Skip to navigation

SDK

The TypeScript SDK for API v2. It finds the API host from the key.
View as Markdown
The package @cloudraker/sdk is not published yet.

The SDK has no runtime dependency. It runs in Node 20 or later, Bun, Deno, browsers and Cloudflare Workers.

Find the API host

Each organization has its own API host. A crk_ key contains the slug, so the SDK finds the host from the key.

import { baseUrlFromKey, parseKey } from '@cloudraker/sdk'
parseKey(process.env.CRK_API_KEY!)
// { env: 'test', slug: 'acme' }
baseUrlFromKey(process.env.CRK_API_KEY!)
// https://acme.cloudraker.run

A crt_ token or a JWT does not contain the slug. Set the slug option:

baseUrlFromKey(token, { slug: 'acme' })

A live key and a test key use the same host.

A credential or a slug with a wrong format causes a KeyError. The message never contains the credential.

error.codeCause
invalid_api_keyA crk_ key with a bad format, or a credential that is not crk_, crt_ or a JWT.
invalid_tokenA crt_ token with a bad format.
invalid_slugThe slug option is not a valid slug.
slug_requiredA crt_ token or a JWT with no slug option.
slug_mismatchThe slug option is not the slug of the crk_ key.

Timeouts

The default request timeout of the SDK client is 100 seconds. A call with a wait also has a timeout of at least wait plus 10 seconds.

The client sends one Idempotency-Key per POST call and uses the same key for each retry of the call. Read Idempotency.

Wait for a job

jobs.wait() waits for a job until the job ends. Each call uses Prefer: wait=55 or less, so a 60-second proxy does not cut it. It uses the Retry-After value. Read Sync and async.

Read a stream

The stream reader parses the server-sent events of a job and resumes with Last-Event-ID after a cut connection. Read Streaming.

Verify a webhook

verifyWebhook({ rawBody, signature, endpointUrl, slug }) verifies the JWT in x-cr-signature. It uses RS256 and the JWKS of your organization, and keeps a cache of the keys by kid. It checks iss, aud, exp with a clock skew of 60 seconds, and body_sha256. It refuses the HMAC form t=,v1=. Read Webhooks.

Other environments

To use another API host, set the baseUrl option of the client. Do not call baseUrlFromKey.