Run a document operation with the Runstamp SDK

The current Runstamp SDK executes named document operations through runstamp.operations.run(). Select a local or managed transport, pass input that matches the named operation, and handle the typed success or failure envelope. PPTX, DOCX, PDF, and XLSX use the same invocation method, but each operation retains its own format-specific input contract.

Install the SDK

npm install @runstamp/sdk

Apps use @runstamp/sdk as the entry point. The local transport runs the stable operations. The managed transport submits the same operation names to a free-trial workspace or an active Platform or Enterprise workspace.

Run a local operation

This complete JavaScript program validates a PDF and prints the supported validation result. It is checked into the repository at examples/sdk/validate-pdf.mjs and runs against the same SDK used by the application.

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

const inputPath = process.argv[2];
if (!inputPath) throw new Error("Usage: node validate-pdf.mjs <input.pdf>");

const input = new Uint8Array(await readFile(inputPath));
const result = await runstamp.operations.run("pdf.validate", input, {
  operation: { timeoutMs: 30_000, lossPolicy: "collect" },
});

if (!result.ok) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}

process.stdout.write(`${JSON.stringify(result.value, null, 2)}\n`);

Run it with a real file:

node examples/sdk/validate-pdf.mjs ./input.pdf

The result envelope separates execution success from document findings. A successful pdf.validate call can report that the file contains validation errors; inspect the operation value instead of treating a resolved promise as proof that the document passed.

Use managed execution

Only the transport changes for managed execution:

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

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-customer-upload-018f",
  operation: { timeoutMs: 30_000, lossPolicy: "collect" },
});

The managed SDK submits a durable execution, polls it to a terminal state, and returns the common operation result. Supply an idempotency key when an application retry must resolve to the same logical execution.

Keep format inputs separate

The SDK provides one invocation method, not one unchanged renderer schema. Use an application-owned business-data model and map it to the contract for each output operation:

An application can reuse customer, invoice, or report data across adapters. The adapters must still produce the correct format-specific inputs. Review the generated operation reference for the installed version before copying a payload into production.

Handle failures and losses

Every operation returns either a success value or a typed error with diagnostics and declared losses. Preserve the operation code and remediation text so callers can distinguish invalid input, resource limits, unsupported features, timeouts, and host failures.

if (!result.ok) {
  console.error(result.error.code, result.error.remediation);
  console.error(result.diagnostics);
  process.exitCode = 1;
}

Set input and output limits for untrusted documents, use explicit timeouts, and validate the exact artifact bytes before release. Managed review, release, delivery, webhook, billing, and audit workflows are separate control-plane operations; a successful render does not imply that those later steps occurred.