Metadata-Version: 2.5
Name: socials-daily
Version: 0.1.0
Summary: Multi-platform social media daily digest CLI
Project-URL: Homepage, https://github.com/bartlomiejcieszkowski/socials-daily
Project-URL: Bug Tracker, https://github.com/bartlomiejcieszkowski/socials-daily/issues
Project-URL: Documentation, https://github.com/bartlomiejcieszkowski/socials-daily#readme
Author-email: Bartlomiej Cieszkowski <bartlomiej.cieszkowski@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Bartlomiej Cieszkowski
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,daily,scraper,social-media,summary
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.12
Requires-Dist: atproto>=0.0.72
Requires-Dist: feedparser>=6.0.14
Requires-Dist: httpx>=0.27.0
Requires-Dist: instaloader>=4.15.3
Provides-Extra: hikerapi
Requires-Dist: hikerapi>=1.8.2; extra == 'hikerapi'
Provides-Extra: xpoz
Requires-Dist: xpoz>=0.8.0; extra == 'xpoz'
Provides-Extra: youtube
Requires-Dist: yt-dlp>=2024.0.0; extra == 'youtube'
Description-Content-Type: text/markdown

# Socials Daily

Fetch recent posts from public social media accounts and generate a daily summary.

## Setup

```bash
uv sync
```

Optional backends:

```bash
uv sync -E hikerapi -E xpoz -E youtube
```

## Usage

1. Edit `accounts.json` — grouped by platform:

```json
{
  "bluesky": {
    "accounts": [{"handle": "bsky.app"}]
  },
  "instagram": {
    "accounts": [{"handle": "natgeo"}, {"handle": "nasa"}]
  }
}
```

Each account can have a custom `limit`:

```json
{
  "bluesky": {
    "accounts": [
      {"handle": "bsky.app"},
      {"handle": "atmos.bsky.social", "limit": 20}
    ]
  },
  "instagram": {
    "accounts": [
      {"handle": "natgeo"}
    ]
  }
}
```

Each platform can override the scraper backend (optional):

```json
{
  "instagram": {
    "backend": "hikerapi",
    "accounts": [
      {"handle": "natgeo"}
    ]
  }
}
```

**Backend resolution** (highest to lowest priority):
1. CLI `--backend` flag (overrides everything)
2. Platform `backend` in `accounts.json`
3. Default mapping (`instagram` → `instaloader`, `bluesky` → `bluesky`, etc.)

2. Run the scraper:

```bash
# Default: Bluesky (free, no auth needed)
uv run python -m socials_daily scrape

# Instagram (free, rate-limited)
uv run python -m socials_daily scrape --backend instaloader

# HikerAPI (pay-per-request, ~$0.0006/request)
uv run python -m socials_daily scrape --backend hikerapi --api-key YOUR_KEY

# Xpoz (pre-indexed data, free tier available)
uv run python -m socials_daily scrape --backend xpoz --api-key YOUR_KEY
```

3. Check the output:

```
output/daily-summary-YYYY-MM-DD.md   # Markdown summary
output/daily-summary-YYYY-MM-DD.json # JSON for programmatic use
```

## Add Accounts

```bash
# Bluesky (default)
uv run python -m socials_daily add bsky.app

# Instagram
uv run python -m socials_daily add natgeo --platform instagram

# With custom limit
uv run python -m socials_daily add atmos.bsky.social --platform bluesky --limit 20

# Set platform backend
uv run python -m socials_daily add natgeo --platform instagram --backend hikerapi
```

## Scrapers

| Backend | Cost | Setup | Best For |
|---|---|---|---|
| `bluesky` | Free | None | Public Bluesky accounts |
| `instaloader` | Free | None | 1-5 Instagram accounts, low volume |
| `reddit` | Free | None | Subreddit posts |
| `rss` | Free | None | Any RSS/Atom feed |
| `youtube` | Free | `uv sync -E youtube` | YouTube channel videos |
| `hikerapi` | ~$0.0006/request | API key | Reliable, high volume |
| `xpoz` | Free tier available | API key | Pre-indexed data, multi-platform |

### Bluesky (default)

Uses Bluesky's public AT Protocol API. No authentication required.

```bash
uv run python -m socials_daily scrape --backend bluesky
```

### Instaloader

Free, open-source Instagram scraper. Rate-limited by Instagram.

### HikerAPI

REST API with 100+ endpoints. No blocks, no rate limits.

```bash
export HIKERAPI_TOKEN=your-key
uv run python -m socials_daily scrape --backend hikerapi
```

### Xpoz

Pre-indexed social data API. Supports Instagram, Twitter, TikTok, Reddit.

```bash
export XPOZ_API_KEY=your-key
uv run python -m socials_daily scrape --backend xpoz
```

### YouTube

Fetches recent videos from YouTube channels. Requires optional `yt-dlp` dependency.

```bash
# Install YouTube support
uv sync -E youtube

# Add a channel (handle or name)
uv run python -m socials_daily add mkbhd --platform youtube

# Scrape
uv run python -m socials_daily scrape
```

### Reddit

Fetches recent posts from public subreddits via Reddit's JSON API. No authentication required.

```bash
# Add a subreddit
uv run python -m socials_daily add programming --platform reddit

# Scrape
uv run python -m socials_daily scrape
```

### RSS

Scrapes any RSS/Atom feed. The `handle` field holds the feed URL.

```bash
# Add an RSS feed
uv run python -m socials_daily add https://www.reddit.com/r/programming/.rss --platform rss

# Scrape
uv run python -m socials_daily scrape
```

## Project Structure

```
accounts.json         # Accounts grouped by platform (with optional backend config)
src/socials_daily/    # Source code
├── __main__.py       # Entry point
└── scrapers/         # Scraper backends
    ├── base.py       # Abstract interface
    ├── bluesky.py
    ├── instaloader.py
    ├── reddit.py     # Reddit JSON API
    ├── rss.py        # RSS/Atom feeds
    ├── youtube.py    # YouTube channel videos
    ├── hikerapi.py
    └── xpoz.py
output/               # Generated daily summaries
pyproject.toml        # Project config (uv)
```

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for a detailed breakdown of the scraper layer, config resolution, deduplication system, and data flow.
