@colixsystems/widget-sdk 0.47.0 → 0.48.0

package/README.md

@@ -13,7 +13,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
-**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (19 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
+**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (20 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
@@ -40,6 +40,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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) |
 | **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`. |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
 
@@ -49,7 +50,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.47.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.48.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.48.0
+
+**New `useSendNotification()` hook — send an in-app notification to an app user (sc-890).** A new NOTIFICATIONS hook reading a newly-injected `ctx.notifications` slice (the `@colixsystems/notifications-client`, now constructed by both the web Player and the native Expo export). Returns `{ send, sending, error }`. `send({ recipient_user_id, title, body, link?, payload? })` posts a notification to one app user **in the same workspace** and resolves to the created row; `recipient_user_id` must be a member of the tenant or the call is rejected (cross-workspace targets never resolve). Call it from an **event handler** (a `Pressable.onPress`, a submit, a mutation callback) — never in render, where the abuse/rate-limit guard would fire on every paint. Gated by the new `notifications.send:appUser` scope, which the widget declares in its manifest `requestedScopes`. Rejections surface as a structured `NotificationError` (new named export) with a stable `.code` (`INVALID_TITLE` / `INVALID_BODY` / `INVALID_RECIPIENT` / `INVALID_PAYLOAD` / `VALIDATION` / `AUTH_REQUIRED` / `FORBIDDEN` / `RECIPIENT_NOT_FOUND` / `RATE_LIMITED` / `INTERNAL`). `CONTRACT.version` → `1.35.0`. Additive — one new hook, one new context slice, one new scope, one new error class; no existing export changed signature.
 
 ### What's new in 0.47.0
 
@@ -396,7 +401,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`, `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`. `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, 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).
 - `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

@@ -420,6 +420,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-890 — send an in-app notification to one app user in the tenant.
+  // IMPERATIVE: send() never fires on mount; the widget calls it from an
+  // event handler. Reads ctx.notifications.send (the injected
+  // @colixsystems/notifications-client). Requires the
+  // notifications.send:appUser scope.
+  {
+    name: "useSendNotification",
+    signature: "useSendNotification()",
+    returnShape: {
+      send: "({ recipient_user_id, title, body, link?, payload? }) => Promise<notification>  // rejects with NotificationError",
+      sending: "boolean",
+      error: "NotificationError | null",
+    },
+    requiredContextSlice: ["notifications.send"],
+    scopes: ["notifications.send:appUser"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
@@ -1026,6 +1042,13 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // sc-890 — backs useSendNotification(). Mirror of contract.js.
+  notifications: {
+    description:
+      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification> }. Backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount).",
+    required: true,
+    fields: { send: "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
@@ -1744,7 +1767,18 @@ const CONTRACT = deepFreeze({
   //    type }` shape the native picker returns, so the same hook code path
   //    feeds the multipart in both hosts. No existing hook, primitive, or
   //    manifest field changed shape — minor bump.
-  version: "1.34.0",
+  //
+  // 1.35.0: additive (sc-890) — new `useSendNotification()` hook reading the
+  //    newly-injected `ctx.notifications` (@colixsystems/notifications-client).
+  //    Returns `{ send, sending, error }`; `send({ recipient_user_id, title,
+  //    body, link?, payload? })` POSTs to `/notifications/send` and resolves to
+  //    the created notification row, rejecting with a structured
+  //    NotificationError. Imperative — never fires on mount. New required field
+  //    on the new `notifications` context slice (`send: "function"`) + the new
+  //    `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.35.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -420,6 +420,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-890 — send an in-app notification to one app user in the tenant.
+  // IMPERATIVE: send() never fires on mount; the widget calls it from an
+  // event handler. Reads ctx.notifications.send (the injected
+  // @colixsystems/notifications-client). Requires the
+  // notifications.send:appUser scope.
+  {
+    name: "useSendNotification",
+    signature: "useSendNotification()",
+    returnShape: {
+      send: "({ recipient_user_id, title, body, link?, payload? }) => Promise<notification>  // rejects with NotificationError",
+      sending: "boolean",
+      error: "NotificationError | null",
+    },
+    requiredContextSlice: ["notifications.send"],
+    scopes: ["notifications.send:appUser"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
@@ -1026,6 +1042,13 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // sc-890 — backs useSendNotification(). Mirror of contract.cjs.
+  notifications: {
+    description:
+      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification> }. Backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount).",
+    required: true,
+    fields: { send: "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
@@ -1744,7 +1767,18 @@ const CONTRACT = deepFreeze({
   //    type }` shape the native picker returns, so the same hook code path
   //    feeds the multipart in both hosts. No existing hook, primitive, or
   //    manifest field changed shape — minor bump.
-  version: "1.34.0",
+  //
+  // 1.35.0: additive (sc-890) — new `useSendNotification()` hook reading the
+  //    newly-injected `ctx.notifications` (@colixsystems/notifications-client).
+  //    Returns `{ send, sending, error }`; `send({ recipient_user_id, title,
+  //    body, link?, payload? })` POSTs to `/notifications/send` and resolves to
+  //    the created notification row, rejecting with a structured
+  //    NotificationError. Imperative — never fires on mount. New required field
+  //    on the new `notifications` context slice (`send: "function"`) + the new
+  //    `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.35.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2553,3 +2553,124 @@ export function usePayments() {
   }, []);
   return { requestPayment, getPayment };
 }
+
+/* ============================================================================
+ * NOTIFICATIONS CLIENT — ctx.notifications (@colixsystems/notifications-client)
+ *
+ * send. Covers: useSendNotification.
+ * ==========================================================================*/
+
+/**
+ * sc-890 — structured error thrown by `useSendNotification().send`. Carries a
+ * stable `code` so widgets can branch without parsing message strings; mirrors
+ * the shape of `PaymentError` / `DirectoryError`.
+ *
+ * `code` is one of:
+ *   - "INVALID_TITLE" / "INVALID_BODY" / "INVALID_RECIPIENT" /
+ *     "INVALID_PAYLOAD" / "VALIDATION" — 400 (bad request)
+ *   - "AUTH_REQUIRED"        — 401 (no signed-in app user)
+ *   - "FORBIDDEN"            — 403 (widget lacks notifications.send:appUser)
+ *   - "RECIPIENT_NOT_FOUND"  — 404 (recipient not a member of the tenant)
+ *   - "RATE_LIMITED"         — 429 (too many sends)
+ *   - "INTERNAL"             — anything else (network, 5xx)
+ *
+ * The server's stable `code` (when volunteered in the error body) is preserved
+ * over the status-derived one.
+ */
+export class NotificationError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "NotificationError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toNotificationError(err) {
+  if (err instanceof NotificationError) return err;
+  // The injected notifications-client rejects with its own NotificationError
+  // subclass carrying { code, status }; the host facade may instead throw an
+  // axios-shaped error ({ response: { status, data: { code, error } } }). Read
+  // both shapes so the hook surfaces a stable code either way.
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : err && typeof err.status === "number"
+        ? err.status
+        : null;
+  const bodyCode =
+    (err && err.response && err.response.data && err.response.data.code) ||
+    (err && typeof err.code === "string" ? err.code : null);
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "RECIPIENT_NOT_FOUND";
+  else if (status === 429) code = "RATE_LIMITED";
+  else if (status === 400) code = "VALIDATION";
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Send notification failed");
+  return new NotificationError(code, message, { cause: err });
+}
+
+/**
+ * sc-890 — send an in-app notification to one app user in the tenant. Returns
+ * `{ send, sending, error }`.
+ *
+ *   send({ recipient_user_id, title, body, link?, payload? })
+ *     → Promise<notification>. Body is snake_case VERBATIM (the wire contract,
+ *       REQ-GEN-09) — the SDK does NOT transform it. Resolves to the created
+ *       notification row (`{ id, tenant_id, user_id, title, body, link,
+ *       payload, read_at, created_at }`) and rejects with a `NotificationError`.
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls `send`
+ * from an event handler (a button press, a form submit). `sending` tracks an
+ * in-flight call and `error` holds the last `NotificationError` (cleared at the
+ * start of each `send`). Reads the injected
+ * `@colixsystems/notifications-client` at `ctx.notifications`.
+ *
+ * Requires the `notifications.send:appUser` scope in the manifest's
+ * `requestedScopes`. A widget that declares the scope but whose caller is not
+ * permitted receives a `NotificationError { code: "FORBIDDEN" }`.
+ */
+export function useSendNotification() {
+  const ctx = useWidgetContextOrThrow("useSendNotification");
+  if (!ctx.notifications || typeof ctx.notifications.send !== "function") {
+    throw new Error(
+      "useSendNotification: host did not inject a notifications client. The " +
+        "widget must declare the notifications.send:appUser scope and be " +
+        "installed in a workspace whose host supports notifications.",
+    );
+  }
+  // `ctx` is a fresh identity each host render — hold the send fn in a ref so
+  // the callback stays stable.
+  const sendRef = useRef(ctx.notifications.send);
+  sendRef.current = ctx.notifications.send;
+
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState(null);
+
+  const send = useCallback(async (body) => {
+    setSending(true);
+    setError(null);
+    try {
+      // body is snake_case verbatim ({ recipient_user_id, title, body, link?,
+      // payload? }) — passed straight through.
+      const row = await sendRef.current(body);
+      setSending(false);
+      return row;
+    } catch (err) {
+      const e = toNotificationError(err);
+      setError(e);
+      setSending(false);
+      throw e;
+    }
+  }, []);
+
+  return { send, sending, error };
+}

package/dist/index.d.ts

@@ -395,6 +395,16 @@ export interface PaymentsClient {
   getPayment(paymentId: string): Promise<PaymentResult>;
 }
 
+/**
+ * Structural shape of the injected `@colixsystems/notifications-client`
+ * (`ctx.notifications`, sc-890). Backs `useSendNotification`. `send` POSTs the
+ * body snake_case verbatim to `/notifications/send` and resolves to the created
+ * notification row.
+ */
+export interface NotificationsClient {
+  send(body: SendNotificationRequest): Promise<NotificationRow>;
+}
+
 export interface WidgetContext<TProps = unknown> {
   props: TProps;
   widget: { id: string; instanceId: string; version: string };
@@ -435,6 +445,8 @@ export interface WidgetContext<TProps = unknown> {
   assets: AssetsClient;
   /** Injected @colixsystems/payments-client. */
   payments: PaymentsClient;
+  /** Injected @colixsystems/notifications-client; backs useSendNotification. */
+  notifications: NotificationsClient;
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
   renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
@@ -612,6 +624,52 @@ export interface PaymentsApi {
  */
 export function usePayments(): PaymentsApi;
 
+/**
+ * Arguments for `useSendNotification().send(...)`. snake_case VERBATIM — this
+ * is the wire contract (REQ-GEN-09). `recipient_user_id`, `title`, and `body`
+ * are required; `link` and `payload` are optional.
+ */
+export interface SendNotificationRequest {
+  recipient_user_id: string;
+  title: string;
+  body: string;
+  link?: string | null;
+  payload?: Record<string, unknown> | null;
+}
+
+/**
+ * A notification row, snake_case verbatim as returned by the backend
+ * (`POST /notifications/send`, 201). The shape is open-ended; the well-known
+ * fields are listed.
+ */
+export interface NotificationRow {
+  id: string;
+  tenant_id?: string;
+  user_id?: string;
+  title?: string;
+  body?: string;
+  link?: string | null;
+  payload?: Record<string, unknown> | null;
+  read_at?: string | null;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export interface SendNotificationApi {
+  send(body: SendNotificationRequest): Promise<NotificationRow>;
+  sending: boolean;
+  error: NotificationError | null;
+}
+
+/**
+ * sc-890 — send an in-app notification to one app user in the tenant. Returns
+ * `{ send, sending, error }`. The hook is imperative — `send` never fires on
+ * mount; the widget calls it from an event handler. Rejects with a
+ * `NotificationError`. Requires the `notifications.send:appUser` scope in the
+ * widget manifest.
+ */
+export function useSendNotification(): SendNotificationApi;
+
 export function useTheme(): ThemeTokens;
 
 /**
@@ -905,6 +963,30 @@ export class DirectoryError extends Error {
   );
 }
 
+/**
+ * sc-890 — error class thrown by `useSendNotification().send`. The `code` is a
+ * stable categorisation widgets can branch on.
+ */
+export class NotificationError extends Error {
+  code:
+    | "INVALID_TITLE"
+    | "INVALID_BODY"
+    | "INVALID_RECIPIENT"
+    | "INVALID_PAYLOAD"
+    | "VALIDATION"
+    | "AUTH_REQUIRED"
+    | "FORBIDDEN"
+    | "RECIPIENT_NOT_FOUND"
+    | "RATE_LIMITED"
+    | "INTERNAL"
+    | string;
+  constructor(
+    code: NotificationError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 // --------------------------------------------------------------- useUsers
 //
 // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.

package/dist/index.js

@@ -9,6 +9,7 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  NotificationError,
   DirectoryError,
   PermissionError,
   useDatastoreQuery,
@@ -32,6 +33,7 @@ export {
   useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
+  useSendNotification,
   useTheme,
   useWidgetStyle,
   useI18n,

package/dist/index.native.js

@@ -9,6 +9,7 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  NotificationError,
   DirectoryError,
   PermissionError,
   useDatastoreQuery,
@@ -30,6 +31,7 @@ export {
   useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
+  useSendNotification,
   useTheme,
   useWidgetStyle,
   useI18n,

package/package.json

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