@lotics/app-sdk 0.68.0 → 0.70.0

package/dist/src/hooks.d.ts

@@ -103,6 +103,18 @@ interface PaginatedQueryState<R> extends QueryStateBase {
 export interface QuerySortKey {
     field_key: string;
     order: "asc" | "desc";
+    /**
+     * Where rows BLANK in this column sit — `"bottom"` when omitted, which is what
+     * you want for "the ones with a value first".
+     *
+     * It earns its place on a MULTI-KEY sort over columns that are blank by
+     * position rather than by accident — a pipeline's per-step date stamps, say,
+     * where the first non-blank column IS the row's rank. Reading such a ladder
+     * from the top with blanks at the bottom orders it furthest-along-first; the
+     * reverse reading needs blanks on TOP, and with only the default there is no
+     * way to express it, so the column can be sorted one way and not the other.
+     */
+    blank_position?: "top" | "bottom";
 }
 /** A filter condition over one output column (wire shape of a filter node). */
 export interface QueryFilterCondition {

package/dist/src/members.d.ts

@@ -9,6 +9,20 @@
  *
  * If the wire format changes, the resolver and this reader move together.
  */
+/**
+ * A member, in the ONE shape every door returns — a `select_member` cell in a
+ * `useQuery` row and the `useMembers` roster alike.
+ *
+ * The two used to disagree: the roster carried an avatar, a resolved cell did
+ * not, and both were typed `ResolvedMember`, so an app author holding one could
+ * not tell which. That is why no register row ever rendered an avatar — the
+ * data was absent and nothing said so.
+ *
+ * The private fields share ONE boundary, not three: an authenticated member of
+ * the app's own org sees `email`, `image` and `groups`; an anonymous visitor to
+ * a public app sees `id` and `name`. Absent ≠ empty — `image: null` means the
+ * member has no photo, `image` MISSING means you were never told.
+ */
 export interface ResolvedMember {
     id: string;
     /** `null` when the id resolves outside the app's org (e.g. removed
@@ -18,9 +32,14 @@ export interface ResolvedMember {
     /** Present only on authenticated responses. Omitted on public-app
      *  responses (no PII exposure to anonymous visitors). */
     email?: string | null;
-    /** Avatar URL. Present on the `useMembers` roster (may be null when the
-     *  member has no profile image); absent on resolved `select_member` cells. */
+    /** Avatar URL, already presigned — render it directly. `null` when the member
+     *  has no profile image (the common case: photos are opt-in). Omitted on
+     *  public-app responses. */
     image?: string | null;
+    /** The member's group names — the platform's "department". There is no
+     *  department field; a member group is what an org uses to say Sale, Kế toán,
+     *  CSKH. `[]` when the member is in none. Omitted on public-app responses. */
+    groups?: string[];
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedMember[]`. Returns `[]` for

package/dist/src/members.js

@@ -28,13 +28,18 @@ export function readMembers(value) {
             continue;
         const name = typeof obj.name === "string" ? obj.name : obj.name === null ? null : null;
         const m = { id, name };
-        if ("email" in obj) {
-            m.email =
-                typeof obj.email === "string"
-                    ? obj.email
-                    : obj.email === null
-                        ? null
-                        : null;
+        // PRESENT ⇒ copy, ABSENT ⇒ leave off. The distinction is the permission
+        // boundary itself: a missing key means a public reader was never told,
+        // while `null` means the member genuinely has none. Defaulting either to
+        // null here would erase that and make a gated field look like an empty one.
+        if ("email" in obj)
+            m.email = typeof obj.email === "string" ? obj.email : null;
+        if ("image" in obj)
+            m.image = typeof obj.image === "string" ? obj.image : null;
+        if ("groups" in obj) {
+            m.groups = Array.isArray(obj.groups)
+                ? obj.groups.filter((g) => typeof g === "string")
+                : [];
         }
         out.push(m);
     }

package/docs/data_fetching.md

@@ -240,7 +240,7 @@ Wire shapes per output column type:
 | `date` | `"YYYY-MM-DD"` — a calendar day, no time component (a reduced-precision date field may also carry `"YYYY-MM"` or `"YYYY"`; see below) |
 | `datetime` | `"YYYY-MM-DDTHH:mm"` — workspace wall-clock, minute precision |
 | `select` | `Array<{ key, label }>` — one entry per selected option |
-| `select_member` | `Array<{ id, name, email? }>` — `email` only for authenticated viewers of the app's own org |
+| `select_member` | `Array<{ id, name, email?, image?, groups? }>` — the last three only for authenticated viewers of the app's own org; `image` presigned |
 | `select_record_link` | `Array<{ id, display }>` — target record id + its display text |
 | `files` | `Array<{ id, filename, mime_type, url, thumbnail_url?, size?, created_at? }>` — presigned |
 
@@ -268,7 +268,7 @@ emits none of these" is a fact the type states rather than one you have to remem
 | `row.link(cell)` | link cell → `{ id, display } \| null` | the FIRST linked record |
 | `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty) |
 | `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
-| `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email? }[]` (`[]` when empty) |
+| `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email?, image?, groups? }[]` (`[]` when empty) |
 | `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty) |
 | `readLocked(rowObj)` | the whole **row** → `boolean` | the record's lock state from `__source_locked` |
 

