Add merge, certify, redact to TypeScript SDK with docs

danmolitor · claude · danmolitor · commit 62b7b3411d3a · 2026-04-04T19:35:44.000-05:00
Add three missing methods to @formepdf/sdk: merge(), certify(), and
redact() — matching the Python and Go SDKs. Create TypeScript SDK
docs page, update README, and add to Mintlify navigation.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/docs.json b/docs/docs.json
@@ -56,7 +56,7 @@
       },
       {
         "group": "SDKs",
-        "pages": ["python-sdk", "go-sdk", "rust-sdk"]
+        "pages": ["typescript-sdk", "python-sdk", "go-sdk", "rust-sdk"]
       },
       {
         "group": "Guides",
diff --git a/docs/typescript-sdk.mdx b/docs/typescript-sdk.mdx
@@ -0,0 +1,151 @@
+---
+title: TypeScript SDK
+sidebarTitle: TypeScript
+description: Generate, certify, redact, and merge PDFs from TypeScript with the hosted API. Zero-dependency client that works in Node.js, Deno, Bun, and edge runtimes.
+---
+
+## Installation
+
+```bash
+npm install @formepdf/sdk
+```
+
+## Usage
+
+Create templates in the [dashboard](https://app.formepdf.com), then render them with data:
+
+```typescript
+import { Forme } from "@formepdf/sdk";
+
+const forme = new Forme("forme_sk_...");
+
+const pdf = await forme.render("invoice", {
+  customer: "Acme Corp",
+  items: [{ name: "Widget", qty: 5, price: 49 }],
+  total: 245,
+});
+
+await fs.writeFile("invoice.pdf", pdf);
+```
+
+### Client options
+
+```typescript
+const forme = new Forme("forme_sk_...", {
+  baseUrl: "https://custom-api.example.com", // optional
+});
+```
+
+### Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `render(slug, data, options?)` | Synchronous render | `Promise<Uint8Array \| { url: string }>` |
+| `renderAsync(slug, data, options?)` | Start async render job | `Promise<{ jobId, status }>` |
+| `getJob(jobId)` | Poll async job status | `Promise<JobResult>` |
+| `merge(pdfs)` | Merge multiple PDFs | `Promise<Uint8Array>` |
+| `certify(pdf, options)` | Certify a PDF with X.509 certificate | `Promise<Uint8Array>` |
+| `redact(pdf, options)` | Redact content from a PDF | `Promise<Uint8Array>` |
+| `extract(pdf)` | Extract embedded data | `Promise<unknown \| null>` |
+
+---
+
+## Render to S3
+
+```typescript
+const result = await forme.render("invoice", data, {
+  s3: {
+    bucket: "my-bucket",
+    key: "invoices/001.pdf",
+    accessKeyId: "AKIA...",
+    secretAccessKey: "...",
+    region: "us-east-1",
+  },
+});
+// result = { url: "https://my-bucket.s3.amazonaws.com/invoices/001.pdf" }
+```
+
+## Async rendering
+
+```typescript
+const { jobId } = await forme.renderAsync("invoice", data, {
+  webhookUrl: "https://example.com/webhook",
+});
+
+// Poll for completion
+const job = await forme.getJob(jobId);
+if (job.status === "completed") {
+  const pdf = Buffer.from(job.pdfBase64!, "base64");
+}
+```
+
+## Certify
+
+```typescript
+import { readFileSync } from "fs";
+
+const certified = await forme.certify(pdfBytes, {
+  certificate: readFileSync("cert.pem", "utf-8"),
+  privateKey: readFileSync("key.pem", "utf-8"),
+  reason: "Approved",
+});
+```
+
+Or use a saved certificate on the hosted API:
+
+```typescript
+const certified = await forme.certify(pdfBytes, {
+  certificateId: "cert_abc123",
+});
+```
+
+## Redact
+
+```typescript
+// By text pattern
+const redacted = await forme.redact(pdfBytes, {
+  patterns: [
+    { pattern: "Jane Doe", pattern_type: "Literal" },
+    { pattern: "\\d{3}-\\d{2}-\\d{4}", pattern_type: "Regex" },
+  ],
+});
+
+// By built-in presets
+const redacted = await forme.redact(pdfBytes, {
+  presets: ["ssn", "email", "phone"],
+});
+
+// By saved redaction template
+const redacted = await forme.redact(pdfBytes, {
+  template: "hipaa-patient-record",
+});
+```
+
+## Merge
+
+```typescript
+const merged = await forme.merge([pdf1, pdf2, pdf3]);
+```
+
+## Extract embedded data
+
+```typescript
+const data = await forme.extract(pdfBytes);
+if (data) {
+  console.log(data); // the JSON that was embedded at render time
+}
+```
+
+## Error handling
+
+```typescript
+import { Forme, FormeError } from "@formepdf/sdk";
+
+try {
+  const pdf = await forme.render("invoice", data);
+} catch (err) {
+  if (err instanceof FormeError) {
+    console.error(`Error ${err.status}: ${err.message}`);
+  }
+}
+```
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
@@ -41,12 +41,55 @@ new Forme(apiKey: string, options?: { baseUrl?: string })
 
 ## Methods
 
-### `render(slug, data?)`
+### `render(slug, data?, options?)`
 
 Render a template to PDF bytes.
 
 - **slug** — Template identifier
 - **data** — Template data (sent as JSON body, defaults to `{}`)
+- **options.s3** — Optional S3 upload config (`{ bucket, key, accessKeyId, secretAccessKey, region?, endpoint? }`)
+- **Returns** `Promise<Uint8Array>` (or `Promise<{ url: string }>` when `s3` is provided)
+
+### `renderAsync(slug, data?, options?)`
+
+Start an async render job.
+
+- **options.webhookUrl** — URL to receive a POST when the job completes
+- **Returns** `Promise<{ jobId: string; status: string }>`
+
+### `getJob(jobId)`
+
+Poll an async job's status.
+
+- **Returns** `Promise<JobResult>` — includes `pdfBase64` when complete
+
+### `merge(pdfs)`
+
+Merge multiple PDFs into one.
+
+- **pdfs** — Array of `Uint8Array` (2–20 PDFs)
+- **Returns** `Promise<Uint8Array>`
+
+### `certify(pdf, options)`
+
+Certify a PDF with an X.509 digital certificate.
+
+- **pdf** — PDF file bytes
+- **options.certificate** — PEM-encoded certificate string
+- **options.privateKey** — PEM-encoded private key string
+- **options.certificateId** — Or use a saved certificate ID (instead of raw PEM)
+- **options.reason** / **options.location** / **options.contact** — Optional metadata
+- **Returns** `Promise<Uint8Array>`
+
+### `redact(pdf, options)`
+
+Redact sensitive content from a PDF.
+
+- **pdf** — PDF file bytes
+- **options.patterns** — Array of `{ pattern, pattern_type: 'Literal' | 'Regex' }`
+- **options.presets** — Built-in presets like `['ssn', 'email', 'phone']`
+- **options.template** — Saved redaction template slug
+- **options.redactions** — Explicit regions `{ page, x, y, width, height }[]`
 - **Returns** `Promise<Uint8Array>`
 
 ### `extract(pdf)`
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
@@ -21,6 +21,35 @@ export interface AsyncRenderOptions {
   webhookUrl?: string;
 }
 
+export interface CertifyOptions {
+  certificate?: string;
+  privateKey?: string;
+  certificateId?: string;
+  reason?: string;
+  location?: string;
+  contact?: string;
+}
+
+export interface RedactionPattern {
+  pattern: string;
+  pattern_type: 'Literal' | 'Regex';
+}
+
+export interface RedactionRegion {
+  page: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface RedactOptions {
+  redactions?: RedactionRegion[];
+  patterns?: RedactionPattern[];
+  presets?: string[];
+  template?: string;
+}
+
 export interface JobResult {
   id: string;
   status: string;
@@ -112,6 +141,79 @@ export class Forme {
     return res.json();
   }
 
+  async merge(pdfs: Uint8Array[]): Promise<Uint8Array> {
+    const res = await fetch(`${this.baseUrl}/v1/merge`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        pdfs: pdfs.map((p) => uint8ArrayToBase64(p)),
+      }),
+    });
+
+    if (!res.ok) {
+      const message = await parseErrorMessage(res);
+      throw new FormeError(res.status, message);
+    }
+
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async certify(pdf: Uint8Array, options: CertifyOptions): Promise<Uint8Array> {
+    const body: Record<string, unknown> = {
+      pdf: uint8ArrayToBase64(pdf),
+    };
+
+    if (options.certificateId) {
+      body.certificateId = options.certificateId;
+    } else {
+      body.certificate = options.certificate;
+      body.privateKey = options.privateKey;
+    }
+    if (options.reason) body.reason = options.reason;
+    if (options.location) body.location = options.location;
+    if (options.contact) body.contact = options.contact;
+
+    const res = await fetch(`${this.baseUrl}/v1/certify`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const message = await parseErrorMessage(res);
+      throw new FormeError(res.status, message);
+    }
+
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async redact(pdf: Uint8Array, options: RedactOptions): Promise<Uint8Array> {
+    const res = await fetch(`${this.baseUrl}/v1/redact`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        pdf: uint8ArrayToBase64(pdf),
+        ...options,
+      }),
+    });
+
+    if (!res.ok) {
+      const message = await parseErrorMessage(res);
+      throw new FormeError(res.status, message);
+    }
+
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
   async extract(pdf: Uint8Array): Promise<unknown | null> {
     const res = await fetch(`${this.baseUrl}/v1/extract`, {
       method: 'POST',
@@ -140,6 +242,17 @@ export class Forme {
   }
 }
 
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
 async function parseErrorMessage(res: Response): Promise<string> {
   try {
     const body = await res.json();
diff --git a/packages/sdk/tests/index.test.ts b/packages/sdk/tests/index.test.ts

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@`
`56`	`56`	`},`
`57`	`57`	`{`
`58`	`58`	`"group": "SDKs",`
`59`		`- "pages": ["python-sdk", "go-sdk", "rust-sdk"]`
	`59`	`+ "pages": ["typescript-sdk", "python-sdk", "go-sdk", "rust-sdk"]`
`60`	`60`	`},`
`61`	`61`	`{`
`62`	`62`	`"group": "Guides",`