Skip to content

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.

The package lives in the necodoc repository (packages/sdk-ts) and isn’t on npm. Install it from a checkout as a local path:

Terminal window
npm install ../necodoc/packages/sdk-ts # or: pnpm add ../necodoc/packages/sdk-ts

It 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:*".

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.

// 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));
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.pdfPath

Invalid data answers 422 with error.fieldErrors, one entry per field.

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.

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.

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).