@imagineers-cards/sdk

The TypeScript SDK for Cards. Create and manage projects, chain cards, and work items from any product — Cards becomes a database you write to with a single API key.

Install

npm install @imagineers-cards/sdk

Authenticate

The SDK uses the same token the cards CLI stores at login. Mint one at imagineers.cards/cli-token — it starts with cards_pat_. Keep it secret; it grants full read/write to your account.

import { CardsClient } from '@imagineers-cards/sdk';

const cards = new CardsClient({ apiKey: process.env.CARDS_API_KEY! });

Projects

await cards.projects.create({ slug: 'my-app', name: 'My App' });
await cards.projects.list();
await cards.projects.get('my-app');
await cards.projects.update('my-app', { name: 'Renamed' });
await cards.projects.delete('my-app');

A project with subprojects cannot be deleted until its children are removed or reparented — the API returns a 409 and the SDK throws a CardsApiError.

Chain cards

The chain is the project's append-only log of decisions, observations, invariants, questions, and artifacts.

const card = await cards.chain.create('my-app', {
  title: 'We chose Postgres over SQLite for the write throughput',
  kind: 'decision',
  body: 'Alternatives considered…',
});

await cards.chain.list('my-app', { kind: 'decision', limit: 20 });
await cards.chain.get('my-app', card.slug);
await cards.chain.update('my-app', card.slug, { status: 'published' });
await cards.chain.delete('my-app', card.slug);

Work items

Work items are the ephemeral do-and-toss layer parallel to the chain.

const item = await cards.work.create('my-app', {
  title: 'Ship the import flow',
  labels: ['feature'],
});

await cards.work.list('my-app', { status: 'todo' });
await cards.work.update('my-app', item.id, { status: 'done' });
await cards.work.delete('my-app', item.id);

Errors

Every non-2xx response throws a CardsApiError carrying the HTTP status and the request that failed.

import { CardsApiError } from '@imagineers-cards/sdk';

try {
  await cards.projects.create({ slug: 'taken' });
} catch (error) {
  if (error instanceof CardsApiError && error.status === 409) {
    // slug already exists
  }
}

Configuration

| Option | Default | Notes | | --------- | --------------------------------------------- | -------------------------------------- | | apiKey | (required) | A cards_pat_ token. | | baseUrl | https://cards-api.krishnanandb.workers.dev | Point at a local or staging Worker. | | fetch | globalThis.fetch | Inject a custom fetch for old runtimes.|

Runtime support

Dependency-free and runtime-agnostic. Runs on Node 18+, the browser, and Cloudflare Workers — anywhere the global fetch exists.

Publishing

One-time: copy .env.example to .env and paste your npm token (NPM_TOKEN=npm_…). .env is gitignored — the token never gets committed.

./publish.sh            # build and publish the current version to npm
./publish.sh --dry-run  # build and preview the tarball; upload nothing

npm rejects re-publishing an existing version — bump version in package.json first. To release both SDKs together, use the repo-root ./publish.sh.