{"id":50571857,"url":"https://github.com/jellydn/sky-alert","last_synced_at":"2026-06-04T19:02:10.895Z","repository":{"id":339315940,"uuid":"1161393843","full_name":"jellydn/sky-alert","owner":"jellydn","description":"Real-time flight monitoring Telegram bot. Track flights, get instant alerts on delays, gate changes, boarding, and more.","archived":false,"fork":false,"pushed_at":"2026-04-17T01:19:38.000Z","size":197,"stargazers_count":3,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T14:56:27.461Z","etag":null,"topics":["bot","flight","telegrambot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jellydn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["jellydn"],"ko_fi":"dunghd","buy_me_a_coffee":"dunghd","polar":"jellydn"}},"created_at":"2026-02-19T03:53:01.000Z","updated_at":"2026-03-21T18:24:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jellydn/sky-alert","commit_stats":null,"previous_names":["jellydn/sky-alert"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jellydn/sky-alert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jellydn%2Fsky-alert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jellydn%2Fsky-alert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jellydn%2Fsky-alert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jellydn%2Fsky-alert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jellydn","download_url":"https://codeload.github.com/jellydn/sky-alert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jellydn%2Fsky-alert/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33916321,"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":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","flight","telegrambot"],"created_at":"2026-06-04T19:02:09.820Z","updated_at":"2026-06-04T19:02:10.889Z","avatar_url":"https://github.com/jellydn.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jellydn","https://ko-fi.com/dunghd","https://buymeacoffee.com/dunghd","https://polar.sh/jellydn","https://paypal.me/dunghd","https://www.buymeacoffee.com/dunghd"],"categories":[],"sub_categories":[],"readme":"# Welcome to SkyAlert 👋\n\n![Version](https://img.shields.io/badge/version-0.1.0-blue.svg?cacheSeconds=2592000)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jellydn/sky-alert/blob/main/LICENSE)\n[![Twitter: jellydn](https://img.shields.io/twitter/follow/jellydn.svg?style=social)](https://twitter.com/jellydn)\n\n\u003e Real-time flight monitoring Telegram bot. Track flights, get instant alerts on delays, gate changes, boarding, and more.\n\n![SkyAlert Logo](logo.svg)\n\n## Features\n\n- **Track flights** by flight number, natural language, or route (e.g., `DAD to SIN today`)\n- **Real-time alerts** — check-in open, delays, gate changes, boarding, departure, landing, cancellation\n- **Adaptive polling** — every 15 min (far), 5 min (near), 1 min (imminent)\n- **Multi-user** — multiple users can track the same flight with deduplicated API calls\n- **Auto-cleanup** — expired flights are deactivated and removed automatically\n- **Live refresh fallback** — FlightStats-first enrichment, then FlightAware as secondary fallback when data is still low-signal\n\n## Tech Stack\n\n- **TypeScript** + [grammY](https://grammy.dev/) (Telegram Bot framework)\n- **SQLite** (via better-sqlite3 or Drizzle)\n- **[Aviationstack API](https://aviationstack.com/)** for flight data\n\n## Install\n\n```bash\n# Install dependencies\nbun install\n\n# Configure environment\ncp .env.example .env\n# Set BOT_TOKEN and AVIATIONSTACK_API_KEY in .env\n```\n\n## Usage\n\n```bash\n# Run the bot\nbun run start\n```\n\n## Deployment\n\nReady to deploy your bot? Check out the [**Hosting Guide**](HOSTING.md) for detailed instructions on deploying to:\n\n- **Fly.io** (recommended) — with persistent SQLite volume\n- **Render** — simple deployment with disk storage\n- **Railway** — easy setup with volume support\n\nThe guide covers environment variables, database persistence, and troubleshooting.\n\n## Develop\n\n```bash\n# Run in development mode\nbun run dev\n\n# Type-check\nbun run typecheck\n\n# Lint\nbun run lint\n```\n\n### Justfile shortcuts\n\n```bash\njust dev\njust db-generate\njust db-migrate\njust db-studio\n```\n\nNote: `drizzle-kit` SQLite commands rely on `better-sqlite3` at dev time for DB connectivity.\n\n\u003cimg width=\"1179\" height=\"1402\" alt=\"image\" src=\"https://github.com/user-attachments/assets/7482a219-3737-46da-a5c0-9d8cca170a39\" /\u003e\n\u003cimg width=\"1179\" height=\"2429\" alt=\"image\" src=\"https://github.com/user-attachments/assets/fb4d642e-14cf-42bf-92b4-09674128bd91\" /\u003e\n\n## Environment Variables\n\n| Variable                | Description                                                  |\n| ----------------------- | ------------------------------------------------------------ |\n| `BOT_TOKEN`             | Telegram bot token from [@BotFather](https://t.me/BotFather) |\n| `AVIATIONSTACK_API_KEY` | API key from [aviationstack.com](https://aviationstack.com/) |\n\n## Bot Commands\n\n| Command                   | Description                           |\n| ------------------------- | ------------------------------------- |\n| `/start`                  | Welcome message                       |\n| `/track AA123 2026-03-15` | Track a flight                        |\n| `/flights`                | List all tracked flights              |\n| `/status AA123`           | View current flight status + timeline |\n| `/remove AA123`           | Stop tracking a flight                |\n| `/help`                   | Show available commands               |\n\nThe bot also understands natural language:\n\n- `Track my flight GA851 tomorrow`\n- `DAD to SIN today`\n\n## Architecture\n\n```\n┌─────────────────────────────────┐\n│         Telegram Bot            │\n│  (grammY – long polling)        │\n├─────────────────────────────────┤\n│     Message Parser / Router     │\n│  (commands + natural language)  │\n├──────────┬──────────────────────┤\n│ Flight   │  Background Worker   │\n│ Service  │  (adaptive polling)  │\n├──────────┴──────────────────────┤\n│         SQLite Database         │\n│  flights | tracked_flights |    │\n│       status_changes            │\n└─────────────────────────────────┘\n          │\n          ▼\n   Aviationstack API\n          │\n          ▼ (fallback when needed)\n FlightStats parser + FlightAware parser\n```\n\n## Status Refresh, Timeout, and Fallback Rules\n\n### Refresh timing\n\n- `/status` refreshes flight data when either condition is true:\n- Data is stale (`\u003e= 15 minutes` since last poll)\n- Data is low-signal (`scheduled`/empty status and no delay)\n- Polling worker interval by time-to-departure:\n- `\u003e 3h`: every `15 minutes`\n- `\u003c= 3h`: every `5 minutes`\n- `\u003c= 1h`: every `1 minute`\n\n### Caching\n\n- Aviationstack response cache TTL: `15 minutes`\n- Live refresh paths (`/status`, polling worker) bypass cache to force fresh provider data\n\n### Selection timeout\n\n- Multi-result flight selection (route or ambiguous number) expires after `5 minutes`\n- If expired, user must search/select again\n\n### Fallback behavior\n\n- Primary source is Aviationstack\n- Fallback is triggered only when Aviationstack is low-signal:\n- Status is `scheduled` or empty, and delay is missing/non-positive\n- Fallback order:\n- 1) FlightStats (status, delay, estimated departure/arrival, terminal, gate)\n- 2) FlightAware only if status/delay are still low-signal after FlightStats\n- `/status` display prefers live fallback estimated times over derived `scheduled + delay`\n- `/status` also shows arrival terminal/gate when available from fallback data\n- FlightAware fallback tries multiple identifiers (`ICAO`, `IATA`, user input), e.g. `TGW315` then `TR315`\n\n### Known limitations\n\n- If both providers return no delay signal, bot will remain on scheduled/on-time data\n- FlightAware fallback is HTML/bootstrap parsing, not an official FlightAware API\n\n## Author\n\n👤 **Huynh Duc Dung**\n\n- Website: https://productsway.com/\n- Twitter: [@jellydn](https://twitter.com/jellydn)\n- Github: [@jellydn](https://github.com/jellydn)\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n[![ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/dunghd)\n[![paypal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://paypal.me/dunghd)\n[![buymeacoffee](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/dunghd)\n\n## License\n\nMIT © [Huynh Duc Dung](https://productsway.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjellydn%2Fsky-alert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjellydn%2Fsky-alert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjellydn%2Fsky-alert/lists"}