@colixsystems/widget-sdk 0.52.0 → 0.54.0

package/README.md

@@ -19,7 +19,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | ----- | ---------------- | ------- | ------------- |
 | **CORE** | `useTheme()` | `{ colors, spacing, radii, typography }` | `ctx.workspace.theme` — no scope |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
-| **CORE** | `useUser()` | `{ id, email, display_name, roles, group_ids }` | `ctx.user` (snake_case verbatim; `id` null when anonymous) — no scope |
+| **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
@@ -40,6 +40,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (edits also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
+| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId? })` | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
 
@@ -51,7 +52,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.52.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.54.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.54.0
+
+**Generate & save PDFs from a widget (sc-2314).** New `usePdfExport({ spaceType, folderId? })` hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF **server-side** (the platform's headless-Chromium pipeline) and saves it into the end-user's Filestore via `ctx.filestore.files.exportPdf`, resolving to the created file row (`application/pdf`). It reuses the filestore owner_id resolution + per-folder write gate and the existing `files.write:*` scope. Because the rendering is server-side, the capability behaves identically on the web Player and the native Expo export — no browser-only PDF library is added to the vetted set. Pairs with `@colixsystems/filestore-client@0.6.0`'s new `files.exportPdf(...)`. `CONTRACT.version` → `1.38.0`. Additive — no existing hook, primitive, manifest field, or token changed shape.
+
+### What's new in 0.53.0
+
+**Server-action scripts gain a `connectors` global (REQ-ACTION-CONNECTORS, sc-2162).** A `scriptSource` action can now call `connectors.call(slug, { method, path, query, body, headers })` to invoke a tenant-configured REST connector by slug; it returns the upstream's `{ status, headers, body }`. Auth and SSRF protection are handled by the platform host — the script names only a slug (never a tenant or base URL), and the tenant is bound host-side. An unknown slug / SSRF rejection / timeout throws a catchable Error. New entry in `CONTRACT.actionScriptGlobals`; `CONTRACT.version` → `1.37.0`. Additive — no widget hook, primitive, manifest field, or token changed shape.
 
 ### What's new in 0.52.0
 
@@ -274,7 +283,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 
 - **The SDK no longer owns any data facade.** The bespoke per-hook facades that used to live on `WidgetContext` (`ctx.datastore` as an opaque host object, `ctx.directory.listUsers`, `ctx.users`, `ctx.groups`, `ctx.recordPermissions`, `ctx.assets.get`) are replaced by four host-instantiated, host-injected domain clients: `ctx.datastore` (`@colixsystems/datastore-client`), `ctx.directory` (`@colixsystems/directory-client`), `ctx.assets` (`@colixsystems/assets-client`, flattened), `ctx.payments` (`@colixsystems/payments-client`). The SDK imports none of them and ships no HTTP.
 - **`ctx.recordPermissions`, `ctx.users`, `ctx.groups` are removed.** Per-record permission management moved under `ctx.datastore.records(tableId).permissions(recordId)`; user / group administration moved under `ctx.directory.users` / `ctx.directory.groups`. The hooks (`useRecordPermissions`, `useUsers`, `useGroups`) keep the same names and signatures — only the client slice they read changed.
-- **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Hook return rows and `useUser()` fields are therefore snake_case (`display_name`, `group_ids`, `is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`).
+- **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Wire-payload hook return rows are therefore snake_case (`is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`). The one exception is `useUser()`: it reads the host-built `ctx.user` context object, not a wire payload, so its fields are **camelCase** (`displayName`, `groupIds`).
 - **Companion package versions:** `datastore-client 0.5.0`, `assets-client 0.4.0`, `directory-client 0.1.0`, `payments-client 0.1.0`.
 - **`CONTRACT.version` → `1.9.0`.** Breaking for `WidgetContext` consumers (removed slices, renamed wire fields); the hook export surface is unchanged.
 
@@ -284,7 +293,7 @@ Two additive features land in this version.
 
 **A widget may declare server-side actions in its manifest.**
 
-- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerType, scheduleCron?, timeoutMs?, scriptSource }`. `triggerType` is one of `schedule`, `record_created`, `record_updated`, `record_deleted`; `scheduleCron` is required when `triggerType === "schedule"`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
+- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerType, scheduleCron?, timeoutMs?, scriptSource }`. `triggerType` is one of `schedule`, `record_created`, `record_updated`, `record_deleted`; `scheduleCron` is required when `triggerType === "schedule"`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `connectors` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). `connectors.call(slug, { method, path, query, body, headers })` resolves a tenant-configured REST connector by slug and returns `{ status, headers, body }` (auth + SSRF handled by the platform; an unknown slug / SSRF / timeout throws a catchable Error). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
 - **Operators enable actions per tenant** from the Properties Panel. An enabled action materialises a tenant `Action` row **DISABLED** until the operator binds an integration API key (and, for `record_*` triggers, a target table) in the Actions admin page — those bindings are tenant-local, so `triggerTableId` / `apiKeyId` must **not** appear in the manifest (the validator and linter reject them).
 - **New contract fields** `CONTRACT.actionTriggerTypes`, `CONTRACT.actionScriptGlobals`, `CONTRACT.actionScriptMaxBytes` expose the grammar so the Developer page, the AI agent prompt, and `validateManifest` derive it from one source. `validateManifest` now structurally validates `actions`; the marketplace linter rejects malformed / oversized declarations.
 - **New manifest category `ADMINISTRATION`** for app-administration widgets such as User Management. Added to `CONTRACT.manifestCategories`, `validateManifest`, the `WidgetCategory` type, the marketplace category list, and the master-DB `WidgetCategory` enum.
@@ -357,7 +366,7 @@ The "split-implementation + vetted package list" pivot.
 
 ### What's new in 0.9.0
 
-- **`usePayments()` — incoming app-user payments.** Returns `{ requestPayment, getPayment }`. `requestPayment({ amountCents, currency?, description, metadata?, returnPath? })` triggers a one-time charge from the signed-in app user and resolves to `{ id, status, checkoutUrl? }`: when `checkoutUrl` is present the widget opens it (web: navigate; native: `expo-web-browser`) — the user pays in **hosted Stripe Checkout**; when absent (the platform's built-in **mock** provider, the default until Stripe is configured) the charge auto-confirms (`status: "PAID"`). `getPayment(id)` polls the terminal status. Backed by a new `WidgetContext.payments` slice and gated by the new `payments.charge:appUser` scope. **No card data ever touches the widget** — never collect card fields yourself. The charge settles to the workspace owner; the amount is bounded by a platform per-charge cap. Rejections are a structured `PaymentError` (also a new named export) with a stable `.code`.
+- **`usePayments()` — incoming app-user payments.** Returns `{ requestPayment, getPayment }`. `requestPayment({ amountCents, currency?, description, metadata?, returnPath? })` triggers a one-time charge from the signed-in app user and resolves to `{ id, status, checkoutUrl? }`: when `checkoutUrl` is present the widget opens it (web: navigate; native: `expo-web-browser`) — the user pays in the provider's **hosted checkout**; when absent (the platform's built-in **mock** provider, the default until a real provider is configured) the charge auto-confirms (`status: "PAID"`). `getPayment(id)` polls the terminal status. Backed by a new `WidgetContext.payments` slice and gated by the new `payments.charge:appUser` scope. **No card data ever touches the widget** — never collect card fields yourself. The charge settles to the workspace owner; the amount is bounded by a platform per-charge cap. Rejections are a structured `PaymentError` (also a new named export) with a stable `.code`.
 - **`CONTRACT.version` → `1.2.0`** (additive: one new hook, one new context slice, one new scope, one new error class). No existing export changed signature.
 
 ### What was in 0.8.0
@@ -419,7 +428,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, display_name, roles, group_ids }` (snake_case verbatim; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -235,6 +235,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.write:*"],
   },
