@runstamp/sdk

The only package applications need to install for Runstamp document operations, Document Jobs, the CLI, MCP, and React integrations.

npm install @runstamp/sdk

Requires Node.js 18.14.1 or later. React consumers also install the optional react and react-dom peers. Bundled font files and their license notices ship inside the SDK; no separate Runstamp engine package or repository checkout is required.

Run a bundled local Document Job by its stable ID:

import { runstamp } from "@runstamp/sdk";

const result = await runstamp.jobs.run("runstamp.reports.client-report", request, { artifactDirectory: ".runstamp/jobs" });

The Job result keeps execution success, verification evidence, and delivery readiness separate. Bundled Jobs remain local preview until their named native, visual, and customer acceptance checks pass.

The lower-level compatibility methods (run, runJob, listJobs, and related discovery methods) remain available through the 2.x transition.

For a caller-owned Job definition:

import { readFile } from "node:fs/promises";
import { createArtifactBytes, createRunstamp } from "@runstamp/sdk";

const runstamp = createRunstamp();
const definition = JSON.parse(await readFile("workbook-update.job.json", "utf8"));
const supplied = JSON.parse(await readFile("workbook-update-input.json", "utf8"));
const workbook = createArtifactBytes(
  new Uint8Array(await readFile("source.xlsx")),
  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "xlsx",
);

const validation = await runstamp.validateJob(definition);
if (!validation.ok) throw new Error(JSON.stringify(validation.issues));

const result = await runstamp.runJob(
  {
    definition,
    inputs: { ...supplied.inputs, workbook },
    idempotencyKey: supplied.idempotencyKey,
  },
  { artifactDirectory: ".runstamp/jobs/artifacts", verifyDeclaredView: true },
);

The first-party Job definitions and local runner remain preview capabilities. Each result reports exact output evidence and may remain not_checked until its declared target-application and customer-review checks run.

Discover the eight bundled Jobs before selecting one. Discovery keeps them separate from the stable 79-operation catalog and returns immutable sample paths and hashes.

const jobs = await runstamp.jobs.list();
const workbook = await runstamp.jobs.describe("runstamp.finance.workbook-update");

import { managed, Runstamp } from "@runstamp/sdk";

const runstamp = new Runstamp({
  transport: managed({ apiKey: process.env.RUNSTAMP_API_KEY }),
});

const result = await runstamp.operations.run("common.extract.table-grid", input);

Managed calls submit a durable execution and resolve only after the final common operation result is available. The SDK generates one idempotency key per run() call, polls the execution within a five-minute default wait budget, follows the successful HTTP 307 result redirect automatically for result envelopes up to 192 MiB, and requests best-effort cancellation when the caller aborts. Supply a key when an application retry must reuse the same execution:

const runstamp = new Runstamp({
  transport: managed({
    apiKey: process.env.RUNSTAMP_API_KEY,
    maxWaitMs: 120_000,
  }),
});

const result = await runstamp.operations.run("pdf.validate", input, {
  idempotencyKey: "validate-upload-018f",
  signal: abortController.signal,
});

Managed input transport is automatic. Canonical envelopes through 768 KiB (786,432 bytes) retain the original { input, options } HTTP body, safely below the Managed API's 1 MiB (1,048,576-byte) inline request maximum. Larger requests are canonicalized and hashed, registered under the API key's active environment, uploaded directly to the private Supabase storage hostname with signed non-upsert TUS and 6 MiB resumable chunks, then finalized by content address. The SDK preserves the same idempotency key, abort signal, polling loop, and final OperationResult across both paths. The canonical staged envelope supports up to 192 MiB (201,326,592 bytes), which covers the public 64 MiB decoded-artifact budget plus the separate 64 MiB JSON budget after base64 expansion.

The default local transport includes the frozen stable 79-operation runtime:

import { runstamp } from "@runstamp/sdk";

const result = await runstamp.operations.run("pdf.validate", input, {
  signal: abortController.signal,
  operation: { timeoutMs: 30_000 },
});

Hosts may still pass local({ resolve }) to inject a deliberate implementation set. Descriptor qualifiers are applied by the SDK, so call sites never need to supply dispatch-only options such as operation: "form".

Discovery reports the catalog's explicit per-surface release authority; it never infers availability from a package or domain:

const operations = runstamp.list({ surface: "sdk", states: ["public_ga"] });
const formInspection = runstamp.describe("pdf.inspect.form");

The stable catalog's five OC-1 domains are technical dispatch and error namespaces, not a list of supported formats. (lifecycle is a sixth domain for experimental operations.) Product-facing discovery uses the 12 stable operation families, including delimited data, mail, DITA, JATS, structured tables, review sidecars, and provenance in addition to the native Office and PDF engines:

import { OPERATION_FAMILIES, operationsForFamily } from "@runstamp/sdk/catalog";

const mailOperations = operationsForFamily("mail-message");
const formOperations = runstamp.operations.list({ family: "pdf-acroform" });

PPTX has one complete SDK engine. The internal compact build is not a separate format, product version, or SDK catalog family.

Platform review, approval, release, delivery, webhook, billing, usage, notification, and audit workflows are separately generally available through the authenticated control plane.

Operation and document conditions return typed { ok: false, error, losses, diagnostics } envelopes in both local and managed modes. RunstampTransportError is reserved for network, HTTP-boundary, unavailable-runtime, or host failures. The authenticated Managed API is generally available to active Platform and Enterprise workspaces.