@colixsystems/widget-sdk 0.47.0 → 0.49.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 |
 | ----- | ---------------- | ------- | ------------- |
@@ -27,6 +27,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
+| **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
@@ -40,6 +41,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 +51,15 @@ 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.49.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.49.0
+
+**New `useGeolocation()` hook — read the device's current position (sc-1584).** A new CORE hook reading a newly-injected `ctx.device` slice (host-brokered device capabilities). Returns `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }`. Capture is **imperative** — call `getCurrentPosition()` from a user gesture (a `Pressable.onPress`); browsers and the mobile OS gate the permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to `{ latitude, longitude, accuracy }` and mirrors the same values onto the hook; `options` (`{ enableHighAccuracy, timeout, maximumAge }`) pass through to the host. Rejections surface as a structured `GeolocationError` (new named export) with a stable `.code` (`PERMISSION_DENIED` / `UNAVAILABLE` / `TIMEOUT` / `UNSUPPORTED` / `INTERNAL`). It needs **no manifest scope** and **no `requestedScopes` entry**. The web Player brokers it via `navigator.geolocation`; the Expo export via `expo-location` — so device access is identical on both platforms. The `ctx.device` slice is optional: a host that can't broker the sensor omits it and the hook degrades to an `UNSUPPORTED` error rather than throwing at render. `CONTRACT.version` → `1.36.0`. Additive — one new hook, one new optional context slice, one new error class; no existing export changed signature.
+
+### 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
 
@@ -364,6 +374,7 @@ The "split-implementation + vetted package list" pivot.
 ### What was in 0.4.1
 
 - **`useDatastoreQuery` returns a stable `refetch` identity.** The hook no longer rebinds the underlying callback when the host's `WidgetContext` value (a fresh object identity on every render in Studio + PageRenderer) changes. Widgets that put `refetch` in a `useEffect` dep array no longer loop.
+- **Keep the `useDatastoreQuery` argument stable across renders.** The hook re-fetches whenever `[table, JSON.stringify(query)]` changes, so a query whose serialized value differs every render refetches forever and the widget is stuck on its loading state. The classic trap is a time-relative filter built with `new Date()` / `Date.now()` inline in the query (a "this week" / "today" range) — the timestamp advances each render, so the key is never the same twice. Compute the date/time bound once with `useMemo(() => …, [])` (round to the day if you only need day granularity) and pass the stable value in. The same applies to any per-render value (a freshly built object, `Math.random()`): memoize it before it enters the query.
 
 ### What's new in 0.4.0
 
@@ -396,7 +407,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 /
@@ -621,6 +637,30 @@ const HOOKS = [
     requiredContextSlice: ["toast.showToast"],
     scopes: null,
   },
+  // sc-1584 — host-brokered device geolocation. Optional slice; the hook
+  // degrades to an UNSUPPORTED error rather than throwing at render.
+  {
+    name: "useGeolocation",
+    signature: "useGeolocation(options?)",
+    description:
+      "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
+      "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
+      "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
+      "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+    returnShape: {
+      latitude: "number | null",
+      longitude: "number | null",
+      accuracy: "number | null  // metres, best-effort",
+      loading: "boolean",
+      error: "GeolocationError | null",
+      getCurrentPosition:
+        "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1026,6 +1066,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
@@ -1060,6 +1107,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { showToast: "function" },
   },
+  // sc-1584 — host-brokered device capabilities. Optional: a host that can't
+  // broker a sensor omits the slice and useGeolocation() surfaces UNSUPPORTED.
+  // Both the web Player (navigator.geolocation) and the Expo export
+  // (expo-location) inject it, so device access is identical on both platforms.
+  device: {
+    description:
+      "Optional host-brokered device capabilities. " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
+      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+    required: false,
+    fields: { geolocation: "object" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -1744,7 +1804,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.36.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 /
@@ -621,6 +637,30 @@ const HOOKS = [
     requiredContextSlice: ["toast.showToast"],
     scopes: null,
   },
+  // sc-1584 — host-brokered device geolocation. Optional slice; the hook
+  // degrades to an UNSUPPORTED error rather than throwing at render.
+  {
+    name: "useGeolocation",
+    signature: "useGeolocation(options?)",
+    description:
+      "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
+      "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
+      "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
+      "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+    returnShape: {
+      latitude: "number | null",
+      longitude: "number | null",
+      accuracy: "number | null  // metres, best-effort",
+      loading: "boolean",
+      error: "GeolocationError | null",
+      getCurrentPosition:
+        "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1026,6 +1066,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
@@ -1060,6 +1107,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { showToast: "function" },
   },
+  // sc-1584 — host-brokered device capabilities. Optional: a host that can't
+  // broker a sensor omits the slice and useGeolocation() surfaces UNSUPPORTED.
+  // Both the web Player (navigator.geolocation) and the Expo export
+  // (expo-location) inject it, so device access is identical on both platforms.
+  device: {
+    description:
+      "Optional host-brokered device capabilities. " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
+      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+    required: false,
+    fields: { geolocation: "object" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -1744,7 +1804,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.36.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -336,6 +336,141 @@ export function useI18n() {
   return { t, locale };
 }
 
+/* ============================================================================
+ * DEVICE — ctx.device (host-brokered device capabilities)
+ *
+ * Sensor / hardware the host brokers for the widget — geolocation today. The
+ * host injects `ctx.device.<cap>` on BOTH platforms (web Player via
+ * navigator.geolocation; the Expo export via expo-location), so a widget reads
+ * the device identically on web and native (widget-parity skill). The slice is
+ * optional — a host that cannot broker a capability omits it and the hook
+ * surfaces an UNSUPPORTED error instead of throwing at render. Covers:
+ *   useGeolocation.
+ * ==========================================================================*/
+
+/**
+ * Error thrown by `useGeolocation().getCurrentPosition()` (and surfaced in the
+ * hook's `error` slot). Carries a stable `code` so widgets branch on the error
+ * class without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED" — the user (or OS) refused location access.
+ *   - "UNAVAILABLE"       — position could not be determined (no fix / sensor).
+ *   - "TIMEOUT"           — the request exceeded the host/option timeout.
+ *   - "UNSUPPORTED"       — this host does not broker geolocation.
+ *   - "INTERNAL"          — anything else.
+ */
+export class GeolocationError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "GeolocationError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/**
+ * Coerce a thrown value into a GeolocationError with a stable `.code`. Maps the
+ * browser PositionError numeric codes (1/2/3) and the host clients' string
+ * codes onto one vocabulary.
+ */
+function toGeolocationError(err) {
+  if (err instanceof GeolocationError) return err;
+  const raw = err && err.code !== undefined ? err.code : null;
+  let code = "INTERNAL";
+  if (raw === 1 || raw === "PERMISSION_DENIED") code = "PERMISSION_DENIED";
+  else if (raw === 2 || raw === "UNAVAILABLE" || raw === "POSITION_UNAVAILABLE")
+    code = "UNAVAILABLE";
+  else if (raw === 3 || raw === "TIMEOUT") code = "TIMEOUT";
+  else if (raw === "UNSUPPORTED") code = "UNSUPPORTED";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Geolocation request failed";
+  return new GeolocationError(code, message, { cause: err });
+}
+
+/**
+ * Read the device's current position. Returns
+ *   `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }`.
+ *
+ * Capture is IMPERATIVE — call `getCurrentPosition()` from a user gesture (a
+ * tap on a button). Browsers and the mobile OS gate the permission prompt on a
+ * user gesture, so the hook never fires on mount. The promise resolves to
+ * `{ latitude, longitude, accuracy }` and the same values are stored on the
+ * hook; it rejects with a `GeolocationError` carrying a stable `.code`.
+ *
+ * `options` pass through to the host (`{ enableHighAccuracy, timeout,
+ * maximumAge }`). The SAME hook drives both platforms: the web Player brokers
+ * it through `navigator.geolocation`, the Expo export through `expo-location`.
+ *
+ * Safe-by-default: on a host that does not inject `ctx.device.geolocation`,
+ * `getCurrentPosition()` rejects with `code: "UNSUPPORTED"` rather than
+ * throwing at render, so a widget can call the hook unconditionally.
+ */
+export function useGeolocation(options) {
+  const ctx = useWidgetContextOrThrow("useGeolocation");
+  const [coords, setCoords] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client +
+  // options in refs so getCurrentPosition is a stable callback.
+  const clientRef = useRef(ctx.device && ctx.device.geolocation);
+  clientRef.current = ctx.device && ctx.device.geolocation;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const runRef = useRef(0);
+
+  const getCurrentPosition = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const client = clientRef.current;
+    if (!client || typeof client.getCurrentPosition !== "function") {
+      const e = new GeolocationError(
+        "UNSUPPORTED",
+        "This host does not provide device geolocation.",
+      );
+      if (runRef.current === myRun) {
+        setError(e);
+        setLoading(false);
+      }
+      throw e;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const pos = await client.getCurrentPosition(optionsRef.current);
+      const next = {
+        latitude:
+          pos && typeof pos.latitude === "number" ? pos.latitude : null,
+        longitude:
+          pos && typeof pos.longitude === "number" ? pos.longitude : null,
+        accuracy:
+          pos && typeof pos.accuracy === "number" ? pos.accuracy : null,
+      };
+      if (runRef.current !== myRun) return next;
+      setCoords(next);
+      setLoading(false);
+      return next;
+    } catch (err) {
+      const ge = toGeolocationError(err);
+      if (runRef.current === myRun) {
+        setError(ge);
+        setLoading(false);
+      }
+      throw ge;
+    }
+  }, []);
+
+  return {
+    latitude: coords ? coords.latitude : null,
+    longitude: coords ? coords.longitude : null,
+    accuracy: coords ? coords.accuracy : null,
+    loading,
+    error,
+    getCurrentPosition,
+  };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *
@@ -2553,3 +2688,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 };
@@ -452,6 +464,16 @@ export interface WidgetContext<TProps = unknown> {
   toast?: {
     showToast(args: { kind?: string; message: string }): void;
   };
+  /** Optional host-brokered device capabilities; backs useGeolocation. */
+  device?: {
+    geolocation?: {
+      getCurrentPosition(options?: GeolocationOptions): Promise<{
+        latitude: number;
+        longitude: number;
+        accuracy: number;
+      }>;
+    };
+  };
 }
 
 /**
@@ -612,6 +634,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;
 
 /**
@@ -863,6 +931,60 @@ export function useRefresh(
   handler: () => void | Promise<unknown>,
 ): void;
 
+/** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
+export interface GeolocationOptions {
+  enableHighAccuracy?: boolean;
+  timeout?: number;
+  maximumAge?: number;
+}
+
+export interface GeolocationResult {
+  latitude: number | null;
+  longitude: number | null;
+  /** Best-effort accuracy in metres. */
+  accuracy: number | null;
+  loading: boolean;
+  error: GeolocationError | null;
+  /**
+   * Imperatively read the device position — call from a user gesture. Resolves
+   * to `{ latitude, longitude, accuracy }` and stores the same on the hook;
+   * rejects with a `GeolocationError`.
+   */
+  getCurrentPosition(): Promise<{
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+  }>;
+}
+
+/**
+ * sc-1584 — read the device's current position. Capture is imperative (call
+ * `getCurrentPosition()` from a user gesture; it never fires on mount). The
+ * same hook drives both platforms — the web Player brokers it via
+ * `navigator.geolocation`, the Expo export via `expo-location`. Safe to call on
+ * a host that doesn't broker geolocation: `getCurrentPosition()` then rejects
+ * with `code: "UNSUPPORTED"`.
+ */
+export function useGeolocation(options?: GeolocationOptions): GeolocationResult;
+
+/**
+ * sc-1584 — error thrown by `useGeolocation().getCurrentPosition()` and
+ * surfaced in the hook's `error` slot. `code` is a stable categorisation.
+ */
+export class GeolocationError extends Error {
+  code:
+    | "PERMISSION_DENIED"
+    | "UNAVAILABLE"
+    | "TIMEOUT"
+    | "UNSUPPORTED"
+    | "INTERNAL";
+  constructor(
+    code: GeolocationError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable
@@ -905,6 +1027,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,
@@ -40,6 +42,8 @@ export {
   useNavigation,
   useChildRenderer,
   useRefresh,
+  useGeolocation,
+  GeolocationError,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file

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,
@@ -38,6 +40,8 @@ export {
   useNavigation,
   useChildRenderer,
   useRefresh,
+  useGeolocation,
+  GeolocationError,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
   },
   "engines": {
     "node": ">=18"