TypeScript SDK

npm i @cavsnode/cavs-sdk

Node 18+ (uses global fetch). Ships ESM, CJS and type declarations.

Caution

Don’t confuse it with @orelvis15/cavs-sdk, which is the FFI binding over the Rust chunking engine. This page is about the platform client.

Configure

export CAVS_TOKEN=cavs_ci_...
export CAVS_API=https://cavsnode.com
export CAVS_ORG=acme-ai            # optional default organization

import { CAVS } from '@cavsnode/cavs-sdk';

const client = CAVS.fromEnv();
// or explicitly
const client = new CAVS({
  token: process.env.CAVS_TOKEN,
  api: 'https://cavsnode.com',
  org: 'acme-ai',
});

Upload

const result = await client.artifacts.upload({
  path: './dist/bundle.tar',            // a file or a directory
  project: process.env.CAVS_REPO_ID!,   // the repository UUID — see the note below
  name: 'game-client',
  kind: 'archive',
  version: process.env.GITHUB_SHA!,
  metadata: { branch: process.env.GITHUB_REF_NAME, ci: 'github-actions' },
});

console.log(result.reference, result.version);

project must be the repository UUID

The TypeScript SDK passes project straight into the request path, and the API’s repository routes accept a UUID only. Pass the repository’s UUID, not its slug.

Resolve a slug once and cache it:

const repos = (await client.listRepositories('acme-ai')) as {
  repositories: { id: string; slug: string }[];
};
const repoId = repos.repositories.find((r) => r.slug === 'game-builds')!.id;

(The Python SDK resolves slugs for you; this one does not.)

Dedup stats are not populated yet

result.deduplicationRatio, physicalBytes, logicalBytes and artifactId depend on finalize response fields the deployed API doesn’t return yet — they’ll be undefined. Read real figures from client.usage.get() or GET /repositories/{id}/usage.

Progress and cancellation

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await client.artifacts.upload({
  path: './dist',
  project: repoId,
  name: 'client', kind: 'archive', version: 'nightly',
  onProgress: (done, total) => process.stdout.write(`\r${done}/${total}`),
  signal: controller.signal,
  idempotencyKey: `nightly-${new Date().toISOString().slice(0, 10)}`,
});

Download

Download is not usable against the deployed API yet

client.artifacts.download() always calls GET /api/v1/resolve, which is not deployed. Every call throws NotFoundError, including with an immutable @sha256: reference.

Until /resolve ships, download with the two-step API directly:

const auth = await fetch(
  `${process.env.CAVS_API}/api/v1/repositories/${repoId}/downloads/authorize`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CAVS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ oids: [oid] }),
  },
).then((r) => r.json());

const url = auth.objects[0].download_url;

// Stream to disk, hashing as you go, and verify before renaming.
import { createHash } from 'node:crypto';
import { createWriteStream } from 'node:fs';
import { rename, unlink } from 'node:fs/promises';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

const res = await fetch(url);
const hash = createHash('sha256');
const tmp = `${dest}.part`;

await pipeline(
  Readable.fromWeb(res.body!).map((c: Buffer) => { hash.update(c); return c; }),
  createWriteStream(tmp),
);

if (hash.digest('hex') !== oid) {
  await unlink(tmp);
  throw new Error('checksum mismatch — refusing to write');
}
await rename(tmp, dest);

Never skip the verification step: the oid is the expected hash.

What works against the deployed API

Call	Status
client.me()	✓
client.search(q)	✓
client.listRepositories(org)	✓
client.artifacts.upload(...)	✓ (UUID project; dedup stats absent)
client.artifacts.download(...)	✗ needs /resolve
client.artifacts.list(...)	✓
client.artifacts.get(id) / .versions(id)	✗ needs /artifacts/{id}
client.usage.get()	✓
client.snapshots.list() / .create()	✓
client.releases.list() / .get(tag)	✓
client.lineage.graph() / .addEdge()	✓
client.resolve(ref)	✗ not deployed
client.runs.*	✗ not deployed
client.serviceAccounts.*	✗ not deployed

The rest of the surface

// Registry
const artifacts = await client.artifacts.list({ type: 'archive', limit: 20 });

// Usage
const usage = await client.usage.get();

// Releases
const releases = await client.releases.list(repoId);
const release = await client.releases.get(repoId, 'v1.4.0');

// Snapshots
await client.snapshots.create(repoId, { idempotencyKey: 'monthly-2026-07' });

// Lineage
await client.lineage.addEdge(repoId, {
  fromType: 'artifact', fromKey: buildOid,
  toType: 'artifact',   toKey: sourceOid,
  relation: 'derived-from',
});
const graph = await client.lineage.graph(repoId);

Hashing and URI helpers:

import { sha256File, uri, VERSION } from '@cavsnode/cavs-sdk';

const oid = await sha256File('./dist/bundle.tar');
const parsed = uri.parse('cavs://acme-ai/game-builds/archive/client:1.2.0');

Errors

import {
  CAVSError, AuthenticationError, AuthorizationError, NotFoundError,
  ConflictError, RateLimitError, QuotaExceededError, ChecksumError,
  UploadError, DownloadError, TemporaryServiceError,
} from '@cavsnode/cavs-sdk';

try {
  await client.artifacts.upload({ /* … */ });
} catch (err) {
  if (err instanceof QuotaExceededError) console.error('plan limit hit');
  else if (err instanceof RateLimitError) console.error('throttled');
  else if (err instanceof CAVSError) console.error('CAVS error:', err.message);
  else throw err;
}

Same taxonomy and mapping as the Python SDK, and the same retry policy: 4 attempts on 429/5xx/network, exponential backoff with jitter, honouring Retry-After.

Testing

Inject a fetch implementation:

import { CAVS } from '@cavsnode/cavs-sdk';

const client = new CAVS({
  token: 'cavs_pat_test',
  api: 'https://test',
  fetch: async (input, init) => {
    const url = String(input);
    if (url.endsWith('/api/v1/users/me')) {
      return new Response(JSON.stringify({ user: { id: 'u1', email: '[email protected]' } }), {
        status: 200,
        headers: { 'content-type': 'application/json' },
      });
    }
    return new Response(
      JSON.stringify({ error: { code: 'not_found', message: 'nope' } }),
      { status: 404, headers: { 'content-type': 'application/json' } },
    );
  },
});

In a release script

import { CAVS, sha256File } from '@cavsnode/cavs-sdk';
import { writeFile } from 'node:fs/promises';

const client = CAVS.fromEnv();
const repoId = process.env.CAVS_REPO_ID!;
const version = process.env.GITHUB_SHA!;

const result = await client.artifacts.upload({
  path: './dist/bundle.tar',
  project: repoId,
  name: 'game-client',
  kind: 'archive',
  version,
  metadata: { runner: process.env.RUNNER_OS, ref: process.env.GITHUB_REF },
  idempotencyKey: `release:${version}`,
});

// Pin the exact bytes for downstream consumers.
const oid = await sha256File('./dist/bundle.tar');
await writeFile('release.json', JSON.stringify({ version, oid, reference: result.reference }, null, 2));
console.log(`published ${result.reference} (oid ${oid})`);

Next

• GitHub Actions — this SDK, packaged as a step.
• Python SDK — the same contract, with slug resolution.
• Upload sessions — the underlying choreography.