{"id":51091080,"url":"https://github.com/makeev/alphai-sdk-ts-examples","last_synced_at":"2026-06-24T02:01:17.099Z","repository":{"id":365383372,"uuid":"1268936611","full_name":"makeev/alphai-sdk-ts-examples","owner":"makeev","description":"Runnable TypeScript examples for the alphai-sdk (AlphaAI financial-news API): news search, ticker feeds, trending, and SEC Form 4 insider data.","archived":false,"fork":false,"pushed_at":"2026-06-17T05:10:57.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T06:23:20.328Z","etag":null,"topics":["ai-agents","alphai","alphai-sdk","examples","financial-news","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://alphai.io/developers","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/makeev.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":null,"dco":null,"cla":null}},"created_at":"2026-06-14T05:31:14.000Z","updated_at":"2026-06-17T05:11:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/makeev/alphai-sdk-ts-examples","commit_stats":null,"previous_names":["makeev/alphai-sdk-ts-examples"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/makeev/alphai-sdk-ts-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk-ts-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk-ts-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk-ts-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk-ts-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makeev","download_url":"https://codeload.github.com/makeev/alphai-sdk-ts-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk-ts-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34713791,"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-24T02:00:07.484Z","response_time":106,"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":["ai-agents","alphai","alphai-sdk","examples","financial-news","sdk","typescript"],"created_at":"2026-06-24T02:01:15.927Z","updated_at":"2026-06-24T02:01:17.078Z","avatar_url":"https://github.com/makeev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# alphai-sdk-ts-examples\n\nRunnable TypeScript examples for [**alphai-sdk**](https://www.npmjs.com/package/alphai-sdk) —\nthe typed client for the [AlphaAI](https://alphai.io) REST API: relevance-scored,\nticker-linked financial news plus SEC Form 4 insider data.\n\nEach script is small, self-contained, and runs against the live API. Together they\ncover the whole SDK surface: the `news.*` and `symbols.*` namespaces, async\npagination, parallel composition, typed errors, and rate-limit inspection.\n\n\u003e The SDK has **zero runtime dependencies** and runs on Node ≥18, browsers, edge,\n\u003e Deno, and Bun. These examples use [`tsx`](https://github.com/privatenumber/tsx)\n\u003e to run TypeScript directly and Node's built-in `.env` loader, so the only\n\u003e dependencies here are dev tooling.\n\n---\n\n## Quick start\n\n```bash\n# 1. install\nnpm install\n\n# 2. add your API key  (get one at https://alphai.io/account/api-keys)\ncp .env.example .env\n#   then edit .env and paste your ak_live_… key\n\n# 3. run any example\nnpm run quickstart\nnpm run dashboard -- TSLA\n```\n\nNo `.env`? Pass the key inline instead:\n\n```bash\nALPHAI_API_KEY=ak_live_… npm run quickstart\n```\n\n---\n\n## The examples\n\n| Script | Command | What it shows |\n| --- | --- | --- |\n| [`01-quickstart.ts`](examples/01-quickstart.ts) | `npm run quickstart` | Construct a client, `news.list()` with filters, read the enriched fields. |\n| [`02-paginate.ts`](examples/02-paginate.ts) | `npm run paginate` | `news.iterate()` async generator with a `maxItems` cap; tally categories while streaming. |\n| [`03-trending.ts`](examples/03-trending.ts) | `npm run trending` | `news.trending()` — top stories of the last 48h. |\n| [`04-ticker-dashboard.ts`](examples/04-ticker-dashboard.ts) | `npm run dashboard` | Compose **four** endpoints in parallel into one report. |\n| [`05-insider.ts`](examples/05-insider.ts) | `npm run insider` | `symbols.insiderSummary()` (decimal-string money) + the insider news feed. |\n| [`06-errors-and-ratelimits.ts`](examples/06-errors-and-ratelimits.ts) | `npm run errors` | Typed error hierarchy + `client.lastRateLimit`. |\n| [`07-symbols.ts`](examples/07-symbols.ts) | `npm run symbols` | `symbols.list()` discovery and `symbols.get()` detail. |\n\nMost scripts take an optional ticker argument:\n\n```bash\nnpm run quickstart -- NVDA\nnpm run dashboard  -- MSFT\nnpm run insider    -- AAPL\n```\n\nType-check everything without running:\n\n```bash\nnpm run typecheck\n```\n\n---\n\n## A real app: the news-alert bot (`alerts/`)\n\nA small, deployable service that turns the SDK into a **financial-news alerting\nbot**. Each poll it fetches the feed for your watchlist, keeps only the unseen\nhigh-relevance stories, and pushes them to **Telegram, Slack, and/or any\nwebhook** — deduplicating across runs so nothing is delivered twice.\n\n```bash\n# Poll once (cron / GitHub Actions friendly), console output:\nnpm run alerts\n\n# Long-lived: poll every POLL_INTERVAL_SECONDS until Ctrl-C:\nnpm run alerts:watch\n\n# See it format real alerts right now, without any tokens:\nnpm run alerts -- --dry-run --backfill=3\n```\n\n**Channels** are configured by env (see [`.env.example`](.env.example)); each is\nactive only when its variables are set. Console output is always on for local\nvisibility, and `--dry-run` keeps everything local.\n\n| Channel | How to enable |\n| --- | --- |\n| **Console** | always on (and the only channel under `--dry-run`) |\n| **Telegram** | `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` (Bot API `sendMessage`, HTML) |\n| **Slack** | `SLACK_WEBHOOK_URL` (Incoming Webhook, `blocks` + fallback text) |\n| **Webhook** | `WEBHOOK_URL` (POSTs `{ \"event\": \"alphai.news.alert\", \"alert\": {…} }`) |\n\n**Tuning** (all optional, with defaults):\n\n| Env | Default | Meaning |\n| --- | --- | --- |\n| `WATCHLIST` | `NVDA,AAPL,MSFT,TSLA` | Tickers to watch, or `trending` for whole-market mode |\n| `MIN_RELEVANCE` | `7` | Minimum relevance score (1–10) to alert |\n| `CATEGORIES` / `EXCLUDE_CATEGORIES` | — | Restrict / drop news categories |\n| `PER_TICKER_LIMIT` | `5` | Max articles per ticker per poll |\n| `POLL_INTERVAL_SECONDS` | `300` | Cadence in `--watch` mode |\n| `STATE_FILE` | `.alerts-state.json` | Where the seen-uid dedup state is stored |\n| `FIRST_RUN_BACKFILL` | `0` | On first run, deliver N newest; the rest seed silently |\n\n**First-run behavior.** With no state file yet, the bot establishes a *baseline*\n— it marks current articles as seen **without** alerting, so you don't get blasted\nwith the backlog. Pass `--backfill=N` (or `FIRST_RUN_BACKFILL`) to deliver the N\nnewest on that first run instead.\n\nHow the pieces fit:\n\n```\nalerts/\n├── index.ts      # orchestration: poll → filter unseen → deliver → persist; once or --watch\n├── config.ts     # env + CLI flags → typed AppConfig\n├── store.ts      # SeenStore: capped, persisted set of delivered article UIDs (dedup)\n├── format.ts     # RichNewsArticle → normalized Alert → per-channel renderers\n└── notifiers.ts  # Console / Slack / Telegram / Webhook (native fetch, zero deps)\n```\n\nDeploy it on a cron (`npm run alerts` every few minutes) or run `npm run\nalerts:watch` as a long-lived process under your supervisor of choice.\n\n---\n\n## The 30-second version\n\n```ts\nimport { AlphaAI } from \"alphai-sdk\";\n\nconst client = new AlphaAI(); // reads ALPHAI_API_KEY from the environment\n\n// One page of NVDA news, only the high-relevance items.\nconst page = await client.news.list({ symbol: \"NVDA\", minRelevance: 7 });\nfor (const article of page.results) {\n  console.log(`[${article.enrichment.relevance_score}] ${article.original.title}`);\n}\n\n// Auto-paginate — the generator follows next_cursor for you.\nfor await (const a of client.news.iterate({ symbol: \"NVDA\", maxItems: 100 })) {\n  // …\n}\n\n// Compose endpoints in parallel.\nconst [detail, sentiment, insider] = await Promise.all([\n  client.symbols.get(\"AAPL\"),\n  client.symbols.sentimentSummary(\"AAPL\"),\n  client.symbols.insiderSummary(\"AAPL\"),\n]);\n```\n\n---\n\n## Things worth knowing\n\n- **Money is decimal strings.** Fields like `buy_value_usd` and `net_value` are\n  returned as strings (e.g. `\"1284500.00\"`) and never coerced to `number` — JS\n  floats lose precision on large dollar amounts. Use a big-decimal library if you\n  need arithmetic. Timestamps are ISO 8601 strings (no auto-`Date`).\n- **`Symbol` type shadows the global.** The symbol model is exported as `Symbol`.\n  Alias it when importing: `import type { Symbol as AlphaSymbol } from \"alphai-sdk\";`\n- **Retries are automatic.** Idempotent GETs retry on 429 / 5xx / network errors\n  with exponential backoff (configurable `maxRetries`, default 2; `0` to disable).\n- **Rate limits** are per account and two-layer — a per-minute burst plus a\n  per-day volume cap (Free 20/min + 100/day · Basic 60/min + 10,000/day ·\n  Pro 300/min + 100,000/day). Read `client.lastRateLimit` after any keyed call;\n  the `X-RateLimit-*` headers report the daily layer, which resets at 00:00 UTC.\n- **Never commit your key.** `.env` is git-ignored; only `.env.example` is tracked.\n\n## Links\n\n- SDK on npm — https://www.npmjs.com/package/alphai-sdk\n- AlphaAI — https://alphai.io\n- API keys — https://alphai.io/account/api-keys\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-sdk-ts-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakeev%2Falphai-sdk-ts-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-sdk-ts-examples/lists"}