@formfeed/sdk 0.1.0 → 0.2.0

package/index.cjs

@@ -54,6 +54,8 @@ function randomKey() {
   if (c?.randomUUID) return c.randomUUID();
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
+var withKey = (options) => ({ ...options, idempotencyKey: options.idempotencyKey ?? randomKey() });
+var idOf = (source) => typeof source === "string" ? source : source.id;
 var Formfeed = class {
   baseUrl;
   apiKey;
@@ -122,6 +124,54 @@ var Formfeed = class {
       idempotencyKey: options.idempotencyKey ?? randomKey()
     })
   };
+  /**
+   * PDF tools on the outputs of earlier renders (a `Render` or its id) and on PDFs of the file library
+   * (a `LibraryFile`, its id or its name). merge, protect and watermark return a new render and cost
+   * 0.5 units each on live keys; info is free.
+   */
+  pdf = {
+    merge: (sources, output = {}, options = {}) => this.request("POST", "/pdf/merge", { ...output, sources: sources.map(idOf) }, withKey(options)),
+    protect: (source, protect, options = {}) => this.request("POST", "/pdf/protect", { ...protect, source: idOf(source) }, withKey(options)),
+    watermark: (source, watermark, options = {}) => this.request("POST", "/pdf/watermark", { ...watermark, source: idOf(source) }, withKey(options)),
+    info: (source, options = {}) => this.request("POST", "/pdf/info", { source: idOf(source) }, options)
+  };
+  /**
+   * The workspace file library (`/files`): images and PDFs a template references by name with
+   * `asset('logo.png')`, and the sources of image watermarks and merges. Needs `file:read`,
+   * `file:write` or `file:delete`. Files are served without a signature, so keep confidential
+   * documents out of it.
+   */
+  files = {
+    /** Uploads a file; the same name replaces the existing file in place and keeps its URL. */
+    upload: (file, options = {}) => {
+      const blob = file.data instanceof Blob ? file.data : new Blob([file.data], file.contentType ? { type: file.contentType } : {});
+      const form = new FormData();
+      form.set("file", blob, file.name);
+      form.set("name", file.name);
+      return this.request("POST", "/files", form, options);
+    },
+    /** Page of files, newest first. */
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/files${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every file matching the query, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.files.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    get: (id, options = {}) => this.request("GET", `/files/${encodeURIComponent(id)}`, void 0, options),
+    /** Removes the file and its bytes; templates that name it render a missing image afterwards. */
+    delete: (file, options = {}) => this.request("DELETE", `/files/${encodeURIComponent(idOf(file))}`, void 0, options)
+  };
   jobs = {
     get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
     waitFor: async (id, options = {}) => {
@@ -172,7 +222,13 @@ var Formfeed = class {
       create: (idOrSlug, input, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions`, input, options),
       publish: (idOrSlug, number, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`, void 0, options)
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options)
+    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
+    /**
+     * Checks a version with data without rendering: syntax, header and footer, missing partials,
+     * runtime errors and the data against the stored schema. Free. Without `data`, the version's
+     * sample data is checked.
+     */
+    validate: (idOrSlug, input = {}, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/validate`, input, options)
   };
   account = {
     get: (options = {}) => this.request("GET", "/account", void 0, options),
@@ -185,9 +241,10 @@ var Formfeed = class {
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
       accept: "application/json",
-      "user-agent": "formfeed-sdk-ts/0.1"
+      "user-agent": "formfeed-sdk-ts/0.2"
     };
-    if (body !== void 0) headers["content-type"] = "application/json";
+    const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+    if (body !== void 0 && !isForm) headers["content-type"] = "application/json";
     if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
     let attempt = 0;
     for (; ; ) {
@@ -199,7 +256,7 @@ var Formfeed = class {
         res = await this.fetchImpl(url, {
           method,
           headers,
-          body: body === void 0 ? void 0 : JSON.stringify(body),
+          body: body === void 0 ? void 0 : isForm ? body : JSON.stringify(body),
           signal: controller.signal
         });
       } catch (e) {

package/index.js

@@ -25,6 +25,8 @@ function randomKey() {
   if (c?.randomUUID) return c.randomUUID();
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
+var withKey = (options) => ({ ...options, idempotencyKey: options.idempotencyKey ?? randomKey() });
+var idOf = (source) => typeof source === "string" ? source : source.id;
 var Formfeed = class {
   baseUrl;
   apiKey;
@@ -93,6 +95,54 @@ var Formfeed = class {
       idempotencyKey: options.idempotencyKey ?? randomKey()
     })
   };
+  /**
+   * PDF tools on the outputs of earlier renders (a `Render` or its id) and on PDFs of the file library
+   * (a `LibraryFile`, its id or its name). merge, protect and watermark return a new render and cost
+   * 0.5 units each on live keys; info is free.
+   */
+  pdf = {
+    merge: (sources, output = {}, options = {}) => this.request("POST", "/pdf/merge", { ...output, sources: sources.map(idOf) }, withKey(options)),
+    protect: (source, protect, options = {}) => this.request("POST", "/pdf/protect", { ...protect, source: idOf(source) }, withKey(options)),
+    watermark: (source, watermark, options = {}) => this.request("POST", "/pdf/watermark", { ...watermark, source: idOf(source) }, withKey(options)),
+    info: (source, options = {}) => this.request("POST", "/pdf/info", { source: idOf(source) }, options)
+  };
+  /**
+   * The workspace file library (`/files`): images and PDFs a template references by name with
+   * `asset('logo.png')`, and the sources of image watermarks and merges. Needs `file:read`,
+   * `file:write` or `file:delete`. Files are served without a signature, so keep confidential
+   * documents out of it.
+   */
+  files = {
+    /** Uploads a file; the same name replaces the existing file in place and keeps its URL. */
+    upload: (file, options = {}) => {
+      const blob = file.data instanceof Blob ? file.data : new Blob([file.data], file.contentType ? { type: file.contentType } : {});
+      const form = new FormData();
+      form.set("file", blob, file.name);
+      form.set("name", file.name);
+      return this.request("POST", "/files", form, options);
+    },
+    /** Page of files, newest first. */
+    list: (query = {}, options = {}) => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== null && v !== "") params.set(k, String(v));
+      const qs = params.toString();
+      return this.request("GET", `/files${qs ? `?${qs}` : ""}`, void 0, options);
+    },
+    /** Every file matching the query, following the cursor. */
+    all: async (query = {}, options = {}) => {
+      const out = [];
+      let cursor = null;
+      do {
+        const page = await this.files.list({ ...query, cursor }, options);
+        out.push(...page.data);
+        cursor = page.next_cursor;
+      } while (cursor);
+      return out;
+    },
+    get: (id, options = {}) => this.request("GET", `/files/${encodeURIComponent(id)}`, void 0, options),
+    /** Removes the file and its bytes; templates that name it render a missing image afterwards. */
+    delete: (file, options = {}) => this.request("DELETE", `/files/${encodeURIComponent(idOf(file))}`, void 0, options)
+  };
   jobs = {
     get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
     waitFor: async (id, options = {}) => {
@@ -143,7 +193,13 @@ var Formfeed = class {
       create: (idOrSlug, input, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions`, input, options),
       publish: (idOrSlug, number, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`, void 0, options)
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options)
+    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
+    /**
+     * Checks a version with data without rendering: syntax, header and footer, missing partials,
+     * runtime errors and the data against the stored schema. Free. Without `data`, the version's
+     * sample data is checked.
+     */
+    validate: (idOrSlug, input = {}, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/validate`, input, options)
   };
   account = {
     get: (options = {}) => this.request("GET", "/account", void 0, options),
@@ -156,9 +212,10 @@ var Formfeed = class {
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
       accept: "application/json",
-      "user-agent": "formfeed-sdk-ts/0.1"
+      "user-agent": "formfeed-sdk-ts/0.2"
     };
-    if (body !== void 0) headers["content-type"] = "application/json";
+    const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+    if (body !== void 0 && !isForm) headers["content-type"] = "application/json";
     if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
     let attempt = 0;
     for (; ; ) {
@@ -170,7 +227,7 @@ var Formfeed = class {
         res = await this.fetchImpl(url, {
           method,
           headers,
-          body: body === void 0 ? void 0 : JSON.stringify(body),
+          body: body === void 0 ? void 0 : isForm ? body : JSON.stringify(body),
           signal: controller.signal
         });
       } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Formfeed API client: renders, templates, webhooks. No dependencies, Web APIs only.",
   "license": "MIT",
   "type": "module",

package/types/index.d.cts

@@ -1,4 +1,4 @@
 export { Formfeed, FormfeedError } from './lib/client.cjs';
-export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Engine, FormfeedOptions, Job, OutputFormat, Problem, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WebhookEndpoint, } from './lib/client.cjs';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, } from './lib/client.cjs';
 export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.cjs';
 export type { VerifyOptions } from './lib/webhooks.cjs';

package/types/index.d.ts

@@ -1,4 +1,4 @@
 export { Formfeed, FormfeedError } from './lib/client.js';
-export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Engine, FormfeedOptions, Job, OutputFormat, Problem, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WebhookEndpoint, } from './lib/client.js';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, VersionStatus, BatchRequest, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, RequestOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, } from './lib/client.js';
 export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.js';
 export type { VerifyOptions } from './lib/webhooks.js';

