{"_id":"@bluefin-ai/yfin","_rev":"3-7aaecf491664d21dd9d0baf787fba10f","name":"@bluefin-ai/yfin","dist-tags":{"latest":"0.2.0"},"versions":{"0.0.1":{"name":"@bluefin-ai/yfin","version":"0.0.1","license":"MIT","_id":"@bluefin-ai/yfin@0.0.1","maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"homepage":"https://yfin.dev","bugs":{"url":"https://github.com/bluefin-ai/yfin/issues"},"dist":{"shasum":"39937d42f293843fcfa14b1ec0587b8cb5df14c1","tarball":"https://registry.npmjs.org/@bluefin-ai/yfin/-/yfin-0.0.1.tgz","fileCount":3,"integrity":"sha512-eMCTObw0gX+/MUPegCV3k9qmSd2RjQa09/qIz4WaB12HgLe22hfjObQUlWqT6AfoXbdB8bzIHF+4HDUYvrpScA==","signatures":[{"sig":"MEUCIQDq5A2CTZGOrB3xVTPDRb+R4xUW3Z71RfJL3o5DTl7GIwIgFA83+oudPMhn/EJxvQkqDQNUJQeymDkM5TriwMrjy70=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":830},"main":"index.js","_npmUser":{"name":"bluedoor","email":"sam@bluedoor.sh"},"repository":{"url":"git+https://github.com/bluefin-ai/yfin.git","type":"git"},"_npmVersion":"11.5.2","description":"Placeholder for the yfin SDK — reserved, implementation in progress.","directories":{},"_nodeVersion":"23.2.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/yfin_0.0.1_1779891194541_0.32091589458744996","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@bluefin-ai/yfin","version":"0.0.2","license":"MIT","_id":"@bluefin-ai/yfin@0.0.2","maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"homepage":"https://yfin.dev","bugs":{"url":"https://github.com/bluefin-ai/yfin/issues"},"dist":{"shasum":"a38d6f3d3fd6fdc1f2dd412931abdd1772928110","tarball":"https://registry.npmjs.org/@bluefin-ai/yfin/-/yfin-0.0.2.tgz","fileCount":3,"integrity":"sha512-Iza8hPwoWs7KxR2EE6t4xCfytcKxu+uGfwtsxi20jl41LQTJbjqkpiInqO6lFDrtQR1vjgssBcm463SNVX6gEA==","signatures":[{"sig":"MEUCIQCkKLAb76ueiowRti7PvqMxyxL3YoHHfCuQEuM/akhaBAIgQwQjL3lBhnPf1gQiw+ihgZM6pjXUJqBna4vJrADn3iE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":871},"main":"index.js","gitHead":"b1bf06ad8fc345ce09438b68bb0c8cc48f6dea00","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:76868f74-ab04-4285-8e55-4592c43f7033"}},"repository":{"url":"git+https://github.com/bluefin-ai/yfin.git","type":"git","directory":"yfin/npm-placeholder"},"_npmVersion":"11.15.0","description":"Placeholder for the yfin SDK — reserved, implementation in progress.","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/yfin_0.0.2_1779892091616_0.4550091148309514","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@bluefin-ai/yfin","version":"0.2.0","description":"Lightweight TypeScript SDK for yfin: hosted Yahoo Finance quotes, history, options, fundamentals, screeners, and search.","license":"MIT","author":{"name":"yfin","email":"sam@bluedoor.sh"},"homepage":"https://docs.yfin.dev/typescript-sdk","repository":{"type":"git","url":"git+https://github.com/bluefin-ai/fin-services.git","directory":"yfin/typescript"},"bugs":{"url":"https://github.com/bluefin-ai/fin-services/issues"},"keywords":["finance","stocks","market-data","yahoo-finance","quotes","historical-prices","options","fundamentals","typescript","sdk"],"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs","default":"./dist/index.mjs"},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","check":"npm run typecheck && npm test && npm run build && npm pack --dry-run","prepack":"npm run build","test":"vitest run","typecheck":"tsc --noEmit"},"devDependencies":{"@types/node":"^22.15.3","tsup":"^8.4.0","typescript":"^5.8.3","vitest":"^3.1.2"},"_id":"@bluefin-ai/yfin@0.2.0","gitHead":"c62b68b43da506a237e8ed6593665313390a9aba","_nodeVersion":"23.2.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-P3eEeJls0kS24RZEnXfwNNH7nqOZMxWv9hsNonU3WhZhHh66WAYpz9a1GfyejmPorFGwtsAvZ+PIitlRh45mUg==","shasum":"1d8108022c15fac6937afbf1f976bf944c61be7c","tarball":"https://registry.npmjs.org/@bluefin-ai/yfin/-/yfin-0.2.0.tgz","fileCount":10,"unpackedSize":235404,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD44YzErbIVLSSDpAL5Us1D1SSrmVpu2m1Oo7ECoHotQQIhALfCrm9650LmqRUwH2M3z0gHZKNAHRAM6Puhlemqb108"}]},"_npmUser":{"name":"bluedoor","email":"sam@bluedoor.sh"},"directories":{},"maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/yfin_0.2.0_1779911540601_0.46863562622355426"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T14:13:14.418Z","modified":"2026-05-27T19:52:20.887Z","0.0.1":"2026-05-27T14:13:14.702Z","0.0.2":"2026-05-27T14:28:11.762Z","0.2.0":"2026-05-27T19:52:20.743Z"},"bugs":{"url":"https://github.com/bluefin-ai/fin-services/issues"},"license":"MIT","homepage":"https://docs.yfin.dev/typescript-sdk","repository":{"type":"git","url":"git+https://github.com/bluefin-ai/fin-services.git","directory":"yfin/typescript"},"description":"Lightweight TypeScript SDK for yfin: hosted Yahoo Finance quotes, history, options, fundamentals, screeners, and search.","maintainers":[{"name":"bluedoor","email":"sam@bluedoor.sh"}],"readme":"# @bluefin-ai/yfin\n\nLightweight TypeScript SDK for yfin, a hosted Yahoo Finance data API for\nbuilders.\n\nyfin gives you access to Yahoo Finance market data without running your own\nscraper stack: quotes, historical prices, options chains, fundamentals,\nscreeners, symbol search, and market context through product-native namespaces.\nUse it for dashboards, agents, notebooks, research tools, watchlists,\nprototyping, and app backends.\n\nThis SDK is intentionally portable: no runtime dependencies, standard `fetch`,\nESM + CommonJS builds, and bundled TypeScript declarations.\n\nDocs: https://docs.yfin.dev/typescript-sdk\n\n```bash\nnpm install @bluefin-ai/yfin\n```\n\n## Quick Use\n\n```ts\nimport { Client } from \"@bluefin-ai/yfin\";\n\nconst client = new Client();\nconst apple = client.ticker(\"AAPL\");\n\n// Current quote snapshots\nconst quotes = await client.quotes.batch([\"AAPL\", \"MSFT\"]);\n\n// Historical chart data\nconst history = await apple.history({ range: \"5d\", interval: \"1h\" });\n\n// Options chain data\nconst chain = await apple.optionChain();\n\nconsole.log(quotes.data, history.data, chain.data);\n```\n\n## Common Calls\n\n```ts\nawait client.quotes.batch([\"AAPL\", \"MSFT\"]);\nawait client.prices.history(\"AAPL\", { range: \"1mo\", interval: \"1d\", events: \"div,splits,capitalGains\" });\nawait client.options.chain(\"AAPL\", { date: \"2026-01-16\" });\nawait client.fundamentals.get(\"AAPL\", { modules: [\"price\", \"summaryDetail\"] });\nawait client.symbols.search(\"apple\");\nawait client.screeners.default({ count: 25 });\nawait client.screeners.run({\n  size: 10,\n  query: { operator: \"EQ\", operands: [\"sector\", \"Technology\"] },\n});\n```\n\nThe client is organized around yfin product areas: `quotes`, `prices`,\n`options`, `fundamentals`, `financials`, `symbols`, `screeners`, `market`,\n`calendar`, `events`, `research`, and `reference`. Use `client.ticker(\"AAPL\")`\nfor symbol-scoped quote, history, options, fundamentals, financials, metadata,\nand research calls.\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` | `YFIN_BASE_URL` | Override `https://api.yfin.dev`; must be `http` or `https` |\n| `contact` | `YFIN_CONTACT` | Send optional support metadata |\n| `apiKey` | `YFIN_API_KEY` | Send email-verified API credentials |\n| `managementToken` | `YFIN_MANAGEMENT_TOKEN` | Manage API keys after email verification |\n\n`apiKey` is sent as `Authorization: Bearer <key>` by default. Pass\n`apiKeyHeader: \"x-yfin-key\"` to use `X-Yfin-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\nCustom-limit requests are limited to 1 per minute per API key. You can also\nemail `sam@yfin.dev`.\n\nAll successful calls return the hosted yfin envelope:\n\n```ts\ntype YfinEnvelope<TData = unknown> = {\n  data?: TData;\n  meta?: {\n    provider?: string;\n    generated_at?: string;\n    route?: string;\n  };\n};\n```\n\n## Errors\n\nHTTP errors throw `YfinError`. HTTP 429 throws `YfinRateLimitError`; HTTP 503\nthrows `YfinServiceBusyError` after retry exhaustion. Error objects include\n`retryAfterSeconds`, `status`, `code`, `response`, and response headers.\n\n```ts\nimport { Client, YfinRateLimitError, YfinServiceBusyError } from \"@bluefin-ai/yfin\";\n\ntry {\n  await new Client().quotes.get(\"AAPL\");\n} catch (error) {\n  if (error instanceof YfinRateLimitError) {\n    console.log(error.retryAfterSeconds);\n  } else if (error instanceof YfinServiceBusyError) {\n    console.log(\"service busy\", error.retryAfterSeconds);\n  }\n}\n```\n\n## Publishing\n\nThe package is scoped and public:\n\n```bash\nnpm publish --access public\n```\n\nRun the release check first:\n\n```bash\nnpm run check\n```\n","readmeFilename":"README.md","keywords":["finance","stocks","market-data","yahoo-finance","quotes","historical-prices","options","fundamentals","typescript","sdk"],"author":{"name":"yfin","email":"sam@bluedoor.sh"}}