TypeScript SDK

If your team builds with JavaScript or TypeScript, the SDK is the fastest way to connect an application to freedam. Instead of writing all the low-level plumbing of an API integration yourself - requests, retries, paging through long lists, waiting for jobs to finish - you install one package and every part of the library is a simple method call away.

What it does

@freedam/sdk is the official client for the freedam REST API. It works in all the usual JavaScript environments - Node, Bun, Deno, and the browser - and it is generated directly from the API's own published description, so it always matches what the API actually does.

Everything in the library is right there on the client: assets, collections, uploads, shares, background operations, metadata, webhooks, and more. Because the client is fully typed, your editor autocompletes the available calls and flags a wrong field name while you type, before anything runs.

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 covering every endpoint, the SDK takes care of the chores you would otherwise write yourself:

• Paging made easy. Fetch one page, loop through pages as you need them, or grab everything in one call.
• Uploads as a flow. Start a batch, send your files, then follow along until every file is fully processed.
• Background jobs. Kick off a bulk update or an export, then simply wait for it - the SDK checks progress for you until the job is done.
• Webhook safety. One call verifies that an incoming webhook notification genuinely came from your freedam instance.
• Automatic retries. Temporary network hiccups and server errors are retried for you, and the client automatically slows down when it is asked to - so it plays nicely with the API's speed limits without any extra code.

When something does go wrong, the errors are clear and specific - the SDK tells you whether an asset was not found, a request was rate-limited, or a signature did not check out, so your code can react to each case cleanly.

Good to know

• Access works the same as everywhere else - you create an API token in Settings → API Tokens with exactly the permissions your integration needs. The SDK adds no side doors; a token that cannot edit assets cannot edit them through the SDK either.
• The SDK is young. Versions before 1.0 may occasionally change how things are named - pin your version and read the changelog before upgrading. The API itself stays stable independently.
• Not a TypeScript shop? The API's published description works with standard tools to generate a client in most 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.