@colixsystems/widget-sdk 0.18.0 → 0.19.0

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export type WidgetCategory =
   | "data"
   | "media"
   | "communication"
+  | "administration"
   | "custom";
 
 export type WidgetScope = string; // e.g. "datastore.read:orders"
@@ -126,6 +127,36 @@ export interface WidgetDatastoreTemplate {
   tables: WidgetDatastoreTemplateTable[];
 }
 
+/**
+ * REQ-WIDGET-ACTION: a server-side action the widget declares. Each runs in
+ * the shared isolated-vm action runner (cron- or record-triggered) — never in
+ * the rendered app, so it has no effect on Player ↔ export parity. Operators
+ * enable it per tenant from the Properties Panel; it materialises DISABLED
+ * until they bind an integration API key (and, for `record_*` triggers, a
+ * target table) in the Actions admin page. `triggerTableId` / `apiKeyId` are
+ * deliberately absent — those are tenant-local and bound after install.
+ */
+export interface WidgetManifestAction {
+  /** Stable, unique within the manifest — the idempotency key for materialise. */
+  key: string;
+  name: string;
+  description?: string;
+  triggerType:
+    | "schedule"
+    | "record_created"
+    | "record_updated"
+    | "record_deleted";
+  /** Required iff `triggerType === "schedule"`. node-cron syntax. */
+  scheduleCron?: string;
+  /** 100–300000. Defaults to 30000 on materialise. */
+  timeoutMs?: number;
+  /**
+   * Runs against `datastore`, `fetch`, `console`, `record`, `tenantId`,
+   * `triggerType`, `triggerTableId` — NOT the React/SDK surface. ≤ 200 KiB.
+   */
+  scriptSource: string;
+}
+
 export interface WidgetManifest {
   id: string;
   name: string;
@@ -147,6 +178,12 @@ export interface WidgetManifest {
    * structural constraints enforced at submission time.
    */
   datastoreTemplate?: WidgetDatastoreTemplate;
+  /**
+   * Optional server-side actions (REQ-WIDGET-ACTION). Operators enable them
+   * per tenant from the Properties Panel; each runs in the existing
+   * isolated-vm action runner. See `WidgetManifestAction`.
+   */
+  actions?: WidgetManifestAction[];
 }
 
 export interface ThemeTokens {
@@ -168,47 +205,162 @@ export interface ThemeTokens {
   };
 }
 
+// ----------------------------------------------------- injected data clients
+//
+// REQ-WSDK-DOMAIN-CLIENTS. @colixsystems/widget-sdk is CORE ONLY — manifest
+// contract, primitives, rendering, hooks, events, theme/i18n. It owns NO HTTP
+// and depends on NONE of the data SDK packages. The data layer is FOUR domain
+// client packages, each instantiated by the host and injected into
+// WidgetContext. **Widgets never import these packages** — they reach the data
+// surface only through the SDK hooks, which read the injected instances. The
+// shapes below are declared STRUCTURALLY here (widget-sdk must not import the
+// data SDKs); the authoritative typings ship with each client package.
+//
+// Wire/casing: snake_case end to end. The clients send/return snake_case
+// VERBATIM (e.g. `created_at`, `group_ids`, `can_read`, `amount_cents`,
+// `data_type`, `is_active`). There is NO client-side case transform anywhere.
+// Author-defined record column values are passed through verbatim. List
+// methods return the `{ data, meta }` envelope.
+
+/** A `{ data, meta }` list envelope, returned verbatim by every `list(...)`. */
+export interface ListEnvelope<T = unknown> {
+  data: T[];
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Structural shape of the injected `@colixsystems/datastore-client`
+ * (`ctx.datastore`). Backs `useDatastoreQuery` / `useDatastoreRecord` /
+ * `useDatastoreSchema` / `useDatastoreMutation` / `useRecordPermissions`.
+ * Rows and bodies are snake_case verbatim; `list` returns `{ data, meta }`.
+ */
+export interface DatastoreClient {
+  tables: {
+    list(): Promise<ListEnvelope>;
+    get(tableIdOrName: string): Promise<unknown>;
+  };
+  schema(tableId: string): Promise<unknown>;
+  records(tableId: string): {
+    list(query?: Query): Promise<ListEnvelope>;
+    get(recordId: string): Promise<unknown>;
+    create(values: Record<string, unknown>): Promise<unknown>;
+    /** PATCH semantics — only the supplied columns are mutated. */
+    update(recordId: string, values: Record<string, unknown>): Promise<unknown>;
+    delete(recordId: string): Promise<void>;
+    aggregate(spec: unknown): Promise<unknown>;
+    permissions(recordId: string): {
+      list(): Promise<ListEnvelope>;
+      grant(body: Record<string, unknown>): Promise<unknown>;
+      update(
+        permissionId: string,
+        patch: Record<string, unknown>,
+      ): Promise<unknown>;
+      revoke(permissionId: string): Promise<void>;
+    };
+  };
+}
+
+/**
+ * Structural shape of the injected `@colixsystems/directory-client`
+ * (`ctx.directory`). Backs `useDirectory` / `useUsers` (via `.users`) and
+ * `useGroups` (via `.groups`). Rows and bodies are snake_case verbatim;
+ * `list` returns `{ data, meta }`.
+ */
+export interface DirectoryClient {
+  me(): Promise<unknown>;
+  users: {
+    list(query?: DirectoryQuery): Promise<ListEnvelope>;
+    get(userId: string): Promise<unknown>;
+    invite(body: Record<string, unknown>): Promise<unknown>;
+    deactivate(userId: string): Promise<unknown>;
+    reactivate(userId: string): Promise<unknown>;
+  };
+  groups: {
+    list(query?: GroupsQuery): Promise<ListEnvelope>;
+    create(body: Record<string, unknown>): Promise<unknown>;
+    remove(groupId: string): Promise<void>;
+    addMember(groupId: string, userId: string): Promise<void>;
+    removeMember(groupId: string, userId: string): Promise<void>;
+    listMine(): Promise<ListEnvelope>;
+  };
+  invites: {
+    list(): Promise<ListEnvelope>;
+    revoke(inviteId: string): Promise<void>;
+    resend(inviteId: string): Promise<unknown>;
+  };
+}
+
+/**
+ * Structural shape of the injected Asset-Manager files client (`ctx.files`).
+ * Slimmed to the three top-level ops the host injects — `get` / `list` /
+ * `upload`. Backs `useFile`, which calls `ctx.files.get(id)`. The returned
+ * file carries an absolute `url` safe to drop into `<Image source>`.
+ */
+export interface FilesClient {
+  get(fileId: string): Promise<unknown>;
+  list(query?: Record<string, unknown>): Promise<ListEnvelope>;
+  upload(formData: unknown): Promise<unknown>;
+}
+
+/**
+ * Structural shape of the injected `@colixsystems/payments-client`
+ * (`ctx.payments`, REQ-BILL-07-WIDGETPAY). Backs `usePayments`.
+ */
+export interface PaymentsClient {
+  requestPayment(body: PaymentRequest): Promise<PaymentResult>;
+  getPayment(paymentId: string): Promise<PaymentResult>;
+}
+
 export interface WidgetContext<TProps = unknown> {
   props: TProps;
   widget: { id: string; instanceId: string; version: string };
+  /** Active end-user identity, snake_case verbatim. `id` is null when anonymous. */
   user: {
     id: string | null;
     email: string | null;
-    displayName: string | null;
+    display_name: string | null;
     roles: string[];
-    groupIds: string[];
+    group_ids: string[];
   };
   workspace: {
     id: string;
-    name: string;
+    slug: string;
     locale: string;
     theme: ThemeTokens;
   };
   navigation: {
     goTo(pageId: string, params?: Record<string, string>): void;
     goBack(): void;
+    push(pageId: string, params?: Record<string, unknown>): void;
+    replace(pageId: string, params?: Record<string, unknown>): void;
+    back(): void;
     currentRoute: { pageId: string; params: Record<string, string> };
   };
-  datastore: unknown; // typed by @colixsystems/datastore-client
-  directory: {
-    listUsers(query?: DirectoryQuery): Promise<DirectoryUser[]>;
-  };
+  /** Injected @colixsystems/datastore-client. */
+  datastore: DatastoreClient;
+  /** Injected @colixsystems/directory-client (users + groups + invites). */
+  directory: DirectoryClient;
+  /** Injected Asset-Manager files client: { get, list, upload }. */
+  files: FilesClient;
+  /** Injected @colixsystems/payments-client. */
+  payments: PaymentsClient;
+  /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
+  renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
-  payments: {
-    requestPayment(args: PaymentRequest): Promise<PaymentResult>;
-    getPayment(paymentId: string): Promise<PaymentResult>;
-  };
   i18n: {
     locale: string;
-    t(key: string, vars?: Record<string, unknown>): string;
+    t(key: string, fallback?: string): string;
   };
-  platform: "web" | "native";
   logger: {
     debug: (...args: unknown[]) => void;
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
   };
+  /** Optional host toast slot; backs useToast. */
+  toast?: {
+    showToast(args: { kind?: string; message: string }): void;
+  };
 }
 
 /**
@@ -303,8 +455,8 @@ export interface DirectoryQuery {
   q?: string;
   /** `"USER"` (default), `"INTEGRATION"`, or `"ALL"`. */
   role?: "USER" | "INTEGRATION" | "ALL";
-  /** Filter by active state. */
-  isActive?: boolean;
+  /** Filter by active state (snake_case on the wire). */
+  is_active?: boolean;
   limit?: number;
   offset?: number;
 }
@@ -317,7 +469,9 @@ export interface DirectoryResult {
 }
 
 /**
- * Read-only user directory hook. Resolves the tenant's app users to
+ * Read-only user directory hook. Reads the injected directory-client at
+ * `ctx.directory.users.list(query)` (returns the `{ data, meta }` envelope;
+ * the hook unwraps `res.data`). Resolves the tenant's app users to snake_case
  * `{ id, name, role }` rows for chat people-lists, @-mention pickers, or
  * author-id → display-name resolution. Requires the
  * `directory.read:users` scope in the widget manifest.
@@ -387,10 +541,11 @@ export function useDatastoreRecord(
  * One column in a table's schema, as returned by `useDatastoreSchema`.
  * Structural metadata only — never row data.
  */
+// Returned by `ctx.datastore.schema(tableId)` — wire data, snake_case verbatim.
 export interface DatastoreSchemaColumn {
   id: string;
   name: string;
-  dataType:
+  data_type:
     | "STRING"
     | "TEXT"
     | "NUMBER"
@@ -405,11 +560,11 @@ export interface DatastoreSchemaColumn {
     | "USER_GROUP";
   required: boolean;
   /** For RELATION columns only. */
-  relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY" | null;
+  relation_type?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY" | null;
   /** For RELATION columns only — the id of the table this column points at. */
-  targetTableId?: string | null;
+  target_table_id?: string | null;
   /** True when this column is the table's display/identification column. */
-  isIdentification?: boolean;
+  is_identification?: boolean;
 }
 
 export interface DatastoreSchema {
@@ -462,9 +617,9 @@ export function useFile(fileId: string | null | undefined): {
   file: {
     id: string;
     url: string;
-    storedFilename?: string;
-    mimeType?: string;
-    sizeBytes?: number;
+    stored_filename?: string;
+    mime_type?: string;
+    size_bytes?: number;
     [k: string]: unknown;
   } | null;
   loading: boolean;
@@ -485,9 +640,9 @@ export function useI18n(): {
 export function useUser(): {
   id: string | null;
   email: string | null;
-  displayName: string | null;
+  display_name: string | null;
   roles: string[];
-  groupIds: string[];
+  group_ids: string[];
 };
 
 /**
@@ -567,13 +722,13 @@ export interface AppUserRow {
   name: string;
   email?: string;
   role: "USER" | "INTEGRATION";
-  isActive: boolean;
+  is_active: boolean;
 }
 
 export interface UsersQuery {
   q?: string;
   role?: "USER" | "INTEGRATION" | "ALL";
-  isActive?: boolean;
+  is_active?: boolean;
   limit?: number;
   offset?: number;
 }
@@ -581,15 +736,15 @@ export interface UsersQuery {
 export interface InviteArgs {
   email: string;
   name?: string;
-  groupIds?: string[];
+  group_ids?: string[];
 }
 
 export interface AppUserInviteRow {
   id: string;
   email: string;
   status: string;
-  invitedAt?: string;
-  expiresAt?: string;
+  invited_at?: string;
+  expires_at?: string;
 }
 
 export interface UsersApi {
@@ -604,10 +759,12 @@ export interface UsersApi {
 }
 
 /**
- * AppUser administration. Reads require the `users.read:*` scope in the
- * manifest; mutations additionally require `users.write:*`. Widgets that
- * declare the scopes but whose calling APP_USER lacks the corresponding
- * SystemAcl `users.*` capability grant get a `FORBIDDEN` DirectoryError.
+ * AppUser administration. Reads through the injected directory-client at
+ * `ctx.directory.users.{list,get,invite,deactivate,reactivate}`. Reads
+ * require the `users.read:*` scope in the manifest; mutations additionally
+ * require `users.write:*`. Widgets that declare the scopes but whose calling
+ * APP_USER lacks the corresponding SystemAcl `users.*` capability grant get a
+ * `FORBIDDEN` DirectoryError.
  */
 export function useUsers(query?: UsersQuery): UsersApi;
 
@@ -616,7 +773,7 @@ export function useUsers(query?: UsersQuery): UsersApi;
 export interface AppUserGroupRow {
   id: string;
   name: string;
-  memberCount?: number;
+  member_count?: number;
 }
 
 export interface GroupsQuery {
@@ -637,47 +794,50 @@ export interface GroupsApi {
 }
 
 /**
- * AppUserGroup administration. Reads require `groups.read:*`; mutations
- * require `groups.write:*`. Same SystemAcl gating as `useUsers`.
+ * AppUserGroup administration. Reads through the injected directory-client at
+ * `ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}`.
+ * Reads require `groups.read:*`; mutations require `groups.write:*`. Same
+ * SystemAcl gating as `useUsers`.
  */
 export function useGroups(query?: GroupsQuery): GroupsApi;
 
 // ----------------------------------------------------- useRecordPermissions
 //
 // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
-// management for a single record. Reuses the existing
-// `/api/v1/tables/:tableId/records/:recordId/permissions` REST surface;
-// the host normalises the wire shape (`userId` / `groupId` /
-// both-null = public) into the `{ principalType, principalId }` pair
-// returned to widgets so the call site is portable.
+// management for a single record. Reads the injected datastore-client at
+// `ctx.datastore.records(tableId).permissions(recordId)`. Rows and bodies are
+// snake_case VERBATIM — the SDK does NOT transform them. A row carries
+// `user_id` OR `group_id` (both null = a public grant) plus the `can_*` flags.
 
 export interface RecordPermission {
   id: string;
-  principalType: "USER" | "GROUP" | "PUBLIC";
-  /** `null` when `principalType === "PUBLIC"`. */
-  principalId: string | null;
-  canRead: boolean;
-  canWrite: boolean;
-  canDelete: boolean;
-  canGrant: boolean;
+  /** Set when the grant targets a user; null otherwise. */
+  user_id: string | null;
+  /** Set when the grant targets a group; null otherwise. Both null = public. */
+  group_id: string | null;
+  can_read: boolean;
+  can_write: boolean;
+  can_delete: boolean;
+  can_grant: boolean;
+  [k: string]: unknown;
 }
 
 export interface RecordPermissionGrantInput {
-  /** Either a concrete principal (`USER` / `GROUP`) or `"PUBLIC"`. */
-  principalType: "USER" | "GROUP" | "PUBLIC";
-  /** Required when `principalType !== "PUBLIC"`. */
-  principalId?: string | null;
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  /** Target a user (omit / null `group_id`). */
+  user_id?: string | null;
+  /** Target a group (omit / null `user_id`). Both omitted = a public grant. */
+  group_id?: string | null;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
 export interface RecordPermissionUpdateInput {
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
 export interface RecordPermissionsResult {
@@ -720,10 +880,13 @@ export class PermissionError extends Error {
 
 /**
  * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
- * management. Requires `acl.write:records` in the manifest's
- * `requestedScopes`. The backend gates the call on `canGrant` for the
- * target record; a widget that declares the scope but whose caller
- * lacks the grant receives `PermissionError { code: "FORBIDDEN" }`.
+ * management. Reads the injected datastore-client at
+ * `ctx.datastore.records(tableId).permissions(recordId).{list,grant,update,revoke}`.
+ * Requires `acl.write:records` in the manifest's `requestedScopes`. The
+ * backend gates the call on `can_grant` for the target record; a widget that
+ * declares the scope but whose caller lacks the grant receives
+ * `PermissionError { code: "FORBIDDEN" }`. Rows and bodies are snake_case
+ * verbatim.
  *
  * When `tableId` OR `recordId` is null / empty, the hook collapses to a
  * stable empty result without a network round-trip; mutation methods

package/dist/linter.cjs

@@ -287,6 +287,61 @@ function _scopeRules(source, manifest) {
   return findings;
 }
 
+// REQ-WIDGET-ACTION — validate manifest-declared server actions. These run in
+// the isolated-vm action runner, NOT in the rendered component, so they are
+// validated structurally here (shape + caps) rather than scanned as component
+// source. Mirrors the validator in manifest.cjs; emits `error` findings so a
+// malformed / oversized / mis-triggered action blocks publish.
+function _manifestActionRules(manifest) {
+  const findings = [];
+  if (!manifest || manifest.actions === undefined) return findings;
+  const validTriggers = new Set(CONTRACT.actionTriggerTypes);
+  const maxBytes = CONTRACT.actionScriptMaxBytes;
+  const push = (label) =>
+    findings.push({ rule: "manifest-action", severity: "error", label, line: 0, snippet: "" });
+  if (!Array.isArray(manifest.actions)) {
+    push("manifest.actions must be an array (omit it or use [] for none)");
+    return findings;
+  }
+  const seenKeys = new Set();
+  for (const a of manifest.actions) {
+    if (a === null || typeof a !== "object") {
+      push("manifest.actions entries must be objects");
+      break;
+    }
+    if (typeof a.key !== "string" || a.key.length === 0) {
+      push("manifest.actions[].key must be a non-empty string");
+    } else if (seenKeys.has(a.key)) {
+      push(`manifest.actions[].key "${a.key}" is duplicated`);
+    } else {
+      seenKeys.add(a.key);
+    }
+    if (typeof a.name !== "string" || a.name.length === 0) {
+      push("manifest.actions[].name must be a non-empty string");
+    }
+    if (!validTriggers.has(a.triggerType)) {
+      push(`manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`);
+    } else if (a.triggerType === "schedule" && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
+      push("manifest.actions[].scheduleCron is required when triggerType is 'schedule'");
+    }
+    if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
+      push("manifest.actions[].scriptSource must be a non-empty string");
+    } else if (new TextEncoder().encode(a.scriptSource).length > maxBytes) {
+      push("manifest.actions[].scriptSource exceeds 200 KiB");
+    }
+    if (a.timeoutMs !== undefined) {
+      const t = Number(a.timeoutMs);
+      if (!Number.isFinite(t) || t < 100 || t > 300000) {
+        push("manifest.actions[].timeoutMs must be between 100 and 300000");
+      }
+    }
+    if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
+      push("manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install");
+    }
+  }
+  return findings;
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -331,6 +386,7 @@ function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  findings.push(..._manifestActionRules(options && options.manifest));
   const hasErrors = findings.some((f) => f.severity !== "warning");
   return { ok: !hasErrors, findings };
 }

package/dist/linter.js

@@ -361,6 +361,61 @@ function _scopeRules(source, manifest) {
  * @param {{ manifest?: { requestedScopes?: string[], supportedPlatforms?: string[] } }} [options]
  * @returns {{ ok: boolean, findings: Array<{ rule: string, severity?: "error" | "warning", label: string, line: number, snippet: string }> }}
  */
+// REQ-WIDGET-ACTION — validate manifest-declared server actions. These run in
+// the isolated-vm action runner, NOT in the rendered component, so they are
+// validated structurally here (shape + caps) rather than scanned as component
+// source. Mirrors the validator in manifest.js; emits `error` findings so a
+// malformed / oversized / mis-triggered action blocks publish.
+function _manifestActionRules(manifest) {
+  const findings = [];
+  if (!manifest || manifest.actions === undefined) return findings;
+  const validTriggers = new Set(CONTRACT.actionTriggerTypes);
+  const maxBytes = CONTRACT.actionScriptMaxBytes;
+  const push = (label) =>
+    findings.push({ rule: "manifest-action", severity: "error", label, line: 0, snippet: "" });
+  if (!Array.isArray(manifest.actions)) {
+    push("manifest.actions must be an array (omit it or use [] for none)");
+    return findings;
+  }
+  const seenKeys = new Set();
+  for (const a of manifest.actions) {
+    if (a === null || typeof a !== "object") {
+      push("manifest.actions entries must be objects");
+      break;
+    }
+    if (typeof a.key !== "string" || a.key.length === 0) {
+      push("manifest.actions[].key must be a non-empty string");
+    } else if (seenKeys.has(a.key)) {
+      push(`manifest.actions[].key "${a.key}" is duplicated`);
+    } else {
+      seenKeys.add(a.key);
+    }
+    if (typeof a.name !== "string" || a.name.length === 0) {
+      push("manifest.actions[].name must be a non-empty string");
+    }
+    if (!validTriggers.has(a.triggerType)) {
+      push(`manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`);
+    } else if (a.triggerType === "schedule" && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
+      push("manifest.actions[].scheduleCron is required when triggerType is 'schedule'");
+    }
+    if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
+      push("manifest.actions[].scriptSource must be a non-empty string");
+    } else if (new TextEncoder().encode(a.scriptSource).length > maxBytes) {
+      push("manifest.actions[].scriptSource exceeds 200 KiB");
+    }
+    if (a.timeoutMs !== undefined) {
+      const t = Number(a.timeoutMs);
+      if (!Number.isFinite(t) || t < 100 || t > 300000) {
+        push("manifest.actions[].timeoutMs must be between 100 and 300000");
+      }
+    }
+    if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
+      push("manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install");
+    }
+  }
+  return findings;
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -410,6 +465,8 @@ export function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  // REQ-WIDGET-ACTION — structural validation of manifest-declared actions.
+  findings.push(..._manifestActionRules(options && options.manifest));
   const hasErrors = findings.some((f) => f.severity !== "warning");
   return { ok: !hasErrors, findings };
 }