{"id":51091090,"url":"https://github.com/makeev/alphai-ts-sdk","last_synced_at":"2026-06-24T02:01:25.192Z","repository":{"id":364697660,"uuid":"1268896111","full_name":"makeev/alphai-ts-sdk","owner":"makeev","description":"A typed, ergonomic TypeScript client for the AlphaAI.io REST API","archived":false,"fork":false,"pushed_at":"2026-06-14T05:54:38.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T06:22:27.070Z","etag":null,"topics":["ai-agents","alphai","api-client","financial-news","market-data","mcp","news-api","sdk","sec-form-4","stock-market","trading","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":"CHANGELOG.md","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-14T04:07:36.000Z","updated_at":"2026-06-14T05:54:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/makeev/alphai-ts-sdk","commit_stats":null,"previous_names":["makeev/alphai-ts-sdk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/makeev/alphai-ts-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-ts-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-ts-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-ts-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-ts-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makeev","download_url":"https://codeload.github.com/makeev/alphai-ts-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-ts-sdk/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","api-client","financial-news","market-data","mcp","news-api","sdk","sec-form-4","stock-market","trading","typescript"],"created_at":"2026-06-24T02:01:23.101Z","updated_at":"2026-06-24T02:01:25.180Z","avatar_url":"https://github.com/makeev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# alphai-sdk\n\nA typed, ergonomic TypeScript client for the [AlphaAI](https://alphai.io) REST API —\nrelevance-scored, ticker-linked financial news plus SEC Form 4 insider data, built\nfor AI agents and trading bots.\n\n- **Fully typed** — hand-written types for every endpoint, money kept as precise\n  decimal strings, timestamps as ISO 8601 strings.\n- **Runs everywhere** — Node ≥18, browsers, edge runtimes, Deno, and Bun. Uses the\n  native `fetch`; **zero runtime dependencies**.\n- **Ergonomic** — resource namespaces (`client.news.*`, `client.symbols.*`), async\n  iterators for pagination, automatic retries with backoff, typed errors, and\n  rate-limit inspection.\n- **Dual module** — ships ESM + CJS with `.d.ts`.\n\n\u003e Wraps the 9 documented public REST endpoints 1:1. API-key management (create /\n\u003e revoke) happens on the website at `/account/api-keys` — this SDK only *consumes* a key.\n\n## Install\n\n```bash\nnpm install alphai-sdk\n```\n\nRequires Node ≥18 (for global `fetch`), or any browser / edge / Deno / Bun runtime\nthat provides `fetch`.\n\n## Authentication\n\nGet an API key from [alphai.io/account/api-keys](https://alphai.io/account/api-keys).\nPass it explicitly, or set the `ALPHAI_API_KEY` environment variable and let the\nclient pick it up.\n\n```ts\nimport { AlphaAI } from \"alphai-sdk\";\n\n// Explicit:\nconst client = new AlphaAI({ apiKey: \"ak_live_…\" });\n\n// Or from process.env.ALPHAI_API_KEY:\nconst client = new AlphaAI();\n```\n\nIf no key is found, the constructor throws `MissingAPIKeyError`.\n\n## Quickstart\n\n```ts\nimport { AlphaAI } from \"alphai-sdk\";\n\nconst client = new AlphaAI();\n\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\n## Usage\n\n### News\n\n```ts\n// One page of the main feed (newest first). Filter by ticker, category, relevance.\nconst page = await client.news.list({\n  symbol: \"NVDA\",\n  category: [\"earnings\", \"insider\"], // single value, array, or CSV string\n  excludeCategories: [\"crypto\"],\n  minRelevance: 7,                   // 1–10\n  collapseStories: true,             // collapse reprints into one story\n  cursor,                            // opaque cursor from a previous page\n});\nconsole.log(page.results, page.next_cursor);\n\n// Auto-pagination — follows next_cursor until the feed ends.\nfor await (const article of client.news.iterate({ symbol: \"NVDA\", maxItems: 100 })) {\n  // …\n}\n\n// Trending: up to 10 ranked stories from the last 48h (not paginated).\nconst trending = await client.news.trending();\n\n// Insider feed (SEC Form 4 + institutional stakes).\nconst insider = await client.news.insider({ symbol: \"NVDA\" });\nfor await (const article of client.news.iterateInsider({ symbol: \"NVDA\" })) {\n  // …\n}\n\n// A single article by its 16-char hex uid, and related articles (≤6).\nconst article = await client.news.get(\"a1b2c3d4e5f60718\");\nconst related = await client.news.related(\"a1b2c3d4e5f60718\");\n```\n\n### Symbols\n\n```ts\n// All active tickers, alphabetical (~10k). Page with limit/offset.\nconst symbols = await client.symbols.list({ limit: 500, offset: 0 });\n\n// Symbol detail (throws NotFoundError for an unknown ticker).\nconst aapl = await client.symbols.get(\"AAPL\");\n\n// Crypto + foreign listings are supported too. Each Symbol carries multi-market\n// metadata: asset_type (\"Stock\" | \"ETF\" | \"Crypto\"), country, currency, and\n// supports_insider (US SEC names only). Crypto is \"\u003cSYM\u003e-USD\"; foreign uses the\n// Yahoo suffix (e.g. \"VOD.L\").\nconst btc = await client.symbols.get(\"BTC-USD\");\nconsole.log(btc.asset_type, btc.currency, btc.supports_insider); // \"Crypto\" \"USD\" false\n\n// 7-day AI sentiment rollup (excludes Form 4).\nconst sentiment = await client.symbols.sentimentSummary(\"AAPL\");\n\n// 30-day Form 4 rollup. Money fields are decimal STRINGS.\nconst insider = await client.symbols.insiderSummary(\"AAPL\");\nconsole.log(insider.buy_value_usd); // e.g. \"1284500.00\" — a string, not a number\n```\n\n\u003e **Type-name note:** the symbol model is exported as `Symbol`, which shadows the\n\u003e JavaScript global. Alias it on import if needed:\n\u003e `import type { Symbol as AlphaSymbol } from \"alphai-sdk\";`\n\n### Money \u0026 timestamps\n\nMonetary fields (`buy_value_usd`, `sell_value_usd`, `net_value`) are **decimal\nstrings** and are never coerced to `number` — JavaScript floats lose precision on\nlarge dollar amounts. If you need arithmetic, feed them to a big-decimal library.\nTimestamps are ISO 8601 **strings** (no automatic `Date` conversion).\n\n## Pagination\n\n`iterate()` and `iterateInsider()` return an `AsyncGenerator` that follows\n`next_cursor` for you. Bound the work with `maxItems` and/or `maxPages`:\n\n```ts\nfor await (const article of client.news.iterate({ symbol: \"AAPL\", maxItems: 50 })) {\n  // stops after 50 articles (or when the feed ends)\n}\n```\n\nCursors are opaque — never build or parse them; pass `page.next_cursor` straight back\nin as `cursor` to fetch the next page manually.\n\n## Errors\n\nEvery non-2xx response is mapped to a typed error. All extend `AlphaAIError`.\n\n| Class | When | Notable fields |\n|---|---|---|\n| `BadRequestError` | 400 | `.fields` (per-field validation messages) |\n| `AuthenticationError` | 401 | — |\n| `PermissionDeniedError` | 403 | — |\n| `NotFoundError` | 404 | — |\n| `RateLimitError` | 429 | `.retryAfter`, `.limit`, `.remaining`, `.reset` |\n| `ServerError` | ≥500 | — |\n| `AlphaAIAPIError` | other non-2xx | `.status`, `.body`, `.extra` (base for the above) |\n| `AlphaAIConnectionError` | network / timeout / abort | `.cause` |\n| `MissingAPIKeyError` | no key resolved | — |\n\n```ts\nimport { AlphaAI, RateLimitError, NotFoundError } from \"alphai-sdk\";\n\ntry {\n  await client.symbols.get(\"NOPE\");\n} catch (err) {\n  if (err instanceof RateLimitError) {\n    console.log(`Slow down — retry after ${err.retryAfter}s`);\n  } else if (err instanceof NotFoundError) {\n    console.log(\"No such ticker\");\n  } else {\n    throw err;\n  }\n}\n```\n\nThe error parser reads `message` first, then falls back to `detail`, then the raw\nbody — so both the app-layer (`{ message, extra }`) and host-gate\n(`{ detail }`) envelopes are handled.\n\n## Retries\n\nIdempotent GETs are retried automatically on **429**, **5xx**, and network errors —\n`maxRetries` times (default **2**) with exponential backoff and full jitter,\nhonoring the `Retry-After` header on 429s. Each request has a timeout (default\n**30s**) enforced with `AbortController`.\n\n```ts\nconst client = new AlphaAI({\n  maxRetries: 3,\n  backoffFactor: 0.5, // seconds; base for exponential backoff\n  timeout: 15_000,    // ms\n});\n```\n\nPass `maxRetries: 0` to disable retries.\n\n## Rate limits\n\nLimits are per account, hourly, sliding window: **Free 100 / Basic 1000 / Pro 10000**\nrequests per hour. Every keyed response carries `X-RateLimit-Limit`,\n`X-RateLimit-Remaining`, and `X-RateLimit-Reset` (epoch seconds). The SDK captures\nthem after each call:\n\n```ts\nawait client.news.list({ symbol: \"NVDA\" });\nconsole.log(client.lastRateLimit); // { limit: 1000, remaining: 998, reset: 1700000000 }\n```\n\nCache-served responses may omit the headers; in that case `lastRateLimit` keeps its\nprevious value.\n\n## Configuration\n\n```ts\nnew AlphaAI({\n  apiKey,                                  // else process.env.ALPHAI_API_KEY\n  baseURL: \"https://api.alphai.io\",        // default\n  timeout: 30_000,                         // ms\n  maxRetries: 2,\n  backoffFactor: 0.5,                      // seconds\n  fetch: customFetch,                      // inject a fetch (tests, proxies, edge)\n  userAgent: \"alphai-sdk-js/0.1.0\",        // default\n});\n```\n\n## Runtime support\n\nWorks anywhere a Web-standard `fetch` is available: Node ≥18, modern browsers, Cloudflare\nWorkers / Vercel Edge, Deno, and Bun. For older or custom runtimes, inject a `fetch`\nimplementation via the `fetch` option.\n\nIn the browser, the `User-Agent` header is a forbidden header name and is dropped by\nthe runtime — that's expected and harmless.\n\n## Examples\n\nRunnable scripts live in [`examples/`](./examples):\n\n- `quickstart.ts` — fetch a news page for a ticker\n- `paginate.ts` — async-iterate the feed with a cap\n- `ticker-dashboard.ts` — compose detail + sentiment + insider + news in parallel\n\n```bash\nALPHAI_API_KEY=ak_live_… npx tsx examples/quickstart.ts\n```\n\nA standalone, fuller set of runnable scripts lives in its own repo:\n[**alphai-sdk-ts-examples**](https://github.com/makeev/alphai-sdk-ts-examples).\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-ts-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakeev%2Falphai-ts-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-ts-sdk/lists"}