@formfeed/sdk 0.1.0 → 0.3.0

package/README.md

@@ -43,6 +43,27 @@ 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'
+
+// 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);
@@ -54,6 +70,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;
@@ -117,11 +135,96 @@ 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()
     })
   };
+  /**
+   * 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),
+    /**
+     * 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
+   * `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)
+  };
+  /** 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 = {}) => {
@@ -141,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 = {}) => {
@@ -162,32 +278,127 @@ 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
+        );
+      }
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options)
+    /**
+     * 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),
+    /**
+     * 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),
     /** 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.1"
+      accept: as === "bytes" ? "*/*" : "application/json",
+      "user-agent": "formfeed-sdk-ts/0.3"
     };
-    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 +410,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) {
@@ -217,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(
@@ -230,7 +447,7 @@ var Formfeed = class {
           res.headers.get("x-request-id")
         );
       }
-      return json;
+      return { status: res.status, body: json };
     }
   }
   backoff(attempt, retryAfter) {