@withdecks/sdk

Build live Decks presentations from code with a typed, resource-oriented API.

npm install @withdecks/sdk

Create an API key in Decks → Settings → API, then build a polished deck in one atomic request—without calculating slide coordinates:

import { Decks, templates } from '@withdecks/sdk';

const client = new Decks(process.env.DECKS_API_KEY);

const deck = await client.decks.create({
  title: 'Q3 board update',
  slides: [
    templates.title({
      eyebrow: 'Board update',
      title: 'A stronger quarter',
      subtitle: 'Revenue grew 40% while churn fell.',
    }),
    templates.bullets({
      kicker: 'Highlights',
      title: 'What changed',
      items: ['Revenue reached $12M', 'Gross margin expanded', 'Churn fell below 2%'],
    }),
  ],
});

console.log(`Created deck ${deck.id}`);

The quickstart is compiled in CI and synchronized with examples/quickstart.ts.

Resources

• client.decks — create, retrieve, update and delete presentations.
• client.slides — create, list, retrieve, update and delete slides.
• client.layers — create, list, retrieve, edit and delete slide content.
• client.layouts — create reusable layouts and fill named placeholders.
• client.themes — create and apply structured presentation themes.
• client.images — upload local image bytes to Decks-hosted storage.

layers.update({ id, position: { x: 200 } }) merges omitted geometry from a captured layer read; an overlapping write fails so the caller can retry. Updates to rich-text contentJson, including layers.applyOp text replacement, also refresh the stored plainText projection.

For precise control, pass flat typed layers with 1920×1080 geometry:

await client.slides.create({
  deckId: deck.id,
  order: deck.slides.length,
  title: 'Revenue',
  layers: [{
    type: 'bar',
    data: [{ label: 'Q1', value: 8.6 }, { label: 'Q3', value: 12 }],
    dataLabels: true,
    at: { x: 160, y: 260, w: 1600, h: 650 },
  }],
});

Reliable requests

Safe reads and idempotent writes retry transient network failures, 429, and retryable 5xx responses. Every write receives an idempotency key. Configure the defaults once or override them per call:

const client = new Decks({
  apiKey: process.env.DECKS_API_KEY,
  timeoutMs: 15_000,
  maxRetries: 2,
  fetch: instrumentedFetch,
});

const controller = new AbortController();
await client.decks.retrieve('deck_id', {
  signal: controller.signal,
  timeoutMs: 5_000,
});

All request failures are DecksError instances with stable diagnostic fields:

import { isDecksError } from '@withdecks/sdk';

try {
  await client.decks.retrieve('missing');
} catch (error) {
  if (isDecksError(error)) {
    console.error(error.code, error.status, error.requestId, error.retryAfter);
  }
}

Layer builders

The root package exports typed builders for text, bullets, charts, tables, images, shapes, fills, effects, themes and slide backgrounds. Zod schemas are also exported when runtime validation is useful.

import { text, table, linearGradient, gradientBackground } from '@withdecks/sdk';

Configuration

new Decks({
  apiKey,                              // or DECKS_API_KEY
  baseURL: 'https://withdecks.com',    // optional API gateway override
  appBaseURL: 'https://withdecks.com', // optional upload-host override
  timeoutMs: 30_000,
  maxRetries: 2,
  retryDelayMs: 250,
  fetch: globalThis.fetch,
});

Node.js 20 or newer is required. The package ships ESM, CommonJS and TypeScript declarations and has no runtime dependency other than Zod.

License

Apache-2.0