+  {
+    name: "usePdfExport",
+    signature: "usePdfExport({ spaceType, folderId? })",
+    description:
+      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+      "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 " +
+      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
+      "means the destination folder denied a write, 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.",
+    returnShape: {
+      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exporting: "boolean",
+      error: "Error | null",
+      lastExported: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -818,6 +841,7 @@ const ACTION_TRIGGER_TYPES = [
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
   "fetch",
+  "connectors",
   "console",
   "record",
   "tenantId",
@@ -974,9 +998,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", display_name: "string" },
+    fields: { id: "string", email: "string", displayName: "string" },
   },
   workspace: {
     description:
@@ -1815,7 +1839,26 @@ const CONTRACT = deepFreeze({
   //    `notifications.send:appUser` scope it gates on. No existing hook,
   //    primitive, manifest field, or token changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.36.0",
+  //
+  // 1.37.0: additive (REQ-ACTION-CONNECTORS, sc-2162) — server-action scripts
+  //    gain a `connectors` global. `connectors.call(slug, { method, path,
+  //    query, body, headers })` resolves a tenant-configured REST connector by
+  //    slug and returns `{ status, headers, body }`; auth + SSRF are handled by
+  //    the platform host, and an unknown slug / SSRF / timeout throws a
+  //    catchable Error. New entry in ACTION_SCRIPT_GLOBALS only — no widget
+  //    hook, primitive, manifest field, or token changed shape; minor bump.
+  //
+  // 1.38.0: additive (sc-2314) — new `usePdfExport({ spaceType, folderId? })`
+  //    hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to
+  //    a PDF server-side (the host's headless-Chromium pipeline) and SAVES it
+  //    into the Filestore via `ctx.filestore.files.exportPdf`, resolving to the
+  //    created file row (`application/pdf`). Reuses the filestore owner_id
+  //    resolution + per-folder write gate; gated on the existing
+  //    `files.write:*` scope. The same server-side renderer backs the web
+  //    Player and the native export, so no browser-only PDF library is added
+  //    to the vetted set. No existing hook, primitive, manifest field, or
+  //    token changed shape — minor bump.
+  version: "1.38.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -235,6 +235,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.write:*"],
   },
+  {
+    name: "usePdfExport",
+    signature: "usePdfExport({ spaceType, folderId? })",
+    description:
+      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+      "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 " +
+      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
+      "means the destination folder denied a write, 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.",
+    returnShape: {
+      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exporting: "boolean",
+      error: "Error | null",
+      lastExported: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -818,6 +841,7 @@ const ACTION_TRIGGER_TYPES = [
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
   "fetch",
+  "connectors",
   "console",
   "record",
   "tenantId",
@@ -974,9 +998,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", display_name: "string" },
+    fields: { id: "string", email: "string", displayName: "string" },
   },
   workspace: {
     description:
@@ -1815,7 +1839,26 @@ const CONTRACT = deepFreeze({
   //    `notifications.send:appUser` scope it gates on. No existing hook,
   //    primitive, manifest field, or token changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.36.0",
+  //
+  // 1.37.0: additive (REQ-ACTION-CONNECTORS, sc-2162) — server-action scripts
+  //    gain a `connectors` global. `connectors.call(slug, { method, path,
+  //    query, body, headers })` resolves a tenant-configured REST connector by
+  //    slug and returns `{ status, headers, body }`; auth + SSRF are handled by
+  //    the platform host, and an unknown slug / SSRF / timeout throws a
+  //    catchable Error. New entry in ACTION_SCRIPT_GLOBALS only — no widget
+  //    hook, primitive, manifest field, or token changed shape; minor bump.
+  //
+  // 1.38.0: additive (sc-2314) — new `usePdfExport({ spaceType, folderId? })`
+  //    hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to
+  //    a PDF server-side (the host's headless-Chromium pipeline) and SAVES it
+  //    into the Filestore via `ctx.filestore.files.exportPdf`, resolving to the
+  //    created file row (`application/pdf`). Reuses the filestore owner_id
+  //    resolution + per-folder write gate; gated on the existing
+  //    `files.write:*` scope. The same server-side renderer backs the web
+  //    Player and the native export, so no browser-only PDF library is added
+  //    to the vetted set. No existing hook, primitive, manifest field, or
+  //    token changed shape — minor bump.
+  version: "1.38.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -113,7 +113,7 @@ export function useWidgetStyle() {
 
 /**
  * Returns the active end-user identity VERBATIM from the host, e.g.
- *   `{ id, email, display_name, roles, group_ids }` (snake_case fields).
+ *   `{ id, email, displayName, roles, groupIds }` (camelCase — host-built context, not a wire payload).
  *
  * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
  * which renders widgets as if signed-out so the public branch shows). The
@@ -1578,6 +1578,87 @@ export function useFilestoreUpload(options) {
   return { upload, uploading, error, lastUploaded };
 }
 
+/**
+ * sc-2314 — render an HTML string to a PDF server-side and SAVE it into the
+ * end-user's Filestore space. Returns `{ exportToPdf, exporting, error,
+ * lastExported }`. The widget passes the SPACE (`{ spaceType, folderId? }`);
+ * the hook resolves `owner_id` the same way the upload hook does (tenant for
+ * PROJECT, app user for PERSONAL) and posts JSON to
+ * `ctx.filestore.files.exportPdf`.
+ *
+ * `exportToPdf(html, { fileName?, folderId? })` resolves to the created file
+ * record (`{ id, name, mime_type: "application/pdf", presigned_url, … }`).
+ * `fileName` defaults to `document.pdf` and is forced to a `.pdf` suffix by the
+ * backend. The HTML is rendered by the host's PDF service (headless Chromium)
+ * — the SAME server-side pipeline backs the web Player and the native export,
+ * so the capability behaves identically on both platforms (no browser-only PDF
+ * library is involved).
+ *
+ * A 404 means the destination folder denied a write; a 413 means the rendered
+ * PDF exceeded the size cap.
+ */
+export function usePdfExport(options) {
+  const ctx = useWidgetContextOrThrow("usePdfExport");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.exportPdf !== "function"
+  ) {
+    throw new Error(
+      "usePdfExport: host did not inject a filestore client (ctx.filestore.files.exportPdf)",
+    );
+  }
+  const { spaceType = "project", folderId: defaultFolderId = null } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [exporting, setExporting] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastExported, setLastExported] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+
+  const exportToPdf = useCallback(
+    async (html, overrides) => {
+      if (typeof html !== "string" || html.trim().length === 0) {
+        throw new Error("usePdfExport: html is required");
+      }
+      if (!ownerId) {
+        const err = new Error("Sign in to save a PDF");
+        setError(err);
+        throw err;
+      }
+      const folderId =
+        overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
+          ? overrides.folderId
+          : defaultFolderId;
+      const fileName = overrides && overrides.fileName;
+      const body = {
+        html,
+        space_type: String(spaceType || "project").toUpperCase(),
+        owner_id: ownerId,
+      };
+      if (folderId) body.folder_id = folderId;
+      if (fileName) body.file_name = fileName;
+      setExporting(true);
+      setError(null);
+      try {
+        const created = await filesRef.current.exportPdf(body);
+        setLastExported(created || null);
+        setExporting(false);
+        return created;
+      } catch (err) {
+        setError(err);
+        setExporting(false);
+        throw err;
+      }
+    },
+    [ownerId, defaultFolderId, spaceType],
+  );
+
+  return { exportToPdf, exporting, error, lastExported };
+}
+
 /**
  * Browse the end-user's Filestore folders. Returns { folders, loading, error,
  * refetch }. Mirrors useFilestoreFiles for subfolder navigation: the widget
@@ -2638,8 +2719,8 @@ function toPaymentError(err) {
  *   requestPayment({ amountCents, currency?, description, metadata? })
  *     → Promise<{ id, status, checkoutUrl?, ... }>. The host either
  *       auto-confirms (mock provider, `status: "PAID"`, no redirect) or
- *       returns a hosted-Checkout `checkoutUrl` the widget should open
- *       (Stripe provider, `status: "PENDING"`). Rejects with a
+ *       returns a hosted-checkout `checkoutUrl` the widget should open
+ *       (Mollie provider, `status: "PENDING"`). Rejects with a
  *       `PaymentError`.
  *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
  *

package/dist/index.d.ts

@@ -424,13 +424,13 @@ export interface WidgetContext<TProps = unknown> {
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
-  /** Active end-user identity, snake_case verbatim. `id` is null when anonymous. */
+  /** Active end-user identity from the host-built context (camelCase, not a wire payload). `id` is null when anonymous. */
   user: {
     id: string | null;
     email: string | null;
-    display_name: string | null;
+    displayName: string | null;
     roles: string[];
-    group_ids: string[];
+    groupIds: string[];
   };
   workspace: {
     id: string;
@@ -624,8 +624,8 @@ export interface PaymentResult {
   currency?: string;
   description?: string;
   /**
-   * Present (Stripe provider) when the app user must complete a hosted
-   * Checkout: the widget should open this URL. Absent under the mock
+   * Present (Mollie provider) when the app user must complete a hosted
+   * checkout: the widget should open this URL. Absent under the mock
    * provider, where the charge auto-confirms (`status: "PAID"`).
    */
   checkoutUrl?: string | null;
@@ -883,9 +883,9 @@ export function useI18n(): {
 export function useUser(): {
   id: string | null;
   email: string | null;
-  display_name: string | null;
+  displayName: string | null;
   roles: string[];
-  group_ids: string[];
+  groupIds: string[];
 };
 
 /**

package/dist/index.js

@@ -19,6 +19,7 @@ export {
   useAssetsByTag,
   useFilestoreFiles,
   useFilestoreUpload,
+  usePdfExport,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,

package/dist/index.native.js

@@ -19,6 +19,7 @@ export {
   useAssetsByTag,
   useFilestoreFiles,
   useFilestoreUpload,
+  usePdfExport,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",