@colixsystems/widget-sdk 0.263.0 → 0.265.0

package/README.md

@@ -86,7 +86,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.263.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)
+
+**A `datastoreTemplate` column can be a `UUID`.** It holds a UUID, checked on every write and stored lowercase, so an id typed in capitals still matches. `defaultValue: "@uuid"` gives every new row its own random id, and `defaultLocked: true` with it makes that id server-generated and unforgeable. Sample `rows` may seed one. `DatastoreSchemaColumn.data_type` now also lists `UUID` (and `DATETIME`, which was missing). Additive.
 
 ### What's new in 0.263.0 (contract 1.213.0)
 
@@ -1019,7 +1027,7 @@ See [Bundled images and sounds](#bundled-images-and-sounds). Additive: a widget
 
 **Files can be attached to a datastore record and stay private to it.** `useFilestoreUpload({ spaceType: "record", recordId })` attaches the uploaded file to that record, and `useFilestoreFiles({ spaceType: "record", recordId, type })` lists its attachments newest first (`type: "media"` for images and videos, `"document"` for the rest). Exactly the people who may read the record may read its attachments, through the same permission check as the record itself. Uploading needs write on the record, only the uploader may delete an attachment, and removing the record removes its attachments. A record attachment's URL is issued to one viewer and lives about ten minutes, so re-resolve it (`useFilestoreFile(id).refetch()`) when an image fails to load. The new `useFilestoreDelete()` returns `{ remove, removing, error }`: `remove(fileId)` deletes a record attachment permanently (only its uploader may) and moves any other file to the trash. `useFilestoreCopy().copy(fileId, { spaceType: "record", recordId })` attaches a copy of a file to a record, with the same write check as uploading there. `useCamera().pick({ multiple: true })` lets the user choose up to 10 photos from the device library at once and resolves an array of assets; `pick()` alone is unchanged. `<Avatar seed={user.id} />` draws the initials on that person's own colour, the same one the Studio's member lists use, and `avatarColorFor(seed)` returns it.
 
-**A `datastoreTemplate` can make inherited access read-only and stamp author columns on the server.** An `inheritAcl` RELATION column may add `inheritAclReadOnly: true`. Rows then inherit only READ access from the row they point at: members of a conversation read every message in it and may post into it, but change or delete only the messages they created (pair it with `grantCreatorPermissions`). This also holds down a chain, such as a reaction on a message in a conversation. A column may declare `defaultValue`, which is written when a create omits the column. Use `"@currentUser"` on a USER column, `"@now"` on a DATE or DATETIME column, or a literal of the column's own type. FILE, RELATION and USER_GROUP columns take no default, because ids belong to the installing workspace. `defaultLocked: true` on a `"@currentUser"` or `"@now"` default makes the server always stamp it. Any value a client sends for the column is ignored on create and on update, so a `Sender` or `CreatedBy` column is always the real author. `immutable: true` makes a column write-once: a create sets it from the value sent or the default, and any value sent for it on update is ignored, so a message's `Conversation` cannot be moved after it is posted. It is not valid on a MANY_TO_MANY relation, whose links live outside the row. Additive.
+**A `datastoreTemplate` can make inherited access read-only and stamp author columns on the server.** An `inheritAcl` RELATION column may add `inheritAclReadOnly: true`. Rows then inherit only READ access from the row they point at: members of a conversation read every message in it and may post into it, but change or delete only the messages they created (pair it with `grantCreatorPermissions`). This also holds down a chain, such as a reaction on a message in a conversation. A column may declare `defaultValue`, which is written when a create omits the column. Use `"@currentUser"` on a USER column, `"@now"` on a DATE or DATETIME column, `"@uuid"` on a UUID column, or a literal of the column's own type. FILE, RELATION and USER_GROUP columns take no default, because ids belong to the installing workspace. `defaultLocked: true` on a `"@currentUser"` or `"@now"` default makes the server always stamp it. Any value a client sends for the column is ignored on create and on update, so a `Sender` or `CreatedBy` column is always the real author. `immutable: true` makes a column write-once: a create sets it from the value sent or the default, and any value sent for it on update is ignored, so a message's `Conversation` cannot be moved after it is posted. It is not valid on a MANY_TO_MANY relation, whose links live outside the row. Additive.
 
 **A user can mute one record's notifications.** `useRecordMute(tableId, recordId)` returns `{ muted, mutedUntil, loading, error, mute, unmute, refetch }`. `mute(until)` takes an ISO time or a `Date`, or `null` (or nothing) to mute until `unmute()`. While a mute is active, a server action's `notifications.notifyRecordSubjects` on that record sends the user nothing: no inbox row, no push, no email. `mutedUntil` is the ISO time the mute ends, or `null` when it lasts until unmuted, and `muted` turns false by itself when that time passes. The user must be able to read the record, so a record they cannot read fails with `NotificationError { code: "RECORD_NOT_FOUND" }`, just like one that does not exist. A falsy id returns a stable not-muted result with no request. On a host without `ctx.notifications.mutes` (the Builder canvas preview) the hook reads not muted, and `mute()` / `unmute()` reject with `NOTIFICATIONS_UNAVAILABLE`. No scope is needed, because it only changes the user's own setting. To show mutes in a list, call `useRecordMutes(tableId)` once: `isMuted(recordId)` answers for every row from one request, and a mute made through `useRecordMute` on the same table shows at once. `NotificationError.code` now carries the server's code when it sends one (`INVALID_TITLE`, `RECORD_NOT_FOUND`, …), and a 401 reads `AUTH_REQUIRED`. Additive.
 

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",
@@ -3959,7 +3967,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6432,7 +6440,12 @@ const CONTRACT = deepFreeze({
   //    scope. A widget runs one of the workspace's Actions and reads its result.
   // 1.213.0: behavioural (sc-13933) — `<Tabs>` wraps tabs that do not fit onto
   //    another line instead of scrolling them out of sight.
-  version: "1.213.0",
+  // 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`.
+  // 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",
@@ -3956,7 +3964,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6429,7 +6437,12 @@ const CONTRACT = deepFreeze({
   //    scope. A widget runs one of the workspace's Actions and reads its result.
   // 1.213.0: behavioural (sc-13933) — `<Tabs>` wraps tabs that do not fit onto
   //    another line instead of scrolling them out of sight.
-  version: "1.213.0",
+  // 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`.
+  // 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/dist/index.d.ts

@@ -185,12 +185,14 @@ export interface WidgetDatastoreTemplateColumn {
     | "FLOAT"
     | "BOOL"
     | "DATE"
+    | "DATETIME"
     | "FILE"
     | "STRING_ARRAY"
     | "INT_ARRAY"
     | "RELATION"
     | "USER"
-    | "USER_GROUP";
+    | "USER_GROUP"
+    | "UUID";
   required?: boolean;
   /** For RELATION columns only — points at a sibling table's `suffix`. */
   targetSuffix?: string;
@@ -221,14 +223,14 @@ export interface WidgetDatastoreTemplateColumn {
   encrypted?: boolean;
   /**
    * Written when a create omits the column. `"@currentUser"` (USER) stamps
-   * the signed-in user and `"@now"` (DATE / DATETIME) the current date or
-   * time. Other types take a literal of their own type. FILE, RELATION and
+   * the signed-in user, `"@now"` (DATE / DATETIME) the current date or
+   * time, and `"@uuid"` (UUID) a new random id per row. Other types take a literal of their own type. FILE, RELATION and
    * USER_GROUP columns take none, because ids belong to the installing
    * workspace.
    */
   defaultValue?: unknown;
   /**
-   * With a `"@currentUser"` or `"@now"` default only: the server always
+   * With a `"@currentUser"`, `"@now"` or `"@uuid"` default only: the server always
    * stamps it. Any value a client sends for the column is ignored on create
    * and on update, so an author column cannot be forged.
    */
@@ -1633,12 +1635,14 @@ export interface DatastoreSchemaColumn {
     | "FLOAT"
     | "BOOL"
     | "DATE"
+    | "DATETIME"
     | "FILE"
     | "STRING_ARRAY"
     | "INT_ARRAY"
     | "RELATION"
     | "USER"
-    | "USER_GROUP";
+    | "USER_GROUP"
+    | "UUID";
   required: boolean;
   /** For RELATION columns only. */
   relation_type?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY" | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.263.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",
@@ -3956,7 +3964,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6429,7 +6437,12 @@ const CONTRACT = deepFreeze({
   //    scope. A widget runs one of the workspace's Actions and reads its result.
   // 1.213.0: behavioural (sc-13933) — `<Tabs>` wraps tabs that do not fit onto
   //    another line instead of scrolling them out of sight.
-  version: "1.213.0",
+  // 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`.
+  // 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,