TypeScript SDK

The Node.js 22+ SDK is implemented and tested locally. It is not published to npm yet, and production API access is not generally available. Do not ask an agent to install an assumed public package. MCP and the installable agent skill are separate deliverables, not included in this SDK.

Download and install

The documentation build includes SDK and MCP downloads and a machine-readable manifest. These files become public when this documentation release is deployed; they are not an npm registry release. Choose @csfolder/sdk from the manifest, download its url from the same trusted documentation origin, and compare the file’s SHA-256 and byte count with the manifest before installing it in your server project:

npm install --ignore-scripts /absolute/path/to/downloaded-sdk.tgz

Archive URLs contain their content digest. Save the archive and your lockfile for reproducible installs: old URLs are not guaranteed to remain after a docs upgrade. The manifest also hashes the exact /openapi.json bytes. Checksums detect corruption, not a compromised origin; this is not a signed release manifest. Installation may fetch the package’s pinned public runtime dependencies.

Build from source (maintainers)

From a trusted checkout of CSFolder:

pnpm --filter @csfolder/sdk pack --out /absolute/path/csfolder-sdk-0.1.0.tgz

Packing builds and generates the client types from the current OpenAPI contract. Install that artifact in your application’s server package:

pnpm add /absolute/path/csfolder-sdk-0.1.0.tgz

First typed request

Set CSFOLDER_API_KEY in your server environment through its secret manager. Never put the key in a prompt, URL, browser component or public environment variable.

import { CSFolderClient } from '@csfolder/sdk';

const api = new CSFolderClient();
const { data: items } = await api.request('listItems', {
  query: { q: 'AK-47', limit: 10 },
});
if (items[0]) {
  const quotes = await api.request('getMarketPrices', {
    params: { item_id: items[0].item_id },
  });
  // quotes.data.asks / bids: integer USD cents, nullable source timestamps.
}

JSON operations use request(operationId, input). The SDK validates requests and responses against the shared contract; use OpenAPI for available fields. It preserves missing values and decimal strings. Private portfolios still require an owner-authorized personal token.

The default origin is https://api.csfolder.com. For a local API, explicitly set baseUrl: 'http://127.0.0.1:PORT' and allowLocalhost: true. Alternate remote origins and redirects are rejected.

Pagination with a budget

for await (const page of api.pages(
  'listItems',
  { query: { limit: 100 } },
  { maxPages: 5 },
)) {
  // Process page.data; save page.meta.next_cursor if more data remains.
}

maxPages is required (1–100). Reaching the budget does not mean the catalog is complete. Filters are preserved; repeated cursors are rejected. Each page has its own request deadline. Pass an AbortSignal to cancel traversal. The SDK has no shared data cache; private responses must never be cached across credentials.

Full market snapshots

Use api.streamMarketSnapshot({ signal }) for full-market exports. It yields typed start, item, and end records. Process rows into staging storage; promote the dataset only after the loop completes successfully. An early break, abort or exception requires discarding staging data.

The client verifies schema, UTF-8, ascending IDs, generation/request ID/count, a 256 KiB record limit and clean EOF. It emits end only after EOF. Streaming is not retried automatically. The default total deadline is 120 seconds, including consumer processing; timeoutMs can lower it.

Errors and request limits

JSON requests default to 15 seconds and an 8 MiB decoded response limit. Retries are disabled by default; maxRetries: 1 or 2 permits bounded 429/503 retries that respect Retry-After and the remaining deadline. Monthly quota exhaustion is never retried automatically. Each retry may consume quota.

Catch CSFolderError and inspect code, status, requestId and retryAfterSeconds. Messages are sanitized and do not repeat raw server details. See limits and errors.

For an AI-generated project, ask it to use this SDK on the server, preserve data semantics, and test empty history, access denial, quota exhaustion and interrupted exports. A generated interface does not create missing historical data or authorize deployment.