package/types/lib/client.d.cts

@@ -34,9 +34,65 @@ export interface RenderRequest {
     mode?: 'sync' | 'async';
     locale?: string | null;
     webhook_url?: string | null;
+    /** Signs the deliveries to `webhook_url`, the way an endpoint secret does; 16 to 200 characters. */
+    webhook_secret?: string | null;
     meta?: Record<string, unknown>;
     region?: Region;
     dedupe?: boolean;
+    /** PDF post-processing: merge, watermark, password, applied in that order (0.5 units each). */
+    post?: PostProcessing | null;
+    /** Check `data` against the template's stored schema first; a mismatch throws `data_validation_error`. */
+    validate_data?: boolean;
+}
+export type PdfPermission = 'print' | 'copy' | 'modify' | 'annotate';
+/** A text or an image watermark; pass one of `text` and `image`. */
+export interface WatermarkOptions {
+    text?: string;
+    /** A PNG or JPEG of the workspace file library: its id (`fil_…`) or its name. */
+    image?: string;
+    /** 0 to 1, default 0.2. */
+    opacity?: number;
+    /** Degrees clockwise as in CSS, default -45 (bottom left to top right). */
+    rotation?: number;
+    /** Hex colour such as `#cc0000`; grey by default. Text only. */
+    color?: string;
+}
+export interface PostProcessing {
+    /** PDFs appended after this document, in order: render ids, or file ids and names of library PDFs. */
+    merge_after?: string[];
+    watermark?: WatermarkOptions;
+    password?: {
+        user?: string;
+        owner?: string;
+        permissions?: PdfPermission[];
+    };
+}
+/** Where the result of a PDF tool is stored, as for a render. */
+export interface PdfOutputOptions {
+    filename?: string;
+    expires_in?: number | null;
+    access?: 'public' | 'signed';
+    meta?: Record<string, unknown>;
+}
+export interface ProtectOptions extends PdfOutputOptions {
+    /** Needed to open the document. */
+    user_password?: string;
+    /** Lifts the restrictions; random when omitted. */
+    owner_password?: string;
+    /** What readers may do; everything not listed is forbidden. */
+    permissions?: PdfPermission[];
+}
+export interface PdfInfo {
+    source: string;
+    page_count: number;
+    pages: Array<{
+        width_pt: number;
+        height_pt: number;
+        width_mm: number;
+        height_mm: number;
+    }>;
+    encrypted: boolean;
+    metadata: Record<string, unknown>;
 }
 export interface Render {
     id: string;
@@ -73,6 +129,7 @@ export interface BatchRequest {
     items: RenderRequest[];
     zip?: boolean;
     webhook_url?: string | null;
+    webhook_secret?: string | null;
     meta?: Record<string, unknown>;
 }
 export interface Job {
@@ -89,6 +146,32 @@ export interface Job {
     created_at: string;
     completed_at: string | null;
 }
+/** A file of the workspace library (`/files`); a template reaches it with `asset(name)`. */
+export interface LibraryFile {
+    id: string;
+    name: string;
+    content_type: string;
+    bytes: number;
+    sha256: string;
+    /** The CDN URL, the same one `asset(name)` produces. */
+    url: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface FileUpload {
+    /** The bytes: a Blob or File, a Uint8Array (Node's Buffer is one) or an ArrayBuffer. */
+    data: Blob | Uint8Array | ArrayBuffer;
+    /** The library name, e.g. `logo.png` or `brand/header.svg`. Uploading a name again replaces it. */
+    name: string;
+    /** Sent with the bytes; the API also goes by the extension when it is missing. */
+    contentType?: string;
+}
+export interface FileListOptions {
+    /** Only names starting with this, e.g. `brand/`. */
+    prefix?: string;
+    limit?: number;
+    cursor?: string | null;
+}
 export interface WebhookEndpoint {
     id: string;
     url: string;
@@ -116,6 +199,28 @@ export interface Template {
     created_at: string;
     updated_at: string;
 }
+/** One finding of `templates.validate`. */
+export interface Diagnostic {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    message: string;
+    location?: {
+        line: number;
+        column: number;
+    };
+    /** Data errors only: where in the data, e.g. `data.invoice.lines[0].qty`. */
+    path?: string;
+}
+export interface TemplateValidation {
+    /** `false` when at least one diagnostic is an error. */
+    ok: boolean;
+    template: {
+        id: string;
+        slug: string;
+        version: number;
+    };
+    diagnostics: Diagnostic[];
+}
 /** The files of a version as the editor and the CLI keep them. */
 export interface TemplateFiles {
     html: string;
@@ -127,6 +232,8 @@ export interface TemplateFiles {
     data_sets?: Record<string, unknown> | null;
     data_schema?: Record<string, unknown> | null;
     i18n?: Record<string, unknown> | null;
+    /** Partials the template includes (`name` → source); `formfeed templates push` sends them. */
+    partials?: Record<string, string> | null;
 }
 export interface TemplateVersion extends Partial<TemplateFiles> {
     id: string;
@@ -238,6 +345,37 @@ export declare class Formfeed {
         deleteOutputs: (id: string, options?: RequestOptions) => Promise<void>;
         batch: (request: BatchRequest, options?: RequestOptions) => Promise<Job>;
     };
+    /**
+     * PDF tools on the outputs of earlier renders (a `Render` or its id) and on PDFs of the file library
+     * (a `LibraryFile`, its id or its name). merge, protect and watermark return a new render and cost
+     * 0.5 units each on live keys; info is free.
+     */
+    readonly pdf: {
+        merge: (sources: Array<Render | LibraryFile | string>, output?: PdfOutputOptions, options?: RequestOptions) => Promise<Render>;
+        protect: (source: Render | string, protect: ProtectOptions, options?: RequestOptions) => Promise<Render>;
+        watermark: (source: Render | string, watermark: WatermarkOptions & PdfOutputOptions, options?: RequestOptions) => Promise<Render>;
+        info: (source: Render | string, options?: RequestOptions) => Promise<PdfInfo>;
+    };
+    /**
+     * The workspace file library (`/files`): images and PDFs a template references by name with
+     * `asset('logo.png')`, and the sources of image watermarks and merges. Needs `file:read`,
+     * `file:write` or `file:delete`. Files are served without a signature, so keep confidential
+     * documents out of it.
+     */
+    readonly files: {
+        /** Uploads a file; the same name replaces the existing file in place and keeps its URL. */
+        upload: (file: FileUpload, options?: RequestOptions) => Promise<LibraryFile>;
+        /** Page of files, newest first. */
+        list: (query?: FileListOptions, options?: RequestOptions) => Promise<{
+            data: LibraryFile[];
+            next_cursor: string | null;
+        }>;
+        /** Every file matching the query, following the cursor. */
+        all: (query?: Omit<FileListOptions, "cursor">, options?: RequestOptions) => Promise<LibraryFile[]>;
+        get: (id: string, options?: RequestOptions) => Promise<LibraryFile>;
+        /** Removes the file and its bytes; templates that name it render a missing image afterwards. */
+        delete: (file: LibraryFile | string, options?: RequestOptions) => Promise<void>;
+    };
     readonly jobs: {
         get: (id: string, options?: RequestOptions) => Promise<Job>;
         waitFor: (id: string, options?: WaitOptions) => Promise<Job>;
@@ -283,6 +421,15 @@ export declare class Formfeed {
             publish: (idOrSlug: string, number: number, options?: RequestOptions) => Promise<TemplateVersion>;
         };
         schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /**
+         * Checks a version with data without rendering: syntax, header and footer, missing partials,
+         * runtime errors and the data against the stored schema. Free. Without `data`, the version's
+         * sample data is checked.
+         */
+        validate: (idOrSlug: string, input?: {
+            version?: "published" | "latest" | number;
+            data?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<TemplateValidation>;
     };
     readonly account: {
         get: (options?: RequestOptions) => Promise<Record<string, unknown>>;

package/types/lib/client.d.ts

@@ -34,9 +34,65 @@ export interface RenderRequest {
     mode?: 'sync' | 'async';
     locale?: string | null;
     webhook_url?: string | null;
+    /** Signs the deliveries to `webhook_url`, the way an endpoint secret does; 16 to 200 characters. */
+    webhook_secret?: string | null;
     meta?: Record<string, unknown>;
     region?: Region;
     dedupe?: boolean;
+    /** PDF post-processing: merge, watermark, password, applied in that order (0.5 units each). */
+    post?: PostProcessing | null;
+    /** Check `data` against the template's stored schema first; a mismatch throws `data_validation_error`. */
+    validate_data?: boolean;
+}
+export type PdfPermission = 'print' | 'copy' | 'modify' | 'annotate';
+/** A text or an image watermark; pass one of `text` and `image`. */
+export interface WatermarkOptions {
+    text?: string;
+    /** A PNG or JPEG of the workspace file library: its id (`fil_…`) or its name. */
+    image?: string;
+    /** 0 to 1, default 0.2. */
+    opacity?: number;
+    /** Degrees clockwise as in CSS, default -45 (bottom left to top right). */
+    rotation?: number;
+    /** Hex colour such as `#cc0000`; grey by default. Text only. */
+    color?: string;
+}
+export interface PostProcessing {
+    /** PDFs appended after this document, in order: render ids, or file ids and names of library PDFs. */
+    merge_after?: string[];
+    watermark?: WatermarkOptions;
+    password?: {
+        user?: string;
+        owner?: string;
+        permissions?: PdfPermission[];
+    };
+}
+/** Where the result of a PDF tool is stored, as for a render. */
+export interface PdfOutputOptions {
+    filename?: string;
+    expires_in?: number | null;
+    access?: 'public' | 'signed';
+    meta?: Record<string, unknown>;
+}
+export interface ProtectOptions extends PdfOutputOptions {
+    /** Needed to open the document. */
+    user_password?: string;
+    /** Lifts the restrictions; random when omitted. */
+    owner_password?: string;
+    /** What readers may do; everything not listed is forbidden. */
+    permissions?: PdfPermission[];
+}
+export interface PdfInfo {
+    source: string;
+    page_count: number;
+    pages: Array<{
+        width_pt: number;
+        height_pt: number;
+        width_mm: number;
+        height_mm: number;
+    }>;
+    encrypted: boolean;
+    metadata: Record<string, unknown>;
 }
 export interface Render {
     id: string;
@@ -73,6 +129,7 @@ export interface BatchRequest {
     items: RenderRequest[];
     zip?: boolean;
     webhook_url?: string | null;
+    webhook_secret?: string | null;
     meta?: Record<string, unknown>;
 }
 export interface Job {
@@ -89,6 +146,32 @@ export interface Job {
     created_at: string;
     completed_at: string | null;
 }
+/** A file of the workspace library (`/files`); a template reaches it with `asset(name)`. */
+export interface LibraryFile {
+    id: string;
+    name: string;
+    content_type: string;
+    bytes: number;
+    sha256: string;
+    /** The CDN URL, the same one `asset(name)` produces. */
+    url: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface FileUpload {
+    /** The bytes: a Blob or File, a Uint8Array (Node's Buffer is one) or an ArrayBuffer. */
+    data: Blob | Uint8Array | ArrayBuffer;
+    /** The library name, e.g. `logo.png` or `brand/header.svg`. Uploading a name again replaces it. */
+    name: string;
+    /** Sent with the bytes; the API also goes by the extension when it is missing. */
+    contentType?: string;
+}
+export interface FileListOptions {
+    /** Only names starting with this, e.g. `brand/`. */
+    prefix?: string;
+    limit?: number;
+    cursor?: string | null;
+}
 export interface WebhookEndpoint {
     id: string;
     url: string;
@@ -116,6 +199,28 @@ export interface Template {
     created_at: string;
     updated_at: string;
 }
+/** One finding of `templates.validate`. */
+export interface Diagnostic {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    message: string;
+    location?: {
+        line: number;
+        column: number;
+    };
+    /** Data errors only: where in the data, e.g. `data.invoice.lines[0].qty`. */
+    path?: string;
+}
+export interface TemplateValidation {
+    /** `false` when at least one diagnostic is an error. */
+    ok: boolean;
+    template: {
+        id: string;
+        slug: string;
+        version: number;
+    };
+    diagnostics: Diagnostic[];
+}
 /** The files of a version as the editor and the CLI keep them. */
 export interface TemplateFiles {
     html: string;
@@ -127,6 +232,8 @@ export interface TemplateFiles {
     data_sets?: Record<string, unknown> | null;
     data_schema?: Record<string, unknown> | null;
     i18n?: Record<string, unknown> | null;
+    /** Partials the template includes (`name` → source); `formfeed templates push` sends them. */
+    partials?: Record<string, string> | null;
 }
 export interface TemplateVersion extends Partial<TemplateFiles> {
     id: string;
@@ -238,6 +345,37 @@ export declare class Formfeed {
         deleteOutputs: (id: string, options?: RequestOptions) => Promise<void>;
         batch: (request: BatchRequest, options?: RequestOptions) => Promise<Job>;
     };
+    /**
+     * PDF tools on the outputs of earlier renders (a `Render` or its id) and on PDFs of the file library
+     * (a `LibraryFile`, its id or its name). merge, protect and watermark return a new render and cost
+     * 0.5 units each on live keys; info is free.
+     */
+    readonly pdf: {
+        merge: (sources: Array<Render | LibraryFile | string>, output?: PdfOutputOptions, options?: RequestOptions) => Promise<Render>;
+        protect: (source: Render | string, protect: ProtectOptions, options?: RequestOptions) => Promise<Render>;
+        watermark: (source: Render | string, watermark: WatermarkOptions & PdfOutputOptions, options?: RequestOptions) => Promise<Render>;
+        info: (source: Render | string, options?: RequestOptions) => Promise<PdfInfo>;
+    };
+    /**
+     * The workspace file library (`/files`): images and PDFs a template references by name with
+     * `asset('logo.png')`, and the sources of image watermarks and merges. Needs `file:read`,
+     * `file:write` or `file:delete`. Files are served without a signature, so keep confidential
+     * documents out of it.
+     */
+    readonly files: {
+        /** Uploads a file; the same name replaces the existing file in place and keeps its URL. */
+        upload: (file: FileUpload, options?: RequestOptions) => Promise<LibraryFile>;
+        /** Page of files, newest first. */
+        list: (query?: FileListOptions, options?: RequestOptions) => Promise<{
+            data: LibraryFile[];
+            next_cursor: string | null;
+        }>;
+        /** Every file matching the query, following the cursor. */
+        all: (query?: Omit<FileListOptions, "cursor">, options?: RequestOptions) => Promise<LibraryFile[]>;
+        get: (id: string, options?: RequestOptions) => Promise<LibraryFile>;
+        /** Removes the file and its bytes; templates that name it render a missing image afterwards. */
+        delete: (file: LibraryFile | string, options?: RequestOptions) => Promise<void>;
+    };
     readonly jobs: {
         get: (id: string, options?: RequestOptions) => Promise<Job>;
         waitFor: (id: string, options?: WaitOptions) => Promise<Job>;
@@ -283,6 +421,15 @@ export declare class Formfeed {
             publish: (idOrSlug: string, number: number, options?: RequestOptions) => Promise<TemplateVersion>;
         };
         schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /**
+         * Checks a version with data without rendering: syntax, header and footer, missing partials,
+         * runtime errors and the data against the stored schema. Free. Without `data`, the version's
+         * sample data is checked.
+         */
+        validate: (idOrSlug: string, input?: {
+            version?: "published" | "latest" | number;
+            data?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<TemplateValidation>;
     };
     readonly account: {
         get: (options?: RequestOptions) => Promise<Record<string, unknown>>;