@szum-io/sdk

Official TypeScript SDK for szum, a chart image API.

Turn a JSON config into an SVG, PNG or interactive embed. Use it in transactional emails, weekly digests, PDF reports, Slack messages, dashboards – anywhere an <img> tag works. No headless browser, no canvas, no client-side JavaScript.

Install

npm install @szum-io/sdk

Server-side only. The SDK sends your API key on every request. Never import it into browser code – save charts server-side and pass the URLs to the client.

Quick start

import { Szum } from "@szum-io/sdk";

const szum = new Szum({ apiKey: process.env.SZUM_KEY! });

const png = await szum.render({
  format: "png",
  theme: "editorial",
  title: "Quarterly Revenue",
  subtitle: "By region, FY 2025",
  marks: [
    {
      type: "barY",
      data: [
        { x: "Q1", y: 4.2, region: "Americas" },
        { x: "Q2", y: 5.1, region: "Americas" },
        { x: "Q1", y: 2.1, region: "EMEA" },
        { x: "Q2", y: 2.8, region: "EMEA" },
      ],
      fill: "region",
    },
  ],
});

Saved charts

Save a config server-side and embed the returned short URL in an <img> tag, or drop the embed URL into an <iframe> for an interactive version (Pro plan):

const chart = await szum.charts.create({
  format: "svg",
  theme: "editorial",
  marks: [
    {
      type: "barY",
      data: [
        { x: "Q1", y: 42 },
        { x: "Q2", y: 58 },
      ],
    },
  ],
});

// Static image: <img src={chart.imageUrl} />
// Interactive embed: <iframe src={chart.embedUrl} />
// Revoke later: await szum.charts.delete(chart.id);

create returns a chart object – { id, source, title, createdAt, updatedAt, sizeBytes, publishedAt, imageUrl, embedUrl, configUrl } – and the same shape comes back from get, update, rename, and each item of list. imageUrl (https://szum.io/c/<id>) renders the same image on every fetch; append .png/.svg to force a format. embedUrl (https://szum.io/e/<id>) serves an interactive HTML page with tooltips, legend toggle, and responsive resize. publishedAt is an ISO-8601 timestamp, or null when the chart's public URLs are dark (an API-created chart is published on create, so it's set).

Managing saved charts

Beyond create and delete, the charts resource lets you enumerate and edit:

// List your charts, newest first; page via nextCursor
const { items, nextCursor } = await szum.charts.list({ source: "api" });

// Sort and search; `total` is the exact match count (present only with `q`)
const { items: hits, total } = await szum.charts.list({
  sort: "title", // "created" (default), "updated", or "title"
  q: "revenue", // case-insensitive title substring
});

// Read one chart's metadata, or its config
const chart = await szum.charts.get(id);
const config = await szum.charts.getConfig(id);

// Read many configs in one request (max 100 ids)
const { configs, missing } = await szum.charts.getConfigs([id1, id2]);

// Replace a config in place – same id, same /c/ and /e/ URLs
await szum.charts.update(id, {
  format: "svg",
  marks: [
    /* … */
  ],
});

// Rename – metadata only, no config rewrite, same URLs
await szum.charts.rename(id, "Q3 revenue by region");

list pages via nextCursor (pass it back as cursor; null on the last page). The cursor is keyset-coupled to the active sort, so keep sort stable while paging one result set. Each item also carries hasDraft (the chart has unpublished edits). getConfigs returns { configs, missing }; each missing entry carries a reason – an open set (today "not_found" or "unavailable"), so match the values you handle and treat anything unfamiliar as a non-fatal skip.

Configuration

const szum = new Szum({
  apiKey: process.env.SZUM_KEY!,
  timeout: 30_000, // ms, default 30s
  maxRetries: 2, // default 2; retries 429, 502, 503, 504, and network errors
});

Every method accepts an optional second argument for per-call overrides:

const controller = new AbortController();

await szum.render(config, {
  timeout: 60_000, // override client timeout
  signal: controller.signal, // caller-initiated cancellation
});

Set SZUM_DEBUG=true in your environment to log every request, response status, timing, and retry attempt to stderr.

Error handling

Errors are typed by category. Match by subclass instead of status codes:

import {
  Szum,
  SzumError,
  SzumAuthenticationError,
  SzumRateLimitError,
  SzumInvalidRequestError,
  SzumConnectionError,
} from "@szum-io/sdk";

try {
  await szum.render(config);
} catch (err) {
  if (err instanceof SzumAuthenticationError) {
    // 401 – bad or missing API key
  } else if (err instanceof SzumRateLimitError) {
    // 429 – wait err.retryAfter seconds
  } else if (err instanceof SzumInvalidRequestError) {
    // 400 / 413 – bad config
  } else if (err instanceof SzumConnectionError) {
    // timeout or network error
  } else if (err instanceof SzumError) {
    console.error(err.code); // "api_error", "invalid_request", etc.
    console.error(err.message);
    console.error(err.status); // HTTP status
    console.error(err.retryAfter); // seconds (on 429)
    console.error(err.requestId); // from x-vercel-id – include in support tickets
  }
}

All errors serialize cleanly via JSON.stringify(err) (they implement toJSON), so they work with Sentry, Datadog, and standard loggers.

Exports

| Export | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------- | | Szum | Client class (render; charts.create/list/get/getConfig/getConfigs/update/rename/delete) | | SzumOptions | Constructor options (apiKey, timeout, maxRetries, …) | | RequestOptions | Per-call options (timeout, signal) | | SzumError | Base error (code, status, message, retryAfter, requestId) | | SzumAuthenticationError | 401 | | SzumPermissionError | 403 | | SzumInvalidRequestError | 400 / 413 | | SzumRateLimitError | 429 | | SzumAPIError | 5xx | | SzumConnectionError | Timeout / network | | ChartConfig | Config type for SDK methods (version optional) | | ChartConfigInput | Full config type including required version | | SavedChart | Saved-chart object from charts.create/get/update/rename/list | | SavedChartListItem | A charts.list item: SavedChart plus a listing-only hasDraft flag | | SavedChartSource | Open union of chart origins ("api", "figma", "app", "mcp", …) | | SavedChartSort | charts.list sort order ("created", "updated", "title") | | SavedChartPage | charts.list result (items, nextCursor, optional total) | | SavedChartConfigs | charts.getConfigs result (configs, missing) | | ConfigMissingReason | Open union: why a config was missing ("not_found", "unavailable", …) | | SCHEMA_VERSION | Schema version this SDK was built against |

Documentation

Full reference at szum.io/docs.