diff --git a/README.md b/README.md index cbc9049..c664197 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,12 @@ # SEC API JavaScript SDK -`@secapi/sdk-js` is an ESM JavaScript and TypeScript client for retrieving SEC filings, filing sections, financial statements, and ownership data from [SEC API](https://secapi.ai/developers). +`@secapi/sdk-js` is the JavaScript and TypeScript client for retrieving source-backed SEC filings, filing sections, financial statements, and ownership data. -[Documentation](https://docs.secapi.ai) · [Get an API key](https://secapi.ai/signup) · [Support](https://github.com/secapi-ai/secapi-js/issues) · [Status](https://status.secapi.ai) - -## Start here - -Install the package and set an API key in server-side configuration: +## Install and retrieve a filing ```bash npm install @secapi/sdk-js -export SECAPI_API_KEY="secapi_live_..." +export SECAPI_API_KEY="secapi_..." ``` Create `first-request.mjs`: @@ -21,16 +17,23 @@ import { SecApiClient } from "@secapi/sdk-js" const client = new SecApiClient() const filing = await client.agentLatestFiling({ ticker: "AAPL", form: "10-K" }) -console.log(filing.accessionNumber) +console.log({ + accessionNumber: filing.accessionNumber, + filingDate: filing.filingDate, + filingUrl: filing.filingUrl, + requestId: filing.requestId, +}) ``` -Run `node first-request.mjs`. It prints the accession number for the latest matching Apple 10-K; this live value changes when a newer filing is available. `agentLatestFiling()` requests the endpoint's `agent` view. Use `latestFiling()` for the default endpoint response. +Run `node first-request.mjs`. It prints the current filing identity and request ID for Apple's latest matching 10-K. Those live values can change when a newer filing is available. -**Compatibility and support:** REST calls require Node.js 18 or newer. `streamFilings()` requires a global `WebSocket` (Node.js 21+, Bun, Deno, or browsers); Node.js 18 callers need a polyfill or a newer runtime. Read the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) for API details, and [open an issue](https://github.com/secapi-ai/secapi-js/issues) for SDK support. +`SecApiClient` sends `SECAPI_API_KEY` as `x-api-key` to `https://api.secapi.ai`. It wraps public REST endpoints; use the [hosted MCP server](https://docs.secapi.ai/mcp-install) separately when your client supports MCP. Keep API keys in server-side configuration and do not use a machine key as an `Authorization: Bearer` token. -## Common requests +## Compatibility and support + +Node.js 18 or newer is required. `streamFilings()` needs a global `WebSocket` (Node.js 21+, Bun, Deno, or browsers); Node.js 18 callers need a polyfill or newer runtime. See the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) and [API reference](https://docs.secapi.ai/api-reference), check [status](https://status.secapi.ai), or [open an SDK issue](https://github.com/secapi-ai/secapi-js/issues). -The client also resolves issuers, searches filings, extracts sections, and returns normalized statements: +## Common requests ```js const company = await client.resolveEntity({ ticker: "AAPL", view: "agent" }) @@ -54,15 +57,9 @@ const incomeStatements = await client.agentStatement("income_statement", { }) ``` -Flat methods are the complete interface. Grouped aliases, including `client.filings.latest()` and `client.sections.latest()`, are available when they make editor discovery clearer. - -## Factor response modes - -Use `response_mode: "compact"` when you want the smallest useful payload. Compact catalog responses still include readiness/proof summaries. Set `include: "trust"` only when you need the full trust/provenance envelope plus full methodology/materialization/revision/source-rights objects for citations or checks. For catalog/tool-discovery calls, start narrow with `category` and `limit`; the full trust envelope can be larger than a simple picker payload. +Use `latestFiling()` for the default endpoint response and `agentLatestFiling()` for the endpoint-supported `agent` view. Preserve returned filing identifiers and request IDs with derived output. -## Configuration - -`new SecApiClient()` reads `SECAPI_API_KEY` and sends it in the `x-api-key` header. `SECAPI_BASE_URL` and `SECAPI_API_BASE_URL` can override the default API origin, `https://api.secapi.ai`. +## Configuration, errors, and pagination Pass values directly when environment variables are not appropriate: @@ -73,29 +70,7 @@ const client = new SecApiClient({ }) ``` -Keep API keys out of browser bundles and client-side configuration. The SDK also accepts a bearer token for signed-in account endpoints through `bearerToken` or `SECAPI_BEARER_TOKEN`. - -## Errors and pagination - -API failures throw `SecApiError`, which includes `status`, `code`, and `requestId` when the service supplied one. Include the request ID in a support report. - -Cursor-backed endpoints can be consumed as async iterators: - -```js -for await (const filing of client.paginateFilings({ - ticker: "AAPL", - form: "10-K", - limit: 100, -})) { - console.log(filing.accessionNumber) -} -``` - -Read methods (`GET`, `HEAD`, and `OPTIONS`) retry network errors and HTTP `408`, `429`, `502`, `503`, and `504` within a bounded policy. A `429` that the API does not mark non-retryable is retried for every method by default, including mutations; pass `retry: false` per call to disable it, or set it on the client to disable retries by default. Other mutation retries require `{ retry: { enabled: true, idempotencyKey: "..." } }`; use that only with a stable key and replay-safe application handling. See the [SDK reliability guide](https://docs.secapi.ai/sdk-reliability) for retry and streaming details. - -## Reference - -See the [JavaScript SDK guide](https://docs.secapi.ai/javascript-sdk) for endpoint behavior and the [API reference](https://docs.secapi.ai) for parameters and response fields. +`SECAPI_BASE_URL` and `SECAPI_API_BASE_URL` can override the default origin. API failures throw `SecApiError`, including `status`, `code`, and `requestId` when supplied. Cursor-backed endpoints can be consumed as async iterators; see the [SDK reliability guide](https://docs.secapi.ai/sdk-reliability) for retry and streaming behavior. ## License