@colixsystems/widget-sdk 0.17.0 → 0.19.0

package/dist/contract.js

@@ -168,12 +168,12 @@ const HOOKS = [
     name: "useDirectory",
     signature: "useDirectory(query?)",
     returnShape: {
-      users: "Array<{ id, name, role }>",
+      users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: ["directory.listUsers"],
+    requiredContextSlice: ["directory.users"],
     scopes: ["directory.read:users"],
   },
   {
@@ -207,28 +207,26 @@ const HOOKS = [
     name: "useUsers",
     signature: "useUsers(query?)",
     description:
-      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
-      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
-      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
-      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+      "AppUser administration via the injected directory-client at " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate}. Returns " +
+      "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
+      "list returns the { data, meta } envelope verbatim — the hook unwraps " +
+      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "scope; mutations need users.write:*. The `invite` call accepts " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host).",
     returnShape: {
-      users: "Array<{ id, name, email?, role, isActive }>",
+      users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "users.listUsers",
-      "users.invite",
-      "users.deactivate",
-      "users.reactivate",
-      "users.remove",
-    ],
+    requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
@@ -240,11 +238,14 @@ const HOOKS = [
     name: "useGroups",
     signature: "useGroups(query?)",
     description:
-      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
-      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "AppUserGroup administration via the injected directory-client at " +
+      "ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}. " +
+      "Returns { groups, loading, error, refetch, create, remove, addMember, " +
+      "removeMember }. list returns the { data, meta } envelope verbatim — the " +
+      "hook unwraps res.data; rows are snake_case. Reads need groups.read:*; " +
       "mutations need groups.write:*.",
     returnShape: {
-      groups: "Array<{ id, name, memberCount }>",
+      groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
@@ -256,15 +257,50 @@ const HOOKS = [
       removeMember:
         "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "groups.listGroups",
-      "groups.create",
-      "groups.remove",
-      "groups.addMember",
-      "groups.removeMember",
-    ],
+    requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management for a single record. Reads the injected datastore-client at
+  // ctx.datastore.records(tableId).permissions(recordId) (the recordPermissions
+  // facade was folded into the datastore-client). The backend gates the call
+  // on `can_grant` for the target record (Studio owners short-circuit;
+  // APP_USER actors must hold `can_grant` via REQ-ACL-05 / REQ-ACL-06). A
+  // widget that declares the scope but whose caller lacks the grant receives
+  // `PermissionError { code: 'FORBIDDEN' }`.
+  {
+    name: "useRecordPermissions",
+    signature: "useRecordPermissions(tableId, recordId)",
+    description:
+      "Manage per-record VirtualPermission grants on a single record via the " +
+      "injected datastore-client at " +
+      "ctx.datastore.records(tableId).permissions(recordId).{list,grant,update,revoke}. " +
+      "Returns { permissions, loading, error, grant, revoke, update, refetch } " +
+      "where permissions is Array<{ id, user_id, group_id, can_read, can_write, " +
+      "can_delete, can_grant }> (snake_case rows verbatim; list() returns the " +
+      "{ data, meta } envelope and the hook unwraps res.data). grant/update " +
+      "bodies are snake_case verbatim ({ user_id | group_id, can_read, " +
+      "can_write, can_delete, can_grant }). Mutating requires acl.write:records " +
+      "scope AND can_grant on the target record (REQ-ACL-RELINHERIT-05: " +
+      "APP_USER actors with can_grant are accepted, not only Studio owners). " +
+      "When tableId or recordId is null/empty the hook collapses to an empty " +
+      "no-op result without a network round-trip.",
+    returnShape: {
+      permissions:
+        "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
+      loading: "boolean",
+      error: "PermissionError | null",
+      grant:
+        "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      revoke:
+        "(permissionId) => Promise<void>  // rejects with PermissionError",
+      update:
+        "(permissionId, { can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["acl.write:records"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks.
   {
     name: "useClipboard",
@@ -414,10 +450,40 @@ const CATEGORIES = [
   "DATA",
   "MEDIA",
   "COMMUNICATION",
+  // REQ-USERMGMT-06: app-administration widgets (User Management, …) the
+  // published app embeds for its own member management — its own palette
+  // section, distinct from COMMUNICATION.
+  "ADMINISTRATION",
   "CUSTOM",
 ];
 const PLATFORMS = ["web", "native"];
 
+// REQ-WIDGET-ACTION — server-side actions a widget may declare in its
+// manifest. Each runs in the shared isolated-vm action runner (see backend
+// action-runner.service.js) on a cron schedule or in response to a record
+// CRUD event — NEVER in the rendered app, so they never affect Player ↔
+// export parity. The trigger vocabulary mirrors the backend Action model.
+const ACTION_TRIGGER_TYPES = [
+  "schedule",
+  "record_created",
+  "record_updated",
+  "record_deleted",
+];
+// Globals the action script runs against (the runner's surface) — distinct
+// from the React/SDK widget surface, so the component import/banned-API
+// linter does NOT scan action scripts.
+const ACTION_SCRIPT_GLOBALS = [
+  "datastore",
+  "fetch",
+  "console",
+  "record",
+  "tenantId",
+  "triggerType",
+  "triggerTableId",
+];
+// Mirrors action.service.js SCRIPT_MAX_BYTES.
+const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -503,6 +569,17 @@ const MANIFEST_SCHEMA = {
     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: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls.",
   },
+  actions: {
+    type: "object[]",
+    required: false,
+    description:
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      ACTION_TRIGGER_TYPES.join(", ") +
+      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      ACTION_SCRIPT_GLOBALS.join(", ") +
+      " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
+    default: [],
+  },
 };
 
 const WIDGET_CONTEXT_SHAPE = {
@@ -518,9 +595,10 @@ const WIDGET_CONTEXT_SHAPE = {
     fields: { id: "manifest.id", version: "manifest.version" },
   },
   user: {
-    description: "Signed-in user ({ id, email, displayName }).",
+    description:
+      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", displayName: "string" },
+    fields: { id: "string", email: "string", display_name: "string" },
   },
   workspace: {
     description:
@@ -540,19 +618,30 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   datastore: {
     description:
-      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) }, schema(table) -> Promise<{ id, name, columns: [...] }> }. `records` backs the query/record/mutation hooks; `schema` backs useDatastoreSchema() and resolves a table's column structure (no row data).",
+      "Injected @colixsystems/datastore-client instance. " +
+      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
+      "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function" },
+    fields: { records: "function", schema: "function", tables: "object" },
   },
   directory: {
     description:
-      "Read-only user directory. { listUsers(query?) -> Promise<Array<{ id, name, role }>> }. Backs useDirectory(); for chat people-lists / @-mention pickers / author-id resolution. Requires the directory.read:users scope.",
+      "Injected @colixsystems/directory-client instance. " +
+      "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
+      "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
+      "invites: { list(), revoke(id), resend(id) } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { listUsers: "function" },
+    fields: { users: "object", groups: "object" },
   },
   files: {
     description:
-      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+      "Injected @colixsystems/files-client instance, FLATTENED so file ops are top-level. " +
+      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData), folders: { list, create }, shares: { list, create, remove } }. " +
+      "Backs useFile(); the returned file already carries an absolute url the widget can drop into an <Image source>.",
     required: true,
     fields: { get: "function" },
   },
@@ -569,42 +658,17 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Incoming app-user payments (REQ-BILL-07-WIDGETPAY). { requestPayment({ amountCents, currency?, description, metadata? }) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
-  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
-  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
-  // APP_USER cannot forge scope claims, and the request is additionally
-  // gated by a SystemAcl `users.read` / `users.write` capability grant.
-  users: {
-    description:
-      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
-    required: true,
-    fields: {
-      listUsers: "function",
-      invite: "function",
-      deactivate: "function",
-      reactivate: "function",
-      remove: "function",
-    },
-  },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
-  // backing useGroups(). Reads gated by `groups.read:*`; mutations by
-  // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
-  groups: {
-    description:
-      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
-    required: true,
-    fields: {
-      listGroups: "function",
-      create: "function",
-      remove: "function",
-      addMember: "function",
-      removeMember: "function",
-    },
-  },
+  // REQ-WSDK-DOMAIN-CLIENTS — the AppUser administration, AppUserGroup
+  // administration, and per-record VirtualPermission facades that used to
+  // live here (`users`, `groups`, `recordPermissions`) were folded into the
+  // injected domain-client instances: useUsers()/useGroups() read
+  // ctx.directory.{users,groups}; useRecordPermissions() reads
+  // ctx.datastore.records(table).permissions(record). See the `directory`
+  // and `datastore` slices above.
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -813,12 +877,43 @@ const CONTRACT = deepFreeze({
   // 1.7.0: additive — new useDatastoreSchema(tableId) hook + the
   // datastore.schema host-context slice it reads (resolves a table's column
   // structure at runtime via the existing ACL-gated GET /tables/:id).
-  version: "1.7.0",
+  //
+  // 1.8.0: two additive features.
+  //  - REQ-WIDGET-ACTION — manifests may declare an optional `actions` array:
+  //    server-side cron/record-triggered scripts the operator enables per
+  //    tenant, run in the existing isolated-vm action runner (never in the
+  //    rendered app). New fields actionTriggerTypes / actionScriptGlobals /
+  //    actionScriptMaxBytes feed the docs + agent prompt. New ADMINISTRATION
+  //    manifest category (REQ-USERMGMT-06).
+  //  - REQ-ACL-06 — new useRecordPermissions(tableId, recordId) hook + the
+  //    recordPermissions host-context slice it reads + the acl.write:records
+  //    scope it gates on. Hits the existing REQ-ACL-06
+  //    /api/v1/tables/:tableId/records/:recordId/permissions REST surface;
+  //    the host normalises the wire shape into a single principalType+
+  //    principalId pair widgets branch on. Caller still needs canGrant on
+  //    the target record (REQ-ACL-RELINHERIT-05).
+  //
+  // 1.9.0: host-contract change (REQ-WSDK-DOMAIN-CLIENTS) — the host now
+  //    injects domain-client INSTANCES on the WidgetContext rather than
+  //    bespoke per-hook facades. ctx.datastore is a @colixsystems/datastore-client
+  //    (records(t).list now returns the { data, meta } envelope verbatim;
+  //    records(t).permissions(r) replaces the deleted ctx.recordPermissions),
+  //    ctx.directory is a @colixsystems/directory-client (users/groups
+  //    namespaces replace the deleted ctx.users / ctx.groups; list returns
+  //    envelopes), ctx.files is a flattened @colixsystems/files-client,
+  //    ctx.payments is a @colixsystems/payments-client. All rows/bodies are
+  //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
+  //    SDK stays duck-typed — it imports none of the four data SDKs. Minor
+  //    bump on the contract's pre-1.0 versioning (the breaking channel).
+  version: "1.9.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
   manifestCategories: CATEGORIES,
   manifestPlatforms: PLATFORMS,
+  actionTriggerTypes: ACTION_TRIGGER_TYPES,
+  actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
+  actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
   themeTokens: DEFAULT_THEME_TOKENS,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,