Connecting your application to freedam through the TypeScript SDK saves you from hand-rolling the boring parts of an API integration: HTTP plumbing, retries, pagination, polling loops, and webhook signature verification. You install one package, construct a client with your instance URL and a token, and every resource in the library is a typed method call away.

What it does

@freedam/sdk is the official client for the freedam REST API. It runs in Node 18+, Bun, Deno, and modern browsers, and it is generated from the same OpenAPI specification the API serves at /docs/api.json — so its request and response types stay aligned with the live API rather than drifting behind it.

Every API resource is a property on the client: assets, collections, uploads, shares, operations, metadata, webhooks, embeds, consents, and tokens. Methods accept typed bodies and return typed responses, which means your editor catches a wrong field name before your integration does.

import { FreedamClient } from '@freedam/sdk';

const client = new FreedamClient({
    baseUrl: 'https://your-instance.example.com',
    token: process.env.FREEDAM_TOKEN!,
});

const { data } = await client.assets.list({ per_page: 50 });

How it works

Beyond raw endpoint coverage, the SDK ships the helpers you would otherwise write yourself:

• Pagination, three ways. list fetches one page; listPages is an async iterator that yields a page at a time; listAll eagerly collects everything when the total is bounded.
• Uploads as a flow. createBatch, then uploadFile or uploadFiles, then getBatchStatus to follow ingestion until it completes.
• Long-running operations. Create a bulk update or export with an idempotency key, then call operations.waitForCompletion(id) — the SDK polls until the operation reaches a terminal state, with configurable interval and timeout.
• Webhook verification. verifyWebhookSignature checks the HMAC-SHA256 signature and timestamp on incoming deliveries and throws a typed FreedamSignatureError on mismatch or staleness.
• Retries and rate limits. The client retries network errors and 5xx responses up to three times by default with exponential back-off, and honours the Retry-After header on 429 responses, so it behaves well against the per-token rate limit without extra code.

Errors are typed too: FreedamApiError carries the status, code, and details, plus convenience getters like isNotFound and isRateLimited; FreedamTimeoutError and FreedamSignatureError cover the other failure modes, and all three share a FreedamError base class for generic handling.

Good to know

• Authentication is the standard API token — created in Settings → API Tokens with exactly the scopes your integration needs. The SDK adds nothing to the permission model; a token without assets:write cannot update assets through the SDK either.
• The SDK is currently 0.x. While pre-1.0, minor versions may include breaking changes — pin a tilde range (for example ~0.2.0) and read the changelog before upgrading. The API itself is versioned independently and stays stable within v1.
• Not a TypeScript shop? The OpenAPI 3.1 spec at /docs/api.json works with standard generators like openapi-generator or Kiota to produce a client in other languages.

The full method reference and usage patterns are in the API documentation. Want a live instance to point the client at while you build? Try the demo.