@lotics/app-sdk 0.78.0 → 0.79.0

package/dist/src/members.d.ts

@@ -18,10 +18,24 @@
  * 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.
+ * It happened a second time, and the fix is the same: the roster returned
+ * neither `groups` nor `role` long after a resolved cell carried both, so an
+ * app reading `m.groups` off `useMembers()` got `undefined` and drew nothing.
+ * Read a field here and you may read it on either door.
+ *
+ * The private fields share ONE boundary, not four: an authenticated member of
+ * the app's own org sees `email`, `image`, `groups` and `role`; an anonymous
+ * visitor to a public app sees `id` and `name` (plus `archived`, which is not
+ * private — see the field). Absent ≠ empty — `image: null` means the member has
+ * no photo, `image` MISSING means you were never told, and `groups: []` means
+ * they are on no team while a missing `groups` means the same "not told". Never
+ * collapse the two: one is a fact about a colleague, the other is a fact about
+ * your own permissions.
+ *
+ * The one field the doors legitimately differ on is `archived`, and it is a
+ * difference of ROW SET rather than of shape: a resolved cell must keep naming
+ * whoever handled a record two years ago, while the roster answers "who may I
+ * assign?" and never offers a departed member at all.
  */
 export interface ResolvedMember {
     id: string;
@@ -40,6 +54,47 @@ export interface ResolvedMember {
      *  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[];
+    /**
+     * The member's ORGANIZATION role. Omitted on public-app responses, and also
+     * when the id did not resolve — there is no member to have a level.
+     *
+     * It arrives RAW, and it is your job to translate it: the platform ships no
+     * display word for it, because a server that picked one would leak English
+     * into every localized app. Map it yourself (`admin` → "Quản trị viên") next
+     * to the rest of your vocabulary.
+     *
+     * It is a PERMISSION level and not a job title. Everyone who reads "Admin"
+     * beside a name on a sales register will read it as rank; if the question
+     * your screen answers is "who is this person in the company", the answer is
+     * `groups`, not this.
+     */
+    role?: "owner" | "admin" | "member";
+    /**
+     * ISO timestamp of when this person joined the organization. Omitted on
+     * public-app responses, and when the id did not resolve — there is no
+     * membership to have begun.
+     *
+     * Render it at whatever precision your question needs; `@lotics/ui`'s
+     * `MemberProfileCard` shows month and year, because "is this the new person?"
+     * does not want a day.
+     */
+    joined?: string;
+    /**
+     * `true` when this person has LEFT the organization — omitted otherwise,
+     * never `false`, because it rides every cell of every row and current staff
+     * are the overwhelming case.
+     *
+     * It arrives on both audiences: a departed colleague reading as a current
+     * assignee is wrong on a public app too, and it discloses less than the name
+     * already beside it. Feed it to `inactive` on `MemberChip` /
+     * `MemberProfileCard` so a record that still names them reads as history
+     * rather than as a live assignment.
+     *
+     * You will not see it on the `useMembers` roster, and that is correct rather
+     * than missing: the roster answers "who may I ASSIGN?" and departed members
+     * are not candidates, so it never returns one.
+     */
+    archived?: true;
 }
 /**
  * Parse a `useQuery` cell value into `ResolvedMember[]`. Returns `[]` for

package/dist/src/members.js

@@ -41,6 +41,21 @@ export function readMembers(value) {
                 ? obj.groups.filter((g) => typeof g === "string")
                 : [];
         }
+        // A CLOSED enum, so an unrecognized value is dropped rather than passed
+        // through: the field's whole worth is that a caller can switch on it, and a
+        // server that grew a fourth role must not have apps rendering the raw word
+        // in a UI that has no translation for it.
+        if (obj.role === "owner" || obj.role === "admin" || obj.role === "member")
+            m.role = obj.role;
+        // A non-empty STRING or nothing: an empty date is not a date, and letting
+        // "" through would render an empty labelled row rather than no row.
+        if (typeof obj.joined === "string" && obj.joined !== "")
+            m.joined = obj.joined;
+        // The server sends this ONLY for a departed member and only as `true`, so
+        // the truthy test is the whole contract — there is no `false` to carry, and
+        // inventing one would put the key on every current member's cell.
+        if (obj.archived === true)
+            m.archived = true;
         out.push(m);
     }
     return out;

package/docs/members_and_options.md

@@ -108,13 +108,13 @@ 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?, image?, groups? }>` — **the same shape
-`useMembers` returns**, so a member is a member wherever you got them from:
+projected `select_member` cell to `Array<{ id, name, email?, image?, groups?, role?, joined?, archived? }>` —
+**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.
+- **`email`, `image`, `groups`, `role` and `joined` share ONE gate.** All five 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, a team
+  and a permission level 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.
@@ -122,6 +122,18 @@ projected `select_member` cell to `Array<{ id, name, email?, image?, groups? }>`
   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.
+- **`role` arrives RAW (`owner` / `admin` / `member`) and you translate it.** The platform ships no
+  display word, because a server that picked one would leak English into every localized app — map
+  it next to the rest of your vocabulary. It is a PERMISSION level, not a job title: everyone reads
+  "Admin" beside a name as rank. If the question your screen asks is "who is this person in the
+  company", the answer is `groups`.
+- **`joined` is an ISO timestamp of when the membership began.** Render it at whatever precision
+  your question needs — `@lotics/ui`'s `MemberProfileCard` shows month and year, because "is this
+  the new person?" does not want a day. Absent on a public response, and on an id that did not
+  resolve: there is no membership to have begun.
+- **`archived: true` marks someone who has LEFT** — omitted otherwise, never `false`. It is the one
+  field that is NOT gated (a departed colleague reading as a current assignee is wrong on a public
+  app too). Feed it to `inactive` on `MemberChip` / `MemberProfileCard`.
 - **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
@@ -139,7 +151,10 @@ const { members, loading, error } = useMembers({ group: "grp_fulfillment" });
 <MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
 ```
 
-Each member is the same `ResolvedMember` a cell carries — `{ id, name, email, image, groups }`.
+Each member is the same `ResolvedMember` a cell carries — `{ id, name, email, image, groups, role, joined }`.
+The one field it never carries is `archived`, and that is the answer rather than a gap: this roster
+answers "who may I ASSIGN?", and a departed member is not a candidate, so it never returns one. A
+resolved CELL is the display door and keeps naming them.
 `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 }`.
@@ -311,7 +326,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 + image + groups, same-org) | ✓ name-only |
+| `readMembers` cell enrichment | ✓ (email + image + groups + role + joined, same-org) | ✓ name-only (+ `archived`) |
 | `useFieldOptions` | ✓ | ✓ |
 | `useMembers` | ✓ (same-org + declaration gates) | ✗ errors |
 | `useViewer` | member id (view-as target) | `null` |

package/package.json

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