TypeScript SDK
A typed TypeScript client for the necodoc public API (/api/v1). Types are generated from the
API’s OpenAPI document; requests go through openapi-fetch.
Install
Section titled “Install”The package lives in the necodoc repository (packages/sdk-ts) and isn’t on npm. Install it from a
checkout as a local path:
npm install ../necodoc/packages/sdk-ts # or: pnpm add ../necodoc/packages/sdk-tsIt ships TypeScript source (src/index.ts), not compiled JavaScript, so your build has to compile
it: a bundler such as Vite, esbuild or webpack with a TS loader, or a runtime such as Bun or tsx.
Node’s built-in type stripping skips node_modules and won’t load it. Inside the necodoc workspace,
depend on "@necodoc/sdk": "workspace:*".
Create a client
Section titled “Create a client”import { createNecodocClient, type Schema } from "@necodoc/sdk";
const necodoc = createNecodocClient({ baseUrl: "https://necodoc.example.com", apiKey: process.env.NECODOC_API_KEY!, // nd_…});Every call returns { data, error, response }. error is the API’s error body
({ error, code, fieldErrors? }) when the status isn’t 2xx.
Render HTML to a PDF
Section titled “Render HTML to a PDF”// Typing the body keeps `pdf` an ArrayBuffer once it uses optional fields like `page.size`.const body: Schema<"RenderRequest"> = { html: "<h1>Invoice {{ number }}</h1>", data: { number: "A-1001" }, footer: { html: "<p>{{ page }} / {{ pages }}</p>", height: 12 },};const { data: pdf, error } = await necodoc.POST("/render", { body, parseAs: "arrayBuffer" });if (error) throw new Error(`${error.code}: ${error.error}`);await writeFile("invoice.pdf", new Uint8Array(pdf));Generate from a template, as JSON
Section titled “Generate from a template, as JSON”const { data } = await necodoc.POST("/templates/{id}/versions/{version}/generate", { params: { path: { id: templateId, version: "latest" } }, body: { data: { client_name: "Acme" }, response: "json" },});// data.generationId, data.downloadUrl (signed, 1 hour), data.pdfPathInvalid data answers 422 with error.fieldErrors, one entry per field.
Signing packages
Section titled “Signing packages”signing answers with the PDF’s signers, sign box positions and provider JSON instead of the PDF:
const { data: pkg } = await necodoc.POST("/templates/{id}/versions/{version}/generate", { params: { path: { id: templateId, version: "latest" } }, body: { data: { client_name: "Acme" }, signing: { formats: ["docusign"], placement: "position" }, },});if (!pkg || !("boxes" in pkg)) throw new Error("Expected a signing package");// pkg.boxes[i].topLeft (points from the page's top-left), pkg.formats.docusign (envelope JSON)GET /generations/{id}/signing-package returns the same for an earlier generation.
Async renders and polling
Section titled “Async renders and polling”const { data: queued } = await necodoc.POST("/render", { body: { html: "<p>Big report</p>", async: true },});if (!queued || typeof queued === "string") throw new Error("Expected a generation id");let status = queued.status;while (status === "queued" || status === "running") { await new Promise((resolve) => setTimeout(resolve, 2000)); const { data } = await necodoc.GET("/generations/{id}", { params: { path: { id: queued.generationId } }, }); status = data?.status ?? "error";}A render still running when the server stops waiting also answers 202 with a generation id, so
handle response.status === 202 on synchronous calls too. Webhooks avoid polling altogether.
paths, components and operations are re-exported. Schema<"RenderRequest"> picks one
schema by name.
Regenerating
Section titled “Regenerating”pnpm --filter @necodoc/sdk generate writes openapi.json from the API code and regenerates
src/schema.ts. It runs openapi-typescript through pnpm dlx with TypeScript 6, because
openapi-typescript needs the TypeScript compiler API, which TypeScript 7 doesn’t ship. Fields
with a server-side default (response, async, page) stay optional
(--default-non-nullable false).