@colixsystems/widget-sdk 0.264.0 → 0.265.0

package/README.md

@@ -86,7 +86,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.264.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.265.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.265.0 (contract 1.215.0)
+
+- **`usePdfExport` appends stored PDFs.** `openPdf(html, { appendFileIds })` and `exportToPdf(html, { appendFileIds })` take up to 20 Filestore file ids; every page of each PDF follows the rendered HTML, in order, on the web Player and in the native export alike (the merge runs server-side). An id the user cannot download, or a file that is not a readable PDF (password-protected, malformed), rejects the call with `err.details.file_id` naming it: 404 `FILE_NOT_FOUND`, 403 `FILE_DOWNLOAD_NOT_PERMITTED`, 422 `PDF_NOT_MERGEABLE`.
 
 ### What's new in 0.264.0 (contract 1.214.0)
 

package/dist/contract.cjs

@@ -1539,7 +1539,7 @@ const HOOKS = [
     optionalArgs: ["spaceType", "folderId"],
     description:
       "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
-      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "it. `openPdf(html, { fileName?, appendFileIds? })` is THE way to give the user a PDF " +
       "to view, print, download or share: it renders the HTML and opens the " +
       "result — the browser's PDF viewer in a new tab on the web Player, the " +
       "OS print / share sheet in the native export — and SAVES NOTHING, so " +
@@ -1555,19 +1555,27 @@ const HOOKS = [
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
-      "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
+      "`exportToPdf(html, { fileName?, folderId?, appendFileIds? })` resolves to the created " +
       "file row (mime_type `application/pdf`) or throws the wire error; " +
       "`err.status` 403/404 means the destination denied the add (403 " +
       "when the caller can see the position, 404 when it cannot), a 413 " +
       "that the rendered " +
       "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
-      "Player and the native export, so no browser-only PDF library is used.",
+      "Player and the native export, so no browser-only PDF library is used. " +
+      "To put a record's attached PDFs INSIDE the document, pass their Filestore " +
+      "file ids as `appendFileIds` (at most 20) to either call: every page of " +
+      "each file follows the rendered HTML, in the order given. Do not try to " +
+      "embed a PDF through an <img>, <iframe> or link. Each id must be a PDF the " +
+      "user may download, or the call rejects naming it in `err.details.file_id`: " +
+      "404 FILE_NOT_FOUND, 403 FILE_DOWNLOAD_NOT_PERMITTED, or 422 " +
+      "PDF_NOT_MERGEABLE (not a PDF, password-protected, or unreadable). On a " +
+      "422, drop that id and call again so the rest of the report still opens.",
     returnShape: {
-      openPdf: "(html, { fileName? }) => Promise<void>",
+      openPdf: "(html, { fileName?, appendFileIds? }) => Promise<void>",
       opening: "boolean",
       canOpenPdf: "boolean",
-      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exportToPdf: "(html, { fileName?, folderId?, appendFileIds? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
       lastExported: "FilestoreFile | null",
@@ -6435,7 +6443,9 @@ const CONTRACT = deepFreeze({
   // 1.214.0: additive (sc-13746) — a datastoreTemplate column may be a
   //    `UUID` (validated, stored lowercase); `"@uuid"` defaults it to a new
   //    random id per row and may be `defaultLocked`.
-  version: "1.214.0",
+  // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
+  //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
+  version: "1.215.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1536,7 +1536,7 @@ const HOOKS = [
     optionalArgs: ["spaceType", "folderId"],
     description:
       "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
-      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "it. `openPdf(html, { fileName?, appendFileIds? })` is THE way to give the user a PDF " +
       "to view, print, download or share: it renders the HTML and opens the " +
       "result — the browser's PDF viewer in a new tab on the web Player, the " +
       "OS print / share sheet in the native export — and SAVES NOTHING, so " +
@@ -1552,19 +1552,27 @@ const HOOKS = [
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
-      "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
+      "`exportToPdf(html, { fileName?, folderId?, appendFileIds? })` resolves to the created " +
       "file row (mime_type `application/pdf`) or throws the wire error; " +
       "`err.status` 403/404 means the destination denied the add (403 " +
       "when the caller can see the position, 404 when it cannot), a 413 " +
       "that the rendered " +
       "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
-      "Player and the native export, so no browser-only PDF library is used.",
+      "Player and the native export, so no browser-only PDF library is used. " +
+      "To put a record's attached PDFs INSIDE the document, pass their Filestore " +
+      "file ids as `appendFileIds` (at most 20) to either call: every page of " +
+      "each file follows the rendered HTML, in the order given. Do not try to " +
+      "embed a PDF through an <img>, <iframe> or link. Each id must be a PDF the " +
+      "user may download, or the call rejects naming it in `err.details.file_id`: " +
+      "404 FILE_NOT_FOUND, 403 FILE_DOWNLOAD_NOT_PERMITTED, or 422 " +
+      "PDF_NOT_MERGEABLE (not a PDF, password-protected, or unreadable). On a " +
+      "422, drop that id and call again so the rest of the report still opens.",
     returnShape: {
-      openPdf: "(html, { fileName? }) => Promise<void>",
+      openPdf: "(html, { fileName?, appendFileIds? }) => Promise<void>",
       opening: "boolean",
       canOpenPdf: "boolean",
-      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exportToPdf: "(html, { fileName?, folderId?, appendFileIds? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
       lastExported: "FilestoreFile | null",
@@ -6432,7 +6440,9 @@ const CONTRACT = deepFreeze({
   // 1.214.0: additive (sc-13746) — a datastoreTemplate column may be a
   //    `UUID` (validated, stored lowercase); `"@uuid"` defaults it to a new
   //    random id per row and may be `defaultLocked`.
-  version: "1.214.0",
+  // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
+  //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
+  version: "1.215.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -5171,7 +5171,7 @@ export function usePdfExport(options) {
     try {
       await viewer.open({
         fileName: _pdfFileName(overrides && overrides.fileName),
-        load: () => files.renderPdf({ html }),
+        load: () => files.renderPdf(_pdfRenderBody(html, overrides)),
       });
     } catch (err) {
       setError(err);
@@ -5204,6 +5204,7 @@ export function usePdfExport(options) {
       };
       if (folderId) body.folder_id = folderId;
       if (fileName) body.file_name = fileName;
+      Object.assign(body, _pdfRenderBody(html, overrides));
       setExporting(true);
       setError(null);
       try {
@@ -5231,6 +5232,12 @@ export function usePdfExport(options) {
   };
 }
 
+// `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
+function _pdfRenderBody(html, overrides) {
+  const ids = overrides && overrides.appendFileIds;
+  return Array.isArray(ids) && ids.length > 0 ? { html, append_file_ids: ids } : { html };
+}
+
 function _canOpenPdf(viewer) {
   return Boolean(
     viewer &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.264.0",
+  "version": "0.265.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1536,7 +1536,7 @@ const HOOKS = [
     optionalArgs: ["spaceType", "folderId"],
     description:
       "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
-      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "it. `openPdf(html, { fileName?, appendFileIds? })` is THE way to give the user a PDF " +
       "to view, print, download or share: it renders the HTML and opens the " +
       "result — the browser's PDF viewer in a new tab on the web Player, the " +
       "OS print / share sheet in the native export — and SAVES NOTHING, so " +
@@ -1552,19 +1552,27 @@ const HOOKS = [
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
-      "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
+      "`exportToPdf(html, { fileName?, folderId?, appendFileIds? })` resolves to the created " +
       "file row (mime_type `application/pdf`) or throws the wire error; " +
       "`err.status` 403/404 means the destination denied the add (403 " +
       "when the caller can see the position, 404 when it cannot), a 413 " +
       "that the rendered " +
       "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
-      "Player and the native export, so no browser-only PDF library is used.",
+      "Player and the native export, so no browser-only PDF library is used. " +
+      "To put a record's attached PDFs INSIDE the document, pass their Filestore " +
+      "file ids as `appendFileIds` (at most 20) to either call: every page of " +
+      "each file follows the rendered HTML, in the order given. Do not try to " +
+      "embed a PDF through an <img>, <iframe> or link. Each id must be a PDF the " +
+      "user may download, or the call rejects naming it in `err.details.file_id`: " +
+      "404 FILE_NOT_FOUND, 403 FILE_DOWNLOAD_NOT_PERMITTED, or 422 " +
+      "PDF_NOT_MERGEABLE (not a PDF, password-protected, or unreadable). On a " +
+      "422, drop that id and call again so the rest of the report still opens.",
     returnShape: {
-      openPdf: "(html, { fileName? }) => Promise<void>",
+      openPdf: "(html, { fileName?, appendFileIds? }) => Promise<void>",
       opening: "boolean",
       canOpenPdf: "boolean",
-      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exportToPdf: "(html, { fileName?, folderId?, appendFileIds? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
       lastExported: "FilestoreFile | null",
@@ -6432,7 +6440,9 @@ const CONTRACT = deepFreeze({
   // 1.214.0: additive (sc-13746) — a datastoreTemplate column may be a
   //    `UUID` (validated, stored lowercase); `"@uuid"` defaults it to a new
   //    random id per row and may be `defaultLocked`.
-  version: "1.214.0",
+  // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
+  //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
+  version: "1.215.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,