@lotics/app-sdk 0.67.0 → 0.69.0

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/ai.md

@@ -24,8 +24,8 @@ A declaration carries:
 | `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
 | `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records. You list them; there is no "all of them" shorthand, and adding a query to the app never widens an existing agent. Omitted means the agent reads nothing |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
-| `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
-| `effort_level` | Optional reasoning depth for adaptive-thinking models. Requires an explicit `model_id` pin — effort is tuned per model |
+| `model_tier` | Optional model tier — `haiku` \| `sonnet` \| `opus`. Omit (preferred) to follow the platform default tier, resolved at run time. A tier names capability, not a version, so the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
+| `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
 | `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose) |
 

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

package/package.json

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