@colixsystems/widget-sdk 0.213.0 → 0.214.0

package/README.md

@@ -83,7 +83,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.213.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.214.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.214.0 (contract 1.173.0)
+
+**Who is behind a figure — `useActiveUsers({ within, group_id, limit, offset })`.** One page of the users seen within `within` — `"online"` (default; the app open in the last two minutes), `"day"` (since midnight in the workspace's time zone), `"week"` or `"month"` (the last 7 / 30 days) — most recently seen first, as `[{ id, name, last_active_at, last_platform }]` with `total` for paging. Same gate as `useUserActivity` (`users.activity:*` plus the "View user activity" permission); pass `null` to read nothing.
+
+**"Who joined" — `useUsers({ joined_since, sort: "newest" })`.** The admin user list narrows to users created since `joined_since` (a `YYYY-MM-DD` date read in the workspace's time zone, or an ISO instant) and lists them newest first. Join dates are admin data, so a caller with only the directory view gets the plain list.
+
+**Reminding several — `remind(id, message, { refetch: false })`.** `useInactiveUsers`' `remind` re-reads the page after each reminder; pass `{ refetch: false }` while sending a batch and call `refetch()` once at the end.
 
 ### What's new in 0.213.0 (contract 1.172.0)
 
@@ -246,7 +254,7 @@ Like the `loading` scope, `alert` styles an SDK component rather than a widget's
 
 **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`).
+**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`); pass `{ refetch: false }` as a third argument when reminding several, then call `refetch()` once. 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.
 

package/dist/contract.cjs

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -5640,7 +5667,11 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -5636,7 +5663,11 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -1107,6 +1107,21 @@ export function useUserActivity(query?: { days?: 7 | 30 | 90; group_id?: string
   refetch(): Promise<void>;
 };
 
+/** Users seen within `within` (default "online"), most recently seen first. */
+export function useActiveUsers(query?: {
+  within?: "online" | "day" | "week" | "month";
+  group_id?: string;
+  limit?: number;
+  offset?: number;
+} | null): {
+  users: Array<{ id: string; name: string; last_active_at: string; last_platform: "web" | "ios" | "android" | "unknown" }>;
+  total: number | 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;
@@ -1121,7 +1136,8 @@ export function useInactiveUsers(query?: {
   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>;
+  /** `{ refetch: false }` skips re-reading the page, for a batch that reads once. */
+  remind(id: string, message: { title: string; body: string }, options?: { refetch?: boolean }): Promise<void>;
 };
 
 /** One record's online members, as `useOnlineMembers` reports them. */
@@ -2743,6 +2759,12 @@ export interface UsersQuery {
   is_active?: boolean;
   /** Restrict to members of one app-user group — the `id` of a `useGroups()` row. */
   group_id?: string;
+  /** Admin view only: users created since this date (workspace time zone) or instant. */
+  joined_since?: string;
+  /** Admin view only: "newest" lists the most recently created first. */
+  sort?: "name" | "newest";
+  /** "real" leaves out preview and store-review accounts; an in-app admin always gets "real". */
+  audience?: "all" | "real" | "preview";
   limit?: number;
   offset?: number;
 }

package/dist/index.js

@@ -127,6 +127,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.

package/dist/index.native.js

@@ -125,6 +125,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.

package/dist/stats-hooks.js

@@ -108,13 +108,32 @@ export function useUserActivity(query) {
   return { ...state, activity: data };
 }
 
+/**
+ * sc-11066 — one page of users seen within `within` ("online" — the last two
+ * minutes — "day", "week" or "month"), most recently seen first. `query`:
+ * `{ within?, group_id?, limit?, offset? }`. Returns `{ users, total, loading,
+ * fetching, error, refetch }`; each user is `{ id, name, last_active_at,
+ * last_platform }`. Same gate as useUserActivity; null reads nothing.
+ */
+export function useActiveUsers(query) {
+  const users = useUsersNamespace("useActiveUsers", "active");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.active(query), "active-users", key, toDirectoryError);
+  return {
+    ...state,
+    users: data && Array.isArray(data.data) ? data.data : [],
+    total: data && data.meta && Number.isFinite(data.meta.total) ? data.meta.total : null,
+  };
+}
+
 /**
  * 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.
+ * re-reads the page; `{ refetch: false }` as a third argument skips the
+ * re-read, so a batch reads once at the end. Same gate as useUserActivity.
  */
 export function useInactiveUsers(query) {
   const users = useUsersNamespace("useInactiveUsers", "inactive");
@@ -122,7 +141,7 @@ export function useInactiveUsers(query) {
   const { data, ...state } = useKeyedRead(() => users.inactive(query), "inactive", key, toDirectoryError);
   const { refetch } = state;
   const remind = useCallback(
-    async (id, message) => {
+    async (id, message, { refetch: reread = true } = {}) => {
       if (typeof users.remind !== "function") {
         throw new Error("useInactiveUsers: host did not inject ctx.directory.users.remind");
       }
@@ -131,7 +150,7 @@ export function useInactiveUsers(query) {
       } catch (err) {
         throw toDirectoryError(err);
       }
-      await refetch();
+      if (reread) await refetch();
     },
     [users, refetch],
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.213.0",
+  "version": "0.214.0",
   "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

@@ -1960,7 +1960,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2084,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2117,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2127,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -5636,7 +5663,11 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  version: "1.173.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,