{"_id":"@bluefin-ai/tvfin","_rev":"2-bb1ee9b2c5e89337033ccbfb2f40e425","name":"@bluefin-ai/tvfin","dist-tags":{"latest":"0.2.1"},"versions":{"0.0.1":{"name":"@bluefin-ai/tvfin","version":"0.0.1","license":"MIT","_id":"@bluefin-ai/tvfin@0.0.1","maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"homepage":"https://tvfin.bluedoor.sh","bugs":{"url":"https://github.com/bluefin-ai/fin-services/issues"},"dist":{"shasum":"fc79ad0d425e49f8e02738dff42c5d98af7c92e4","tarball":"https://registry.npmjs.org/@bluefin-ai/tvfin/-/tvfin-0.0.1.tgz","fileCount":3,"integrity":"sha512-jHo8KIRLH2CQ+qOGbFdKmqOz8ycMlS9UfahjTlpW9y8yfzjxxD1GTe7P1vW6bOH+5QAcxQYKTJFydt5U2aGsXg==","signatures":[{"sig":"MEYCIQDKckm/eHBj2cyEm0U6KiYNmdflQb/DG91W07YS01TDAQIhAL0MuqkbhnO4JOnCBOB3z2tLrrsVU4aY8kfrbTHpNmBQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1136},"main":"index.js","gitHead":"133f548a6e6a1275bbe4de11d2d28b66b41e23dc","_npmUser":{"name":"bluedoor","email":"sam@bluedoor.sh"},"repository":{"url":"git+https://github.com/bluefin-ai/fin-services.git","type":"git","directory":"tvfin/tvfin/npm-placeholder"},"_npmVersion":"11.5.2","description":"Placeholder for the tvfin SDK - reserved, implementation pending npm approval.","directories":{},"_nodeVersion":"23.2.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/tvfin_0.0.1_1779996853265_0.6752125638183053","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@bluefin-ai/tvfin","version":"0.2.1","description":"Lightweight TypeScript SDK for tvfin: hosted TradingView symbols, screeners, news, calendars, options, ideas, and scripts.","license":"MIT","author":{"name":"tvfin","email":"sam@bluedoor.sh"},"homepage":"https://docs.tvfin.bluedoor.sh","repository":{"type":"git","url":"git+https://github.com/bluefin-ai/fin-services.git","directory":"tvfin/tvfin/typescript"},"bugs":{"url":"https://github.com/bluefin-ai/fin-services/issues"},"type":"module","sideEffects":false,"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc --outDir dist","check":"npm run typecheck && npm test && npm run build && npm pack --dry-run","prepack":"npm run build","test":"tsc --noEmit -p tsconfig.test.json","typecheck":"tsc --noEmit"},"keywords":["finance","stocks","tradingview","market-data","screeners","news","options","typescript","sdk"],"devDependencies":{"typescript":"^5.6.3"},"gitHead":"56d65e7af34d560afa85698a89aad538f06c50af","_id":"@bluefin-ai/tvfin@0.2.1","_nodeVersion":"22.22.3","_npmVersion":"11.16.0","dist":{"integrity":"sha512-nTqICMl/OlfFfTTmAfzQyJH9jgJH6Nh8hgQY7/tDiqAjCNoFsite3ThMWsA5tFyEdCvMlfEx+VM+zs/4Vx+1Kw==","shasum":"7c22cba4dd9c12252bceef4be3ce4e6de44eee3b","tarball":"https://registry.npmjs.org/@bluefin-ai/tvfin/-/tvfin-0.2.1.tgz","fileCount":18,"unpackedSize":52219,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCE6ogFRpuhtC9CGxn/peJlSvG6QYu4V3hPKP0Fp+YFKAIgUcMxYHaf+hHY3clvxv9kjcgl6lEhQYGao/9+fn7l8rw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b6ad5466-f69c-418b-9945-003b889d3b7e"}},"directories":{},"maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tvfin_0.2.1_1780004997800_0.7948595151956805"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-28T19:34:13.119Z","modified":"2026-05-28T21:49:58.092Z","0.0.1":"2026-05-28T19:34:13.421Z","0.2.1":"2026-05-28T21:49:57.953Z"},"bugs":{"url":"https://github.com/bluefin-ai/fin-services/issues"},"license":"MIT","homepage":"https://docs.tvfin.bluedoor.sh","repository":{"type":"git","url":"git+https://github.com/bluefin-ai/fin-services.git","directory":"tvfin/tvfin/typescript"},"description":"Lightweight TypeScript SDK for tvfin: hosted TradingView symbols, screeners, news, calendars, options, ideas, and scripts.","maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"readme":"# @bluefin-ai/tvfin\n\nLightweight TypeScript SDK for tvfin, a hosted TradingView data API for\nbuilders.\n\ntvfin gives you access to TradingView market data without running your own\nbrowser or scraper stack: symbol search, news, economic calendars, earnings and\ndividend events, screeners, options data, public ideas, and public scripts\nthrough product-native namespaces. Use it for dashboards, agents, notebooks,\nresearch tools, watchlists, prototyping, and app backends.\n\nThis SDK is intentionally portable: no runtime dependencies, standard `fetch`,\nESM builds, bundled TypeScript declarations, automatic transient retries, and a\npublic surface that follows tvfin routes rather than upstream provider endpoint\nnames.\n\nDocs: https://docs.tvfin.bluedoor.sh\n\n```bash\nnpm install @bluefin-ai/tvfin\n```\n\n## Quick Use\n\n```ts\nimport { Client } from \"@bluefin-ai/tvfin\";\n\nconst client = new Client();\n\nconst symbols = await client.symbols.search(\"apple\", { exchange: \"NASDAQ\" });\nconst news = await client.news.forSymbol(\"NASDAQ:AAPL\");\nconst screen = await client.screeners.search(\"america\", { columns: [\"name\", \"close\"], limit: 5 });\nconst chain = await client.options.chain(\"AAPL\", { limit: 10 });\n\nconsole.log(symbols.data, news.data, screen.data, chain.data);\n```\n\n## Common Calls\n\n```ts\nawait client.symbols.search(\"tesla\", { type: \"stock\" });\nawait client.news.headlines({ lang: \"en\" });\nawait client.news.flow({ market: \"stocks\" });\nawait client.calendar.economic({ country: \"US\" });\nawait client.events.earnings({ limit: 25, columns: [\"name\", \"earnings_release_date\"] });\nawait client.screeners.metadata(\"america\");\nawait client.screeners.search(\"america\", { limit: 25, columns: [\"name\", \"close\", \"volume\"] });\nawait client.screeners.global({ markets: \"america,crypto\", limit: 25 });\nawait client.options.impliedVolatility(\"AAPL\");\nawait client.options.underlyingAggregates(\"AAPL\");\nawait client.ideas.list({ symbol: \"AAPL\" });\nawait client.scripts.list({ symbol: \"AAPL\" });\n```\n\nThe client is organized around tvfin product areas: `symbols`, `news`,\n`calendar`, `events`, `screeners`, `options`, `ideas`, `scripts`, and\n`management`.\n\n## Runtime Support\n\nThe package uses the standard Fetch API. In Node, use Node 18+ or pass a custom\nfetch implementation:\n\n```ts\nconst client = new Client({ fetch: myFetch });\n```\n\nConfiguration can come from constructor options or environment variables in\nNode-like runtimes:\n\n| Option | Environment | Purpose |\n| --- | --- | --- |\n| `baseUrl` | `TVFIN_BASE_URL` | Override `https://api.tvfin.bluedoor.sh`; must be `http` or `https` |\n| `contact` | `TVFIN_CONTACT` | Send optional support metadata |\n| `apiKey` | `TVFIN_API_KEY` | Send email-verified API credentials |\n| `managementToken` | `TVFIN_MANAGEMENT_TOKEN` | Manage API keys after email verification |\n\n`apiKey` is sent as `Authorization: Bearer <key>` by default. Pass\n`apiKeyHeader: \"x-tvfin-key\"` to use `X-Tvfin-Key` instead.\n\nThe SDK retries transient `429`, `502`, `503`, and `504` responses by default.\nUse `maxRetries`, `retryStatuses`, `backoffFactorMs`, `maxBackoffMs`, and\n`backoffJitter` when you need tighter control, or set `maxRetries: 0`.\n\nKeep API keys on a server when you do not control the runtime.\n\n## Auth Helpers\n\n```ts\nconst client = new Client();\nawait client.management.requestAuthOtp(\"you@example.com\");\nconst verified = await client.management.verifyAuthOtp(\"you@example.com\", \"123456\", {\n  label: \"agent\",\n});\nconst verifiedData = verified.data as {\n  api_key?: string;\n  management_token?: string;\n};\n\nconst authed = new Client({ apiKey: verifiedData.api_key });\nawait authed.management.requestLimitIncrease({\n  requestedRps: 25,\n  useCase: \"production agent workload\",\n  message: \"Short traffic description.\",\n});\n\nconst managed = new Client({\n  managementToken: verifiedData.management_token,\n});\nconst keys = await managed.management.keys.list();\nconst created = await managed.management.keys.create({ label: \"batch job\" });\nconst createdData = created.data as { key?: { id?: string } };\nif (createdData.key?.id) {\n  await managed.management.keys.rotate(createdData.key.id);\n}\n```\n\nAll successful calls return the hosted tvfin envelope:\n\n```ts\ntype TvfinEnvelope<TData = unknown> = {\n  data?: TData;\n  meta?: {\n    provider?: \"tradingview\";\n    generated_at?: string;\n    route?: string;\n  };\n};\n```\n\n## Errors\n\nHTTP errors throw `TvfinError`. HTTP 429 throws `TvfinRateLimitError`; HTTP 503\nthrows `TvfinServiceBusyError` after retry exhaustion. Error objects include\n`retryAfter`, `status`, `requestId`, and the response payload.\n","readmeFilename":"README.md","keywords":["finance","stocks","tradingview","market-data","screeners","news","options","typescript","sdk"],"author":{"name":"tvfin","email":"sam@bluedoor.sh"}}