@formfeed/sdk 0.2.0 → 0.3.1

package/README.md

@@ -1,7 +1,7 @@
 # @formfeed/sdk
 
 The TypeScript client for the [Formfeed](https://formfeed.dev) API: generate PDFs and images from
-templates. It has no dependencies and uses only Web APIs (`fetch`, Web Crypto), so it runs in Node 22+,
+templates, and fill Word and PowerPoint templates. It has no dependencies and uses only Web APIs (`fetch`, Web Crypto), so it runs in Node 22+,
 Deno, Bun, Cloudflare Workers and browsers.
 
 - Retries `429` and `503` with the server's `Retry-After`.
@@ -43,6 +43,31 @@ const job = await client.renders.batch({
 const finished = await client.jobs.waitFor(job.id);
 ```
 
+## Word and PowerPoint
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+// a template is a .docx or .pptx with tags such as {{ customer.name }} in its text
+await client.templates.create({
+  name: 'Offer',
+  slug: 'offer',
+  kind: 'docx',
+  engine: 'jinja2',
+  file: { data: await readFile('offer.docx'), name: 'offer.docx' },
+  publish: true,
+});
+
+const filled = await client.renders.create({ template: 'offer', output: 'docx', data }); // or output: 'pdf'
+
+// a new version with a new document; without `file` the latest document is kept
+await client.templates.versions.create('offer', { file: { data: await readFile('offer-v2.docx'), name: 'offer.docx' } });
+const docx = await client.templates.versions.file('offer', 'latest'); // the document's bytes
+
+// any office document to PDF (Word, Excel, PowerPoint, OpenDocument, RTF)
+const pdf = await client.pdf.convert({ file: { data: await readFile('report.xlsx'), name: 'report.xlsx' } }, { single_page_sheets: true });
+```
+
 ## Webhooks
 
 ```ts

package/index.cjs

@@ -28,6 +28,22 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // packages/sdk-ts/src/lib/client.ts
+var isOfficeInput = (input) => "file" in input;
+function blobOf(file) {
+  const blob = file.data instanceof Blob ? file.data : new Blob([file.data]);
+  const own = typeof File !== "undefined" && file.data instanceof File ? file.data.name : void 0;
+  return { blob, name: file.name ?? own ?? "document" };
+}
+function multipart(fields, file) {
+  const form = new FormData();
+  const { blob, name } = blobOf(file);
+  form.set("file", blob, name);
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === void 0) continue;
+    form.set(key, typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value));
+  }
+  return form;
+}
 var FormfeedError = class extends Error {
   constructor(code, message, status, problem = null, requestId = null) {
     super(message);
@@ -119,6 +135,11 @@ var Formfeed = class {
     },
     /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
     deleteOutputs: (id, options = {}) => this.request("DELETE", `/renders/${encodeURIComponent(id)}/outputs`, void 0, options),
+    /**
+     * The stored request of a render, to render it again. Needs `render:input`; throws
+     * `render_input_expired` (410) when the workspace keeps no requests or the period ended.
+     */
+    input: (id, options = {}) => this.request("GET", `/renders/${encodeURIComponent(id)}/input`, void 0, options),
     batch: (request, options = {}) => this.request("POST", "/renders/batch", request, {
       ...options,
       idempotencyKey: options.idempotencyKey ?? randomKey()
@@ -133,7 +154,18 @@ var Formfeed = class {
     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)
+    info: (source, options = {}) => this.request("POST", "/pdf/info", { source: idOf(source) }, options),
+    /**
+     * Converts an office document to a PDF render (Starter plan and above): an uploaded file (Word,
+     * Excel, PowerPoint, OpenDocument, RTF or HTML, up to 20 MB, not kept), or the output of a Word or
+     * PowerPoint template render. Costs follow the PDF rule. A busy converter answers 503, which is
+     * retried like any other.
+     */
+    convert: (source, convert = {}, options = {}) => {
+      if (typeof source === "object" && "file" in source)
+        return this.request("POST", "/pdf/convert", multipart({ ...convert }, source.file), withKey(options));
+      return this.request("POST", "/pdf/convert", { ...convert, source: idOf(source) }, withKey(options));
+    }
   };
   /**
    * The workspace file library (`/files`): images and PDFs a template references by name with
@@ -172,6 +204,27 @@ var Formfeed = class {
     /** 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)
   };
+  /** The organisation's brand kit, read-only through the API (it is edited in the app). Needs `template:read`. */
+  brand = {
+    get: (options = {}) => this.request("GET", "/brand", void 0, options)
+  };
+  /**
+   * Shared partials of the organisation. Renders use the current source, so a change reaches every
+   * template that includes the partial without a new version. Needs `template:read` or `template:write`.
+   */
+  partials = {
+    /** Every shared partial, without its source. */
+    list: async (options = {}) => (await this.request("GET", "/partials", void 0, options)).data,
+    /** One partial with its source. */
+    get: (name, options = {}) => this.request("GET", `/partials/${encodeURIComponent(name)}`, void 0, options),
+    /** Creates or replaces a partial; pass `base_version` to fail with 409 when it changed since you read it. */
+    put: async (name, input, options = {}) => {
+      const { status, body } = await this.send("PUT", `/partials/${encodeURIComponent(name)}`, input, options);
+      return { partial: body, created: status === 201 };
+    },
+    /** Removes a partial; templates that still include it fail to render afterwards. */
+    delete: (name, options = {}) => this.request("DELETE", `/partials/${encodeURIComponent(name)}`, void 0, options)
+  };
   jobs = {
     get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
     waitFor: async (id, options = {}) => {
@@ -191,7 +244,20 @@ var Formfeed = class {
     create: (input, options = {}) => this.request("POST", "/webhooks", input, options),
     update: (id, patch, options = {}) => this.request("PUT", `/webhooks/${encodeURIComponent(id)}`, patch, options),
     delete: (id, options = {}) => this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`, void 0, options),
-    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options)
+    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options),
+    /**
+     * Sends a stored event (`evt_…`) again as a new delivery to a registered endpoint (`webhook:manage`)
+     * or a running listen session (`webhook:listen`).
+     */
+    resend: (eventId, endpointId, options = {}) => this.request("POST", `/webhooks/events/${encodeURIComponent(eventId)}/resend`, { endpoint_id: endpointId }, options),
+    /**
+     * Listen sessions, what `formfeed listen` uses. Needs `webhook:listen`. Starting a session ends the
+     * previous one of the same key; the WebSocket itself is up to the caller.
+     */
+    listen: {
+      start: (input = {}, options = {}) => this.request("POST", "/webhooks/listen", input, options),
+      end: (id, options = {}) => this.request("DELETE", `/webhooks/listen/${encodeURIComponent(id)}`, void 0, options)
+    }
   };
   templates = {
     list: (query = {}, options = {}) => {
@@ -212,15 +278,79 @@ var Formfeed = class {
       return out;
     },
     get: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
-    create: (input, options = {}) => this.request("POST", "/templates", input, options),
+    /** A Word or PowerPoint template (`kind` `docx` or `pptx`) is created from its `file`, sent as multipart. */
+    create: (input, options = {}) => {
+      if (isOfficeInput(input) && input.file) {
+        const { file, ...fields } = input;
+        return this.request("POST", "/templates", multipart(fields, file), options);
+      }
+      return this.request("POST", "/templates", input, options);
+    },
     update: (idOrSlug, patch, options = {}) => this.request("PUT", `/templates/${encodeURIComponent(idOrSlug)}`, patch, options),
     archive: (idOrSlug, options = {}) => this.request("DELETE", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
     versions: {
       list: async (idOrSlug, options = {}) => (await this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions`, void 0, options)).data,
-      /** `which`: 'published', 'latest' or a version number. Carries the files. */
-      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${which}`, void 0, options),
-      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)
+      /** `which`: 'published', 'latest', a version number or a channel name (its main version). Carries the files. */
+      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${encodeURIComponent(String(which))}`, void 0, options),
+      /** For a Word or PowerPoint template, pass `file` to replace the document; without it the latest file is kept. */
+      create: (idOrSlug, input, options = {}) => {
+        const path = `/templates/${encodeURIComponent(idOrSlug)}/versions`;
+        if (isOfficeInput(input)) {
+          const { file, ...fields } = input;
+          if (file) return this.request("POST", path, multipart(fields, file), options);
+          return this.request("POST", path, fields, options);
+        }
+        return this.request("POST", path, input, options);
+      },
+      /** The Word or PowerPoint file of a version (`which` as for `get`); needs `template:read`. */
+      file: async (idOrSlug, which = "published", options = {}) => {
+        const path = `/templates/${encodeURIComponent(idOrSlug)}/versions/${encodeURIComponent(String(which))}/file`;
+        return (await this.send("GET", path, void 0, options, "bytes")).body;
+      },
+      /**
+       * Publishes a version. When both versions store a data schema and the new one breaks callers of the
+       * published one, the API refuses with `schema_breaking_change` unless `allowBreaking` is set.
+       */
+      publish: (idOrSlug, number, options = {}) => {
+        const { allowBreaking, ...rest } = options;
+        return this.request(
+          "POST",
+          `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`,
+          allowBreaking ? { allow_breaking: true } : void 0,
+          rest
+        );
+      }
+    },
+    /**
+     * Release channels (`published` and named ones such as `staging`): a render with `version: 'staging'`
+     * uses the version the channel points at. Moves reach renders within a minute.
+     */
+    channels: {
+      list: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/channels`, void 0, options),
+      /** Creates or moves a channel; on `published` this publishes. */
+      set: (idOrSlug, name, move, options = {}) => {
+        const { allowBreaking, ...rest } = options;
+        return this.request(
+          "PUT",
+          `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}`,
+          { ...move, ...allowBreaking ? { allow_breaking: true } : {} },
+          rest
+        );
+      },
+      /** The canary becomes the main version. */
+      promote: (idOrSlug, name, options = {}) => this.channelAction(idOrSlug, name, "promote", options),
+      /** Back to the version before the last move. */
+      rollback: (idOrSlug, name, options = {}) => this.channelAction(idOrSlug, name, "rollback", options),
+      /** Refused with `channel_in_use` while renders of the last hour used the channel, unless `force`. */
+      delete: (idOrSlug, name, options = {}) => {
+        const { force, ...rest } = options;
+        return this.request(
+          "DELETE",
+          `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}${force ? "?force=true" : ""}`,
+          void 0,
+          rest
+        );
+      }
     },
     schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
     /**
@@ -235,13 +365,37 @@ var Formfeed = class {
     /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
     usage: (period = "current", options = {}) => this.request("GET", `/usage?period=${encodeURIComponent(period)}`, void 0, options)
   };
+  /** Workspaces of the key's organisation. Needs `workspace:delete`, which no key has by default. */
+  workspaces = {
+    /**
+     * Deletes a workspace: it leaves the app and the API at once, its keys are revoked and its content
+     * is removed after 30 days. The organisation's last workspace is refused with `last_workspace`.
+     */
+    delete: (id, options = {}) => this.request("DELETE", `/workspaces/${encodeURIComponent(id)}`, void 0, options)
+  };
+  channelAction(idOrSlug, name, action, options) {
+    const { allowBreaking, ...rest } = options;
+    return this.request(
+      "POST",
+      `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}/${action}`,
+      allowBreaking ? { allow_breaking: true } : void 0,
+      rest
+    );
+  }
   /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
   async request(method, path, body, options = {}) {
+    return (await this.send(method, path, body, options)).body;
+  }
+  /**
+   * `request` with the HTTP status, for endpoints whose answer depends on it (201 created, 200 updated).
+   * `bytes` returns a successful body as bytes (file downloads); problems are JSON either way.
+   */
+  async send(method, path, body, options = {}, as = "json") {
     const url = `${this.baseUrl}${path}`;
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
-      accept: "application/json",
-      "user-agent": "formfeed-sdk-ts/0.2"
+      accept: as === "bytes" ? "*/*" : "application/json",
+      "user-agent": "formfeed-sdk-ts/0.3"
     };
     const isForm = typeof FormData !== "undefined" && body instanceof FormData;
     if (body !== void 0 && !isForm) headers["content-type"] = "application/json";
@@ -274,9 +428,15 @@ var Formfeed = class {
         await sleep(this.backoff(attempt, res.headers.get("retry-after")), options.signal);
         continue;
       }
-      if (res.status === 204) return void 0;
+      if (res.status === 204) return { status: 204, body: void 0 };
+      if (as === "bytes" && res.ok) return { status: res.status, body: new Uint8Array(await res.arrayBuffer()) };
       const text = await res.text();
-      const json = text ? JSON.parse(text) : null;
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        if (res.ok) throw new FormfeedError("invalid_response", `the API answered HTTP ${res.status} with a body that is not JSON`, res.status);
+      }
       if (!res.ok) {
         const problem = json ?? {};
         throw new FormfeedError(
@@ -287,7 +447,7 @@ var Formfeed = class {
           res.headers.get("x-request-id")
         );
       }
-      return json;
+      return { status: res.status, body: json };
     }
   }
   backoff(attempt, retryAfter) {

package/index.js

@@ -1,4 +1,20 @@
 // packages/sdk-ts/src/lib/client.ts
+var isOfficeInput = (input) => "file" in input;
+function blobOf(file) {
+  const blob = file.data instanceof Blob ? file.data : new Blob([file.data]);
+  const own = typeof File !== "undefined" && file.data instanceof File ? file.data.name : void 0;
+  return { blob, name: file.name ?? own ?? "document" };
+}
+function multipart(fields, file) {
+  const form = new FormData();
+  const { blob, name } = blobOf(file);
+  form.set("file", blob, name);
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === void 0) continue;
+    form.set(key, typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value));
+  }
+  return form;
+}
 var FormfeedError = class extends Error {
   constructor(code, message, status, problem = null, requestId = null) {
     super(message);
@@ -90,6 +106,11 @@ var Formfeed = class {
     },
     /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
     deleteOutputs: (id, options = {}) => this.request("DELETE", `/renders/${encodeURIComponent(id)}/outputs`, void 0, options),
+    /**
+     * The stored request of a render, to render it again. Needs `render:input`; throws
+     * `render_input_expired` (410) when the workspace keeps no requests or the period ended.
+     */
+    input: (id, options = {}) => this.request("GET", `/renders/${encodeURIComponent(id)}/input`, void 0, options),
     batch: (request, options = {}) => this.request("POST", "/renders/batch", request, {
       ...options,
       idempotencyKey: options.idempotencyKey ?? randomKey()
@@ -104,7 +125,18 @@ var Formfeed = class {
     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)
+    info: (source, options = {}) => this.request("POST", "/pdf/info", { source: idOf(source) }, options),
+    /**
+     * Converts an office document to a PDF render (Starter plan and above): an uploaded file (Word,
+     * Excel, PowerPoint, OpenDocument, RTF or HTML, up to 20 MB, not kept), or the output of a Word or
+     * PowerPoint template render. Costs follow the PDF rule. A busy converter answers 503, which is
+     * retried like any other.
+     */
+    convert: (source, convert = {}, options = {}) => {
+      if (typeof source === "object" && "file" in source)
+        return this.request("POST", "/pdf/convert", multipart({ ...convert }, source.file), withKey(options));
+      return this.request("POST", "/pdf/convert", { ...convert, source: idOf(source) }, withKey(options));
+    }
   };
   /**
    * The workspace file library (`/files`): images and PDFs a template references by name with
@@ -143,6 +175,27 @@ var Formfeed = class {
     /** 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)
   };
+  /** The organisation's brand kit, read-only through the API (it is edited in the app). Needs `template:read`. */
+  brand = {
+    get: (options = {}) => this.request("GET", "/brand", void 0, options)
+  };
+  /**
+   * Shared partials of the organisation. Renders use the current source, so a change reaches every
+   * template that includes the partial without a new version. Needs `template:read` or `template:write`.
+   */
+  partials = {
+    /** Every shared partial, without its source. */
+    list: async (options = {}) => (await this.request("GET", "/partials", void 0, options)).data,
+    /** One partial with its source. */
+    get: (name, options = {}) => this.request("GET", `/partials/${encodeURIComponent(name)}`, void 0, options),
+    /** Creates or replaces a partial; pass `base_version` to fail with 409 when it changed since you read it. */
+    put: async (name, input, options = {}) => {
+      const { status, body } = await this.send("PUT", `/partials/${encodeURIComponent(name)}`, input, options);
+      return { partial: body, created: status === 201 };
+    },
+    /** Removes a partial; templates that still include it fail to render afterwards. */
+    delete: (name, options = {}) => this.request("DELETE", `/partials/${encodeURIComponent(name)}`, void 0, options)
+  };
   jobs = {
     get: (id, options = {}) => this.request("GET", `/jobs/${encodeURIComponent(id)}`, void 0, options),
     waitFor: async (id, options = {}) => {
@@ -162,7 +215,20 @@ var Formfeed = class {
     create: (input, options = {}) => this.request("POST", "/webhooks", input, options),
     update: (id, patch, options = {}) => this.request("PUT", `/webhooks/${encodeURIComponent(id)}`, patch, options),
     delete: (id, options = {}) => this.request("DELETE", `/webhooks/${encodeURIComponent(id)}`, void 0, options),
-    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options)
+    test: (id, options = {}) => this.request("POST", `/webhooks/${encodeURIComponent(id)}/test`, void 0, options),
+    /**
+     * Sends a stored event (`evt_…`) again as a new delivery to a registered endpoint (`webhook:manage`)
+     * or a running listen session (`webhook:listen`).
+     */
+    resend: (eventId, endpointId, options = {}) => this.request("POST", `/webhooks/events/${encodeURIComponent(eventId)}/resend`, { endpoint_id: endpointId }, options),
+    /**
+     * Listen sessions, what `formfeed listen` uses. Needs `webhook:listen`. Starting a session ends the
+     * previous one of the same key; the WebSocket itself is up to the caller.
+     */
+    listen: {
+      start: (input = {}, options = {}) => this.request("POST", "/webhooks/listen", input, options),
+      end: (id, options = {}) => this.request("DELETE", `/webhooks/listen/${encodeURIComponent(id)}`, void 0, options)
+    }
   };
   templates = {
     list: (query = {}, options = {}) => {
@@ -183,15 +249,79 @@ var Formfeed = class {
       return out;
     },
     get: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
-    create: (input, options = {}) => this.request("POST", "/templates", input, options),
+    /** A Word or PowerPoint template (`kind` `docx` or `pptx`) is created from its `file`, sent as multipart. */
+    create: (input, options = {}) => {
+      if (isOfficeInput(input) && input.file) {
+        const { file, ...fields } = input;
+        return this.request("POST", "/templates", multipart(fields, file), options);
+      }
+      return this.request("POST", "/templates", input, options);
+    },
     update: (idOrSlug, patch, options = {}) => this.request("PUT", `/templates/${encodeURIComponent(idOrSlug)}`, patch, options),
     archive: (idOrSlug, options = {}) => this.request("DELETE", `/templates/${encodeURIComponent(idOrSlug)}`, void 0, options),
     versions: {
       list: async (idOrSlug, options = {}) => (await this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions`, void 0, options)).data,
-      /** `which`: 'published', 'latest' or a version number. Carries the files. */
-      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${which}`, void 0, options),
-      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)
+      /** `which`: 'published', 'latest', a version number or a channel name (its main version). Carries the files. */
+      get: (idOrSlug, which = "published", options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/versions/${encodeURIComponent(String(which))}`, void 0, options),
+      /** For a Word or PowerPoint template, pass `file` to replace the document; without it the latest file is kept. */
+      create: (idOrSlug, input, options = {}) => {
+        const path = `/templates/${encodeURIComponent(idOrSlug)}/versions`;
+        if (isOfficeInput(input)) {
+          const { file, ...fields } = input;
+          if (file) return this.request("POST", path, multipart(fields, file), options);
+          return this.request("POST", path, fields, options);
+        }
+        return this.request("POST", path, input, options);
+      },
+      /** The Word or PowerPoint file of a version (`which` as for `get`); needs `template:read`. */
+      file: async (idOrSlug, which = "published", options = {}) => {
+        const path = `/templates/${encodeURIComponent(idOrSlug)}/versions/${encodeURIComponent(String(which))}/file`;
+        return (await this.send("GET", path, void 0, options, "bytes")).body;
+      },
+      /**
+       * Publishes a version. When both versions store a data schema and the new one breaks callers of the
+       * published one, the API refuses with `schema_breaking_change` unless `allowBreaking` is set.
+       */
+      publish: (idOrSlug, number, options = {}) => {
+        const { allowBreaking, ...rest } = options;
+        return this.request(
+          "POST",
+          `/templates/${encodeURIComponent(idOrSlug)}/versions/${number}/publish`,
+          allowBreaking ? { allow_breaking: true } : void 0,
+          rest
+        );
+      }
+    },
+    /**
+     * Release channels (`published` and named ones such as `staging`): a render with `version: 'staging'`
+     * uses the version the channel points at. Moves reach renders within a minute.
+     */
+    channels: {
+      list: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/channels`, void 0, options),
+      /** Creates or moves a channel; on `published` this publishes. */
+      set: (idOrSlug, name, move, options = {}) => {
+        const { allowBreaking, ...rest } = options;
+        return this.request(
+          "PUT",
+          `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}`,
+          { ...move, ...allowBreaking ? { allow_breaking: true } : {} },
+          rest
+        );
+      },
+      /** The canary becomes the main version. */
+      promote: (idOrSlug, name, options = {}) => this.channelAction(idOrSlug, name, "promote", options),
+      /** Back to the version before the last move. */
+      rollback: (idOrSlug, name, options = {}) => this.channelAction(idOrSlug, name, "rollback", options),
+      /** Refused with `channel_in_use` while renders of the last hour used the channel, unless `force`. */
+      delete: (idOrSlug, name, options = {}) => {
+        const { force, ...rest } = options;
+        return this.request(
+          "DELETE",
+          `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}${force ? "?force=true" : ""}`,
+          void 0,
+          rest
+        );
+      }
     },
     schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
     /**
@@ -206,13 +336,37 @@ var Formfeed = class {
     /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
     usage: (period = "current", options = {}) => this.request("GET", `/usage?period=${encodeURIComponent(period)}`, void 0, options)
   };
+  /** Workspaces of the key's organisation. Needs `workspace:delete`, which no key has by default. */
+  workspaces = {
+    /**
+     * Deletes a workspace: it leaves the app and the API at once, its keys are revoked and its content
+     * is removed after 30 days. The organisation's last workspace is refused with `last_workspace`.
+     */
+    delete: (id, options = {}) => this.request("DELETE", `/workspaces/${encodeURIComponent(id)}`, void 0, options)
+  };
+  channelAction(idOrSlug, name, action, options) {
+    const { allowBreaking, ...rest } = options;
+    return this.request(
+      "POST",
+      `/templates/${encodeURIComponent(idOrSlug)}/channels/${encodeURIComponent(name)}/${action}`,
+      allowBreaking ? { allow_breaking: true } : void 0,
+      rest
+    );
+  }
   /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
   async request(method, path, body, options = {}) {
+    return (await this.send(method, path, body, options)).body;
+  }
+  /**
+   * `request` with the HTTP status, for endpoints whose answer depends on it (201 created, 200 updated).
+   * `bytes` returns a successful body as bytes (file downloads); problems are JSON either way.
+   */
+  async send(method, path, body, options = {}, as = "json") {
     const url = `${this.baseUrl}${path}`;
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
-      accept: "application/json",
-      "user-agent": "formfeed-sdk-ts/0.2"
+      accept: as === "bytes" ? "*/*" : "application/json",
+      "user-agent": "formfeed-sdk-ts/0.3"
     };
     const isForm = typeof FormData !== "undefined" && body instanceof FormData;
     if (body !== void 0 && !isForm) headers["content-type"] = "application/json";
@@ -245,9 +399,15 @@ var Formfeed = class {
         await sleep(this.backoff(attempt, res.headers.get("retry-after")), options.signal);
         continue;
       }
-      if (res.status === 204) return void 0;
+      if (res.status === 204) return { status: 204, body: void 0 };
+      if (as === "bytes" && res.ok) return { status: res.status, body: new Uint8Array(await res.arrayBuffer()) };
       const text = await res.text();
-      const json = text ? JSON.parse(text) : null;
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        if (res.ok) throw new FormfeedError("invalid_response", `the API answered HTTP ${res.status} with a body that is not JSON`, res.status);
+      }
       if (!res.ok) {
         const problem = json ?? {};
         throw new FormfeedError(
@@ -258,7 +418,7 @@ var Formfeed = class {
           res.headers.get("x-request-id")
         );
       }
-      return json;
+      return { status: res.status, body: json };
     }
   }
   backoff(attempt, retryAfter) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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, 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 type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } 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, 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 type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } from './lib/client.js';
 export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.js';
 export type { VerifyOptions } from './lib/webhooks.js';