package/docs/members_and_options.md

@@ -16,8 +16,8 @@ Every select and member value reaches the app in one of two shapes, and most scr
 | --- | --- | --- |
 | Render a stored select value | `readSelect(cell)` | The options the record actually holds — `{ key, label }`, **no color** |
 | Populate a select picker, or color a stored value | `useFieldOptions(alias)` | Each select column's **complete** option list — `{ key, label, color }` — plus a `byKey` index |
-| Render a stored member value | `readMembers(cell)` | The members the record actually holds — `{ id, name, email? }`, **no avatar** |
-| Populate a member picker (assign UIs) | `useMembers(opts?)` | The org roster — `{ id, name, email, image }` (avatar included) |
+| Render a stored member value | `readMembers(cell)` | The members the record actually holds |
+| Populate a member picker (assign UIs) | `useMembers(opts?)` | The org roster — every member, not only the referenced ones |
 
 Cells are **self-describing**: the server rewrites raw storage shapes into resolved objects before
 rows reach the app, so an app never maintains a hardcoded key→label or id→name map. Catalogs are
@@ -108,18 +108,24 @@ cell's own `{ key, label }`, which renders as a neutral badge. Never hand-map op
 ## Member cells (`readMembers`)
 
 A `select_member` column's storage shape is a bare array of member ids. The server rewrites every
-projected `select_member` cell to `Array<{ id, name, email? }>`:
-
-- **`email` is present only for authenticated members of the app's own organization.** Anonymous
-  visitors to a public app — and members of *other* orgs viewing a publicly shared app — get
-  `{ id, name }` only. No PII crosses to viewers outside the org.
-- **An id that no longer resolves** (removed member, id outside the org) comes back as
-  `{ id, name: null }` — an explicit missing state, never an empty string. Render a placeholder.
-- **Cells never carry the avatar.** `ResolvedMember.image` exists only on the `useMembers` roster;
-  avatar URLs are presigned files and stay in that one bounded list rather than being fattened onto
-  every query cell.
+projected `select_member` cell to `Array<{ id, name, email?, image?, groups? }>` — **the same shape
+`useMembers` returns**, so a member is a member wherever you got them from:
+
+- **`email`, `image` and `groups` share ONE gate.** All three are present only for authenticated
+  members of the app's own organization. Anonymous visitors to a public app — and members of *other*
+  orgs viewing a publicly shared app — get `{ id, name }` only. A face and a team are org-internal
+  exactly as an address is.
+- **Absent is not null.** A missing `image` key means you were not told; `image: null` means the
+  member genuinely has no photo. Same for `groups`: absent vs `[]`. Rendering the two the same way
+  turns a permission boundary into a missing-data bug.
+- **`image` is already presigned** — render it directly. It is a `/v1/files/…` object behind a
+  cookie-authenticated proxy, so an unsigned URL would not load inside an app iframe at all.
+- **`groups` is the platform's "department".** There is no department field; a member group is what
+  an org uses to say Sale, Kế toán, CSKH. `[]` when the member is in none.
+- **An id that no longer resolves** (removed member, id outside the org) comes back with
+  `name: null` — an explicit missing state, never an empty string. Render a placeholder.
 - Only ids already present in the projected rows are resolved — a member cell never exposes the
-  wider directory.
+  wider directory, and only their avatars are signed.
 
 Decode with **`readMembers(cell)`** (`dist/src/members.d.ts`) → `ResolvedMember[]`. Same defensive
 contract as `readSelect`: `[]` for null/empty/unexpected cells, malformed entries dropped.
