Skip to main content

SDK quickstart

Status: Current (Scale plan). @warmr/sdk is the official TypeScript SDK for the Warmr Cloud API. It has zero runtime dependencies (it uses the platform fetch and Web Crypto), typed methods for every /v1 route, and it handles the key → org-session exchange — including caching and automatic refresh — for you.

Install

Requires Node ≥ 18 (for global fetch + Web Crypto), Deno, or Bun.

Construct a client

baseUrl, exchangeUrl, and publishableKey are deployment-specific and required — there is no canonical public URL baked in. https://app.warmr.so is a placeholder; substitute your own origin. If exchangeUrl is omitted the SDK falls back to ${baseUrl}/functions/v1/exchange-api-key-for-session, which is only correct when your baseUrl also fronts the Supabase functions. Get these wrong and the first call throws a WarmrAuthError.
The first call triggers the exchange; the session token is then cached and re-exchanged automatically as it nears expiry (and once on any 401).

Register an account

Register a handle once. Credentials and proxies are not accepted here — bring-your-own-fleet keeps those secrets on your Mac.
platform is one of tiktok / instagram / x / reddit / linkedin.

Enqueue a warmup and poll it

See Runs for the full run lifecycle, listing, cancel, and retry.

Post a clip (the three-step flow)

Posting is a signed upload → upload the bytes → confirm → enqueue flow. The SDK does not bundle @supabase/supabase-js; step 2 uses your own copy to push bytes to the signed URL.
If confirm returns 422 upload_object_missing, the upload PUT never landed. That error is recoverable — re-upload the bytes with the signed URL, then confirm again. If the signed token has expired, re-issue with content.uploads.create first.

Errors

Non-2xx /v1 responses throw WarmrApiError with .code, .message, .status, and optional .data. Failed key exchanges throw WarmrAuthError with .code / .status.
Common codes: unauthorized (401), forbidden (403, incl. the airlock and a missing scope), invalid_request (400/422), not_found (404), conflict (409), source_consumed (409), quota_exceeded (413), license_inactive (403), internal (500).

Next

  • Runs — enqueue, batch, list, get, cancel, retry.
  • Schedules — standing recurring cadences.
  • Webhooks — subscribe and verify signatures.
  • Scopes — which scope each method needs.