{"id":50229095,"url":"https://github.com/mgaitan/lobstersgram","last_synced_at":"2026-05-26T17:36:31.552Z","repository":{"id":331049356,"uuid":"1122460029","full_name":"mgaitan/lobstersgram","owner":"mgaitan","description":"A Telegram client for lobste.rs.","archived":false,"fork":false,"pushed_at":"2026-05-21T22:59:49.000Z","size":6191,"stargazers_count":3,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-21T23:52:41.051Z","etag":null,"topics":["bot","lobsters","reading","telegram"],"latest_commit_sha":null,"homepage":"https://mgaitan.github.io/en/posts/lobstersgram-cliente-rapido-lobsters/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgaitan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T19:22:43.000Z","updated_at":"2026-05-21T22:59:52.000Z","dependencies_parsed_at":"2026-04-14T19:01:53.791Z","dependency_job_id":null,"html_url":"https://github.com/mgaitan/lobstersgram","commit_stats":null,"previous_names":["mgaitan/lobstersgram"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mgaitan/lobstersgram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Flobstersgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Flobstersgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Flobstersgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Flobstersgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgaitan","download_url":"https://codeload.github.com/mgaitan/lobstersgram/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgaitan%2Flobstersgram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33532401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","lobsters","reading","telegram"],"created_at":"2026-05-26T17:36:30.677Z","updated_at":"2026-05-26T17:36:31.536Z","avatar_url":"https://github.com/mgaitan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lobstergram: Lobsters → Telegraph → Telegram (Serverless)\n\n[![CI](https://github.com/mgaitan/lobstersgram/actions/workflows/ci.yml/badge.svg)](https://github.com/mgaitan/lobstersgram/actions/workflows/ci.yml)\n\nLobstergram is a fast Telegram client for [lobste.rs](https://lobste.rs). It delivers the hottest Lobsters stories (articles that reached the home page) right into Telegram with a clean telegra.ph reading view.\n\nBot: [@lobstersgram_bot](https://t.me/lobstersgram_bot)\nPost: https://mgaitan.github.io/en/posts/lobstersgram-cliente-rapido-lobsters/\n\nCommands:\n- `/start` to subscribe\n- `/unsubscribe` to stop receiving posts\n\nDemo:\n\n[![Lobstergram demo](https://img.youtube.com/vi/wdzIBFYjJ3Y/hqdefault.jpg)](https://youtube.com/shorts/wdzIBFYjJ3Y?si=yMhLPjz7kDGX_1Wl)\n\n---\n\n## How it works\n\n1. A GitHub Actions workflow runs on a schedule (cron).\n2. It fetches the Lobste.rs \"hottest\" RSS feed (home-page articles only).\n3. New items are detected via a local `state.json` file.\n4. For each new item:\n   - The final article URL is resolved.\n   - The main content is extracted (Readability-style).\n   - A full article page is created on **telegra.ph**.\n   - A Telegram message is sent with:\n     - Title (bold)\n     - Source domain\n     - Link to the Telegraph page\n     - Link to the original article\n     - Link to the Lobsters discussion\n5. The processed item IDs are stored back into `state.json`, which is committed automatically.\n\nNo callbacks, no pagination logic, no bot process running 24/7.\n\n---\n\n## Why Telegraph?\n\nTelegram bots cannot send hidden data or delegate pagination logic to the client.\nAny real “continue reading” flow would require a live bot handling callbacks.\n\nUsing **telegra.ph** gives us:\n\n- Fast, clean, mobile-friendly reading\n- No hosting or storage to maintain\n- Instant article views\n- A perfect fit for “read later” from Telegram\n\n---\n\n## Requirements\n\n- Python 3.11+ (used by GitHub Actions)\n- A Telegram bot token\n- One or more Telegram subscribers (see below)\n- A Telegraph access token\n- Optional: `TELEGRAM_DEV_CHAT_ID` to force sends only to your chat during local testing\n\n## Subscribers\n\nUsers subscribe by sending `/start` to the bot. Run the workflow in `--read-messages`\nmode to fetch pending updates and store subscribers in `subscribers.json`. The normal\nmode sends each post to every subscriber in that file.\n\nAll secrets are stored securely in GitHub Actions.\n\n---\n\n## Setup\n\n### 1. Create a Telegram bot\n\n1. Talk to `@BotFather`\n2. Create a new bot\n3. Save the bot token (`TELEGRAM_BOT_TOKEN`)\n\nTo register subscribers:\n- Send `/start` to the bot from the Telegram account or group you want to receive posts.\n- Run the workflow once (or run `uv run python main.py --read-messages`) to record the\n  `chat_id` values into `subscribers.json`.\n\nFor local development, you can set `TELEGRAM_DEV_CHAT_ID` to force all sends\nto your own chat without touching `subscribers.json`.\n\nTo stop receiving posts, send `/unsubscribe` to the bot and run `--read-messages`\nagain to remove the chat from `subscribers.json`.\n\n---\n\n### 2. Create a Telegraph access token\n\nRun once (locally or in a temporary script):\n\n```python\nimport requests\n\nr = requests.post(\n    \"https://api.telegra.ph/createAccount\",\n    data={\n        \"short_name\": \"lobsters2tg\",\n        \"author_name\": \"Your Name\",\n        \"author_url\": \"https://lobste.rs/\",\n    },\n)\nprint(r.json()[\"result\"][\"access_token\"])\n```\n\nSave the resulting token.\n\n---\n\n### 3. Configure GitHub Secrets\n\nIn your repository:\n\n**Settings → Secrets and variables → Actions**\n\nAdd the following secrets:\n\n- `TELEGRAM_BOT_TOKEN`\n- `TELEGRAPH_ACCESS_TOKEN`\n\n---\n\n### `state.json`\n\nLocal state file used to track already-processed items.\nAutomatically committed by GitHub Actions.\n\n### `subscribers.json`\n\nLocal subscribers file used to store `chat_id` values from `/start`.\nAutomatically committed by GitHub Actions when it changes.\n\n### `.github/workflows/lobsters.yml`\n\nScheduled GitHub Actions workflow that runs the pipeline.\n\n---\n\n## Configuration\n\nOptional environment variables:\n\n- `MAX_ITEMS_PER_RUN` (default: `5`)\n- `REQUEST_TIMEOUT` (default: `20` seconds)\n\nThese can be set directly in the workflow file.\n\n---\n\n## Running manually\n\nYou can trigger the pipeline manually from GitHub:\n\n```\nActions → Lobsters to Telegram → Run workflow\n```\n\nUseful for testing or initial bootstrapping.\n\n---\n\n## Design constraints (by choice)\n\n- ❌ No webhooks\n- ❌ No callback queries\n- ❌ No pagination inside Telegram\n- ❌ No database\n- ❌ No server\n\n- ✅ Stateless execution\n- ✅ Deterministic behavior\n- ✅ Easy to maintain\n- ✅ Easy to extend\n\n---\n\n## Possible extensions\n\n- Attach the full article as an HTML or EPUB file\n- Add other RSS sources\n- Add basic keyword filtering\n- Improve Telegraph HTML fidelity\n- Mirror articles to a static archive\n\nAll without changing the serverless model.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgaitan%2Flobstersgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgaitan%2Flobstersgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgaitan%2Flobstersgram/lists"}