@@ -133,9 +139,9 @@ const { members, loading, error } = useMembers({ group: "grp_fulfillment" });
 <MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
 ```
 
-Each member is `{ id, name, email, image }`. `image` is the avatar URL (a presigned URL valid 24
-hours, or the member's external OAuth photo) and may be `null`. `name` may be null/empty for
-members without a display name — fall back to `email`. On failure the hook does not throw: it
+Each member is the same `ResolvedMember` a cell carries — `{ id, name, email, image, groups }`.
+`image` is the avatar URL (a presigned URL valid 24 hours, or the member's external OAuth photo) and
+may be `null`. `name` may be null/empty for members without a display name — fall back to `email`. On failure the hook does not throw: it
 resolves `{ members: [], loading: false, error }`.
 
 **Limitation:** `useMembers` is not SWR-cached — every mounted hook instance issues its own
@@ -294,7 +300,7 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 | Value | Component | Feed it |
 | --- | --- | --- |
 | A select value (stored or picker option) | `OptionBadge` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
-| A person, inline | `MemberChip` | `name` / `image` resolved from the roster or a cell; no image → initials |
+| A person, inline | `MemberChip` | `name` / `image` from a roster or a cell — both carry it; no image → initials |
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
 | A comment thread | `CommentList` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
 
@@ -305,7 +311,7 @@ The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter
 | Surface | Embedded (signed-in member) | Standalone / public (anonymous) |
 | --- | --- | --- |
 | `readSelect` cell enrichment | ✓ | ✓ |
-| `readMembers` cell enrichment | ✓ (email included, same-org) | ✓ name-only, no email |
+| `readMembers` cell enrichment | ✓ (email + image + groups, same-org) | ✓ name-only |
 | `useFieldOptions` | ✓ | ✓ |
 | `useMembers` | ✓ (same-org + declaration gates) | ✗ errors |
 | `useViewer` | member id (view-as target) | `null` |

package/docs/queries.md

@@ -124,8 +124,10 @@ Delivery-layer enrichment (applied to the response, per request):
   server-bounded (§10). Public apps hand out direct presigned URLs — anonymous-fetchable,
   time-boxed. (App workflow-execute responses presign returned files the same way, so their
   URLs also work for anonymous public-app viewers — see [files.md](./files.md).)
-- **`select_member` cells** — bare member-id arrays become `{ id, name, email? }[]` (`email`
-  only for authenticated members of the app's own org).
+- **`select_member` cells** — bare member-id arrays become
+  `{ id, name, email?, image?, groups? }[]`, the same shape `useMembers` returns. The last three
+  are org-internal and share one gate: present only for authenticated members of the app's own org,
+  and `image` arrives presigned.
 - **`select` cells** — bare option-key arrays become `{ key, label }[]` (colors ride in
   `useFieldOptions`, not the cell — see [members_and_options.md](./members_and_options.md)).
   **Enrichment needs the column's source addressing**, which a passthrough projection carries, a
@@ -768,10 +770,13 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   it. Record-link membership (`has_any_of` by id) **works** here; so does `is_current_member`
   on a member column. Traversals / `locked` / `current_member` do not — bake those into the
   template.
-- **`sort`** — `[{ field_key, order }]` over output columns — the typed `QuerySortKey` the hooks
-  accept. The wire sort node also honors `blank_position?: "top" | "bottom"` (blanks default to
-  bottom), but that field is **not** on the typed hook option; reach it only through a raw
-  `rpc("query", { sort })` call.
+- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns — the typed
+  `QuerySortKey` the hooks accept. `blank_position` is `"top" | "bottom"`, defaulting to
+  `"bottom"`. It matters on a **multi-key** sort over columns whose blankness IS the ranking —
+  a pipeline's per-step date stamps, where the first non-blank column gives the row's rung.
+  Listing the ladder top-down with blanks at the bottom orders it furthest-along-first; the
+  ascending reading needs `blank_position: "top"` on every key, and without it that direction
+  cannot be expressed at all.
 - **`limit` / `offset` / keyset `cursor`** — pagination. `useQuery` / `usePaginatedQuery` page by
   `offset` (`limit` clamped to the 10,000-row cap, §10); `useInfiniteQuery` opts into **keyset
   (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.68.0",
-  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
+  "version": "0.70.0",
+  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {