@colixsystems/widget-sdk 0.204.0 → 0.205.1

package/README.md

@@ -83,7 +83,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.204.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.205.1` — 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.205.1
+
+**An encrypted column never labels a relation.** A RELATION read's `label` now comes from the first non-encrypted STRING/TEXT column on the target table when no display column is set, and an encrypted display column gives no label (`null`): a label is read whatever the reader may read of the target row, so it never carries encrypted text. To show an encrypted value of a related row, read that row through the table it lives in. A documentation correction; `CONTRACT.version` is unchanged.
+
+### What's new in 0.205.0 (contract 1.164.0)
+
+**An app's user totals for its own admins — `useUserStats({ days, group_id })`.** Active and deactivated users, new users per day (7 / 30 days) or week (90 days) with the previous period's total beside them, users in no group, empty groups, and invite figures. Totals only — never a list of people. Needs `users.read:*` and the viewer's admin user access (else `error.code === "FORBIDDEN"`); `stats.invites` is null unless the widget also declares `users.write:*` and the viewer holds it.
+
+**User activity — `useUserActivity({ days, group_id })` and `useInactiveUsers({ inactive_days, group_id, limit, offset })`.** For a workspace that records user activity: who is online now, active in the last day / week / month, never active, active users per day or week, the web / iOS / Android split and the active share per group — and a page of the users not seen recently, never-seen first. Needs `users.activity:*` and the viewer's "View user activity" permission (else `error.code === "FORBIDDEN"`); when the workspace does not record activity, `error.reason === "ACTIVITY_DISABLED"` — show that, not zeros. Before user activity is offered to the workspace at all, `error.reason` is `"ACTIVITY_UNAVAILABLE"`: hide the section, as for `FORBIDDEN`. `useInactiveUsers` also returns `remind(userId, { title, body })`, which notifies one of them and records when (each row carries `last_reminded_at`). Days follow the workspace's time zone (`period.time_zone`).
+
+**Linter fix.** A widget that uses `useGroups` or `useUsers` is no longer refused for a write it never makes: `StyleSheet.create(...)` and an event subscription's bare `remove()` (an `AppState` listener, say) are not user or group writes.
 
 ### What's new in 0.204.0 (contract 1.163.0)
 
@@ -2102,7 +2114,7 @@ useEffect(() => {
 
 ### What's new in 0.42.0
 
-**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table. Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList` and `DataValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
+**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table (since 0.205.1: the first non-encrypted one; an encrypted display column gives no label). Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList` and `DataValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
 
 ### What's new in 0.41.0
 

package/dist/contract.cjs

@@ -1975,6 +1975,95 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
+  // sc-10691 / REQ-USERMGMT-10 — an app's user totals for its own admins.
+  {
+    name: "useUserStats",
+    signature: "useUserStats({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "Workspace user TOTALS for an app's own administrators — never a list " +
+      "of people. `days` is 7 or 30 (charted per day) or 90 (per ISO week), in " +
+      "the workspace's time zone (`stats.period.time_zone`); " +
+      "`group_id` (a useGroups() row id) narrows the user and invite " +
+      "figures to that group. `stats.users` = { active, deactivated, " +
+      "without_group }; `stats.new_users` = { total, previous_total, buckets: " +
+      "[{ date, count }] } with every bucket present and previous_total the " +
+      "equal-length window before the period; `stats.groups` and " +
+      "`stats.empty_groups`; `stats.invites` = { " +
+      "pending, expiring_soon, expired, accepted }. `without_group`, `groups` " +
+      "and `empty_groups` are null on a group-scoped read. `invites` is null unless " +
+      "the widget also declares users.write:* AND the viewer holds users.write " +
+      "— render \"no access\" for that section rather than zeros. A viewer " +
+      "without the admin user view gets error.code FORBIDDEN; show an " +
+      "explicit no-access state.",
+    returnShape: {
+      stats:
+        "{ period, group_id, users, new_users, groups, empty_groups, invites } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN without the admin user view, NOT_FOUND for a foreign group",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.read:*"],
+  },
+  // sc-10691 / REQ-USERMGMT-12 — user activity, behind users.activity.
+  {
+    name: "useUserActivity",
+    signature: "useUserActivity({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "User ACTIVITY for an app's administrators, for a workspace that " +
+      "records it: `activity.online_now` (app open in the last two minutes), " +
+      "`activity.active` = { day (since midnight), week, month (last 7/30 " +
+      "days), period (distinct users active in the period) }, " +
+      "`activity.never_active`, " +
+      "`activity.daily_active` = [{ date, count }] distinct active users per " +
+      "day (7/30 days) or week (90) in the workspace's time zone, `activity.platforms` = { web, ios, " +
+      "android, unknown } users active in the period, `activity.by_group` = " +
+      "[{ group_id, name, users, active }] (null on a group-scoped read), " +
+      "`activity.users` and `activity.recording_since` (activity before it " +
+      "is unknown — say \"since <date>\" next to never-active figures). Needs " +
+      "users.activity:* AND the viewer's \"View user activity\" permission " +
+      "(else error.code FORBIDDEN). error.reason \"ACTIVITY_UNAVAILABLE\" means " +
+      "user activity is not offered to this workspace yet: hide the section, " +
+      "like FORBIDDEN. When the workspace does not record activity, " +
+      "error.reason is \"ACTIVITY_DISABLED\": show that state, not zeros. " +
+      "Pass null instead of a query to read nothing (a section switched off).",
+    returnShape: {
+      activity:
+        "{ period, group_id, recording_since, users, online_now, active, never_active, daily_active, platforms, by_group } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN; reason ACTIVITY_UNAVAILABLE (hide) or ACTIVITY_DISABLED (not recorded)",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
+  {
+    name: "useInactiveUsers",
+    signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
+    optionalArgs: ["inactive_days", "group_id", "limit", "offset"],
+    description:
+      "One page of users not seen for `inactive_days` (1-365, default 30), " +
+      "never-seen first, then least recently seen: `users` = [{ id, name, " +
+      "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
+      "since recording began), `total` for paging. `remind(id, { title, body })` " +
+      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "Same gate and errors as useUserActivity; null reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_reminded_at }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      remind: "(id, { title, body }) => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -5370,7 +5459,12 @@ const CONTRACT = deepFreeze({
   //    `Spinner` wears `colors.loader`; `Skeleton` reads the new `loading`
   //    component scope (colour, radius). A scope may now name `sdkComponents`
   //    and bind no widget field. Both stop under reduced motion.
-  version: "1.163.0",
+  // 1.164.0: additive (sc-10691) — `useUserStats(query)` reads an app's user
+  //    totals through the new `ctx.directory.users.stats`; `useUserActivity`
+  //    and `useInactiveUsers` read user activity through the new
+  //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
+  //    new `users.activity:*` scope.
+  version: "1.164.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1975,6 +1975,95 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
+  // sc-10691 / REQ-USERMGMT-10 — an app's user totals for its own admins.
+  {
+    name: "useUserStats",
+    signature: "useUserStats({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "Workspace user TOTALS for an app's own administrators — never a list " +
+      "of people. `days` is 7 or 30 (charted per day) or 90 (per ISO week), in " +
+      "the workspace's time zone (`stats.period.time_zone`); " +
+      "`group_id` (a useGroups() row id) narrows the user and invite " +
+      "figures to that group. `stats.users` = { active, deactivated, " +
+      "without_group }; `stats.new_users` = { total, previous_total, buckets: " +
+      "[{ date, count }] } with every bucket present and previous_total the " +
+      "equal-length window before the period; `stats.groups` and " +
+      "`stats.empty_groups`; `stats.invites` = { " +
+      "pending, expiring_soon, expired, accepted }. `without_group`, `groups` " +
+      "and `empty_groups` are null on a group-scoped read. `invites` is null unless " +
+      "the widget also declares users.write:* AND the viewer holds users.write " +
+      "— render \"no access\" for that section rather than zeros. A viewer " +
+      "without the admin user view gets error.code FORBIDDEN; show an " +
+      "explicit no-access state.",
+    returnShape: {
+      stats:
+        "{ period, group_id, users, new_users, groups, empty_groups, invites } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN without the admin user view, NOT_FOUND for a foreign group",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.read:*"],
+  },
+  // sc-10691 / REQ-USERMGMT-12 — user activity, behind users.activity.
+  {
+    name: "useUserActivity",
+    signature: "useUserActivity({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "User ACTIVITY for an app's administrators, for a workspace that " +
+      "records it: `activity.online_now` (app open in the last two minutes), " +
+      "`activity.active` = { day (since midnight), week, month (last 7/30 " +
+      "days), period (distinct users active in the period) }, " +
+      "`activity.never_active`, " +
+      "`activity.daily_active` = [{ date, count }] distinct active users per " +
+      "day (7/30 days) or week (90) in the workspace's time zone, `activity.platforms` = { web, ios, " +
+      "android, unknown } users active in the period, `activity.by_group` = " +
+      "[{ group_id, name, users, active }] (null on a group-scoped read), " +
+      "`activity.users` and `activity.recording_since` (activity before it " +
+      "is unknown — say \"since <date>\" next to never-active figures). Needs " +
+      "users.activity:* AND the viewer's \"View user activity\" permission " +
+      "(else error.code FORBIDDEN). error.reason \"ACTIVITY_UNAVAILABLE\" means " +
+      "user activity is not offered to this workspace yet: hide the section, " +
+      "like FORBIDDEN. When the workspace does not record activity, " +
+      "error.reason is \"ACTIVITY_DISABLED\": show that state, not zeros. " +
+      "Pass null instead of a query to read nothing (a section switched off).",
+    returnShape: {
+      activity:
+        "{ period, group_id, recording_since, users, online_now, active, never_active, daily_active, platforms, by_group } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN; reason ACTIVITY_UNAVAILABLE (hide) or ACTIVITY_DISABLED (not recorded)",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
+  {
+    name: "useInactiveUsers",
+    signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
+    optionalArgs: ["inactive_days", "group_id", "limit", "offset"],
+    description:
+      "One page of users not seen for `inactive_days` (1-365, default 30), " +
+      "never-seen first, then least recently seen: `users` = [{ id, name, " +
+      "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
+      "since recording began), `total` for paging. `remind(id, { title, body })` " +
+      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "Same gate and errors as useUserActivity; null reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_reminded_at }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      remind: "(id, { title, body }) => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -5366,7 +5455,12 @@ const CONTRACT = deepFreeze({
   //    `Spinner` wears `colors.loader`; `Skeleton` reads the new `loading`
   //    component scope (colour, radius). A scope may now name `sdkComponents`
   //    and bind no widget field. Both stop under reduced motion.
-  version: "1.163.0",
+  // 1.164.0: additive (sc-10691) — `useUserStats(query)` reads an app's user
+  //    totals through the new `ctx.directory.users.stats`; `useUserActivity`
+  //    and `useInactiveUsers` read user activity through the new
+  //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
+  //    new `users.activity:*` scope.
+  version: "1.164.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -5613,7 +5613,8 @@ export class DirectoryError extends Error {
   }
 }
 
-function toDirectoryError(err) {
+// Internal: shared with stats-hooks.js, not re-exported by the index.
+export function toDirectoryError(err) {
   // See the note in toDatastoreError: the directory CLIENT has a same-named
   // class, so a client rejection is read from the envelope below, not here.
   if (err instanceof DirectoryError) return err;

package/dist/index.d.ts

@@ -1037,6 +1037,87 @@ export function useDatastoreFigure(
   options?: FigureOptions,
 ): FigureResult;
 
+export interface UserStatsQuery {
+  days?: 7 | 30 | 90;
+  /** A `useGroups()` row id: narrows user and invite figures to that group. */
+  group_id?: string;
+}
+
+export interface UserStats {
+  /** Days follow the workspace's `time_zone` (IANA; "UTC" when unset). */
+  period: { days: 7 | 30 | 90; bucket: "day" | "week"; from: string; to: string; time_zone: string };
+  group_id: string | null;
+  users: { active: number; deactivated: number; without_group: number | null };
+  /** `previous_total`: the equal-length window just before the period. */
+  new_users: {
+    total: number;
+    previous_total: number;
+    buckets: Array<{ date: string; count: number }>;
+  };
+  /** The workspace's groups; null on a group-scoped read. */
+  groups: number | null;
+  empty_groups: number | null;
+  /** Null unless the viewer may list invites (`users.write`). */
+  invites: { pending: number; expiring_soon: number; expired: number; accepted: number } | null;
+}
+
+/** An app's user totals for its own admins — never a list of people. */
+export function useUserStats(query?: UserStatsQuery): {
+  stats: UserStats | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+export interface UserActivity {
+  /** Days follow the workspace's `time_zone` (IANA; "UTC" when unset). */
+  period: { days: 7 | 30 | 90; bucket: "day" | "week"; from: string; to: string; time_zone: string };
+  group_id: string | null;
+  /** When the workspace started recording. */
+  recording_since: string | null;
+  users: number;
+  /** Seen with the app open in the last two minutes. */
+  online_now: number;
+  /** `day`: since midnight; `week`/`month`: last 7/30 days; `period`: distinct over the period. */
+  active: { day: number; week: number; month: number; period: number };
+  never_active: number;
+  daily_active: Array<{ date: string; count: number }>;
+  platforms: { web: number; ios: number; android: number; unknown: number };
+  by_group: Array<{ group_id: string; name: string; users: number; active: number }> | null;
+}
+
+/**
+ * User activity for an app's admins. Needs `users.activity:*` and the
+ * viewer's "View user activity" permission; `error.reason` is
+ * "ACTIVITY_DISABLED" when the workspace does not record activity, and
+ * "ACTIVITY_UNAVAILABLE" (hide the section) before it is offered at all.
+ */
+export function useUserActivity(query?: { days?: 7 | 30 | 90; group_id?: string }): {
+  activity: UserActivity | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+/** Users not seen for `inactive_days` (default 30), never-seen first. */
+export function useInactiveUsers(query?: {
+  inactive_days?: number;
+  group_id?: string;
+  limit?: number;
+  offset?: number;
+} | null): {
+  users: Array<{ id: string; name: string; last_active_at: string | null; last_reminded_at: string | null }>;
+  total: number | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+  /** Notify one user, record when, then re-read the page. */
+  remind(id: string, message: { title: string; body: string }): Promise<void>;
+};
+
 export function useDatastoreMutation<T = unknown>(
   table: string,
 ): MutationApi<T>;
@@ -1335,8 +1416,9 @@ export interface DatastoreSchemaColumn {
   /**
    * For RELATION columns only — id of a column on `target_table_id` whose
    * value supplies the `label` hydrated next to the related record id in
-   * record responses. `null` falls back to the first STRING/TEXT column on
-   * the target table.
+   * record responses. `null` falls back to the first non-encrypted
+   * STRING/TEXT column on the target table; an encrypted display column
+   * gives no label (`null`).
    */
   display_column_id?: string | null;
   /** True when this column is the table's display/identification column. */

package/dist/index.js

@@ -124,6 +124,11 @@ export {
   AudioPlayerError,
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export {
+  useUserStats,
+  useUserActivity,
+  useInactiveUsers,
+} from "./stats-hooks.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box
 // identically on the Player and the Expo export.

package/dist/index.native.js

@@ -122,6 +122,11 @@ export {
   AudioPlayerError,
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export {
+  useUserStats,
+  useUserActivity,
+  useInactiveUsers,
+} from "./stats-hooks.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";
 // sc-8104 — see the note on the web mirror in ./index.js.

package/dist/linter.cjs

@@ -771,7 +771,8 @@ function _scopeRules(source, manifest) {
     // the edit-style write scope above.
     if (usesUsersHook && !firedUsersDelete) {
       for (const m of USER_DELETE_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // remove(userId) takes an id; an event subscription's remove() does not.
+        const re = new RegExp(`\\.${m}\\s*\\(\\s*[^)\\s]`);
         if (re.test(line)) {
           if (
             !declared.has("users.delete:*") &&
@@ -791,7 +792,10 @@ function _scopeRules(source, manifest) {
     }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // Not group writes: `StyleSheet.create(`, and a subscription's bare remove().
+        const lookbehind = m === "create" ? "(?<!StyleSheet)" : "";
+        const needsArgs = m === "remove" ? "\\s*[^)\\s]" : "";
+        const re = new RegExp(`${lookbehind}\\.${m}\\s*\\(${needsArgs}`);
         if (re.test(line)) {
           if (m === "remove" && usesUsersHook) continue;
           if (

package/dist/linter.js

@@ -723,7 +723,8 @@ function _scopeRules(source, manifest) {
     // the edit-style write scope above.
     if (usesUsersHook && !firedUsersDelete) {
       for (const m of USER_DELETE_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // remove(userId) takes an id; an event subscription's remove() does not.
+        const re = new RegExp(`\\.${m}\\s*\\(\\s*[^)\\s]`);
         if (re.test(line)) {
           if (
             !declared.has("users.delete:*") &&
@@ -743,7 +744,10 @@ function _scopeRules(source, manifest) {
     }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // Not group writes: `StyleSheet.create(`, and a subscription's bare remove().
+        const lookbehind = m === "create" ? "(?<!StyleSheet)" : "";
+        const needsArgs = m === "remove" ? "\\s*[^)\\s]" : "";
+        const re = new RegExp(`${lookbehind}\\.${m}\\s*\\(${needsArgs}`);
         if (re.test(line)) {
           // `.remove(` is also a useUsers method; only blame groups
           // when the source also uses the groups hook AND the source

package/dist/stats-hooks.js

@@ -0,0 +1,144 @@
+// sc-10691 — read-only hooks for an app's user totals and user activity. Each
+// is one keyed read, stale-while-revalidate like useDatastoreQuery, and each
+// re-runs on the page's pull-to-refresh.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toDirectoryError, useRefresh, useWidgetContextOrThrow } from "./hooks.js";
+
+const EMPTY = { identity: null, key: null, data: null, error: null };
+
+function serialize(value) {
+  try {
+    return JSON.stringify(value === undefined ? null : value);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Runs `read()` whenever `key` changes. A changed key on the same `identity`
+ * keeps the previous data on screen (`fetching`); a new identity starts over
+ * (`loading`). A null key is "nothing to read" and settles empty.
+ */
+function useKeyedRead(read, identity, key, mapError) {
+  const readRef = useRef(read);
+  readRef.current = read;
+  const runRef = useRef(0);
+  const [settled, setSettled] = useState(EMPTY);
+  const [fetching, setFetching] = useState(key !== null);
+
+  const run = useCallback(async () => {
+    const myRun = ++runRef.current;
+    if (key === null) {
+      setSettled(EMPTY);
+      setFetching(false);
+      return;
+    }
+    setFetching(true);
+    try {
+      const data = await readRef.current();
+      if (runRef.current === myRun) setSettled({ identity, key, data, error: null });
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setSettled((prev) => ({
+        identity,
+        key,
+        data: prev.identity === identity ? prev.data : null,
+        error: mapError(err),
+      }));
+    } finally {
+      if (runRef.current === myRun) setFetching(false);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [identity, key]);
+
+  useEffect(() => {
+    run();
+  }, [run]);
+  useRefresh(run);
+
+  const sameIdentity = settled.identity === identity;
+  return {
+    data: sameIdentity ? settled.data : null,
+    loading: key !== null && !sameIdentity,
+    fetching,
+    error: sameIdentity ? settled.error : null,
+    refetch: run,
+  };
+}
+
+/**
+ * The app's user totals for its own admins — never a list of people.
+ * `query`: `{ days?: 7 | 30 | 90, group_id? }`. Returns `{ stats, loading,
+ * fetching, error, refetch }`; `stats.invites` is null unless the viewer may
+ * list invites. A viewer without the admin user view gets a FORBIDDEN error.
+ */
+export function useUserStats(query) {
+  const ctx = useWidgetContextOrThrow("useUserStats");
+  if (!ctx.directory || !ctx.directory.users || typeof ctx.directory.users.stats !== "function") {
+    throw new Error("useUserStats: host did not inject a directory client (ctx.directory.users.stats)");
+  }
+  const users = ctx.directory.users;
+  const key = serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.stats(query), "stats", key, toDirectoryError);
+  return { ...state, stats: data };
+}
+
+function useUsersNamespace(hookName, method) {
+  const ctx = useWidgetContextOrThrow(hookName);
+  const users = ctx.directory && ctx.directory.users;
+  if (!users || typeof users[method] !== "function") {
+    throw new Error(`${hookName}: host did not inject a directory client (ctx.directory.users.${method})`);
+  }
+  return users;
+}
+
+/**
+ * sc-10691 — user activity for an app's admins: who is online now, active
+ * in the last day / week / month, never active, active users per bucket,
+ * the platform split and the active share per group. `query`: `{ days?: 7 |
+ * 30 | 90, group_id? }`. `error.reason` is "ACTIVITY_DISABLED" when the
+ * workspace does not record activity, "ACTIVITY_UNAVAILABLE" before it is
+ * offered to the workspace, and `error.code` FORBIDDEN without the
+ * users.activity permission. Pass `null` to read nothing.
+ */
+export function useUserActivity(query) {
+  const users = useUsersNamespace("useUserActivity", "activity");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.activity(query), "activity", key, toDirectoryError);
+  return { ...state, activity: data };
+}
+
+/**
+ * sc-10691 — one page of users not seen for `inactive_days` (default 30),
+ * never-seen first. `query`: `{ inactive_days?, group_id?, limit?, offset? }`.
+ * Returns `{ users, total, loading, fetching, error, refetch, remind }`; each
+ * user is `{ id, name, last_active_at, last_reminded_at }` (last_active_at
+ * null when never seen). `remind(id, { title, body })` notifies one and
+ * re-reads the page. Same gate as useUserActivity.
+ */
+export function useInactiveUsers(query) {
+  const users = useUsersNamespace("useInactiveUsers", "inactive");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.inactive(query), "inactive", key, toDirectoryError);
+  const { refetch } = state;
+  const remind = useCallback(
+    async (id, message) => {
+      if (typeof users.remind !== "function") {
+        throw new Error("useInactiveUsers: host did not inject ctx.directory.users.remind");
+      }
+      try {
+        await users.remind(id, message);
+      } catch (err) {
+        throw toDirectoryError(err);
+      }
+      await refetch();
+    },
+    [users, refetch],
+  );
+  return {
+    ...state,
+    remind,
+    users: data && Array.isArray(data.data) ? data.data : [],
+    total: data && data.meta && Number.isFinite(data.meta.total) ? data.meta.total : null,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.204.0",
+  "version": "0.205.1",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1975,6 +1975,95 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
+  // sc-10691 / REQ-USERMGMT-10 — an app's user totals for its own admins.
+  {
+    name: "useUserStats",
+    signature: "useUserStats({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "Workspace user TOTALS for an app's own administrators — never a list " +
+      "of people. `days` is 7 or 30 (charted per day) or 90 (per ISO week), in " +
+      "the workspace's time zone (`stats.period.time_zone`); " +
+      "`group_id` (a useGroups() row id) narrows the user and invite " +
+      "figures to that group. `stats.users` = { active, deactivated, " +
+      "without_group }; `stats.new_users` = { total, previous_total, buckets: " +
+      "[{ date, count }] } with every bucket present and previous_total the " +
+      "equal-length window before the period; `stats.groups` and " +
+      "`stats.empty_groups`; `stats.invites` = { " +
+      "pending, expiring_soon, expired, accepted }. `without_group`, `groups` " +
+      "and `empty_groups` are null on a group-scoped read. `invites` is null unless " +
+      "the widget also declares users.write:* AND the viewer holds users.write " +
+      "— render \"no access\" for that section rather than zeros. A viewer " +
+      "without the admin user view gets error.code FORBIDDEN; show an " +
+      "explicit no-access state.",
+    returnShape: {
+      stats:
+        "{ period, group_id, users, new_users, groups, empty_groups, invites } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN without the admin user view, NOT_FOUND for a foreign group",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.read:*"],
+  },
+  // sc-10691 / REQ-USERMGMT-12 — user activity, behind users.activity.
+  {
+    name: "useUserActivity",
+    signature: "useUserActivity({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "User ACTIVITY for an app's administrators, for a workspace that " +
+      "records it: `activity.online_now` (app open in the last two minutes), " +
+      "`activity.active` = { day (since midnight), week, month (last 7/30 " +
+      "days), period (distinct users active in the period) }, " +
+      "`activity.never_active`, " +
+      "`activity.daily_active` = [{ date, count }] distinct active users per " +
+      "day (7/30 days) or week (90) in the workspace's time zone, `activity.platforms` = { web, ios, " +
+      "android, unknown } users active in the period, `activity.by_group` = " +
+      "[{ group_id, name, users, active }] (null on a group-scoped read), " +
+      "`activity.users` and `activity.recording_since` (activity before it " +
+      "is unknown — say \"since <date>\" next to never-active figures). Needs " +
+      "users.activity:* AND the viewer's \"View user activity\" permission " +
+      "(else error.code FORBIDDEN). error.reason \"ACTIVITY_UNAVAILABLE\" means " +
+      "user activity is not offered to this workspace yet: hide the section, " +
+      "like FORBIDDEN. When the workspace does not record activity, " +
+      "error.reason is \"ACTIVITY_DISABLED\": show that state, not zeros. " +
+      "Pass null instead of a query to read nothing (a section switched off).",
+    returnShape: {
+      activity:
+        "{ period, group_id, recording_since, users, online_now, active, never_active, daily_active, platforms, by_group } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN; reason ACTIVITY_UNAVAILABLE (hide) or ACTIVITY_DISABLED (not recorded)",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
+  {
+    name: "useInactiveUsers",
+    signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
+    optionalArgs: ["inactive_days", "group_id", "limit", "offset"],
+    description:
+      "One page of users not seen for `inactive_days` (1-365, default 30), " +
+      "never-seen first, then least recently seen: `users` = [{ id, name, " +
+      "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
+      "since recording began), `total` for paging. `remind(id, { title, body })` " +
+      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "Same gate and errors as useUserActivity; null reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_reminded_at }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      remind: "(id, { title, body }) => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -5366,7 +5455,12 @@ const CONTRACT = deepFreeze({
   //    `Spinner` wears `colors.loader`; `Skeleton` reads the new `loading`
   //    component scope (colour, radius). A scope may now name `sdkComponents`
   //    and bind no widget field. Both stop under reduced motion.
-  version: "1.163.0",
+  // 1.164.0: additive (sc-10691) — `useUserStats(query)` reads an app's user
+  //    totals through the new `ctx.directory.users.stats`; `useUserActivity`
+  //    and `useInactiveUsers` read user activity through the new
+  //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
+  //    new `users.activity:*` scope.
+  version: "1.164.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,