@argentic/chest-sdk 0.4.1 → 0.5.0

package/client/src/member.ts

@@ -12,8 +12,12 @@ import type { IncomingMessage } from "node:http";
 // - photo is the address of their picture on the tool's team host
 //   (/_chest/members/{id}/photo?v=<rev>), role one of the roles chest.json
 //   declares: null when there is none.
-// - isBuilder says they build this tool; groups are the groups that give them
-//   this tool ("grp_…").
+// - isBuilder says they build this tool; groups are those of their groups
+//   the tool sees ("grp_…"): the groups that give them this tool, or all of
+//   their groups when the tool holds "members.groups". null when they are in
+//   more groups than travel with a request (about 150: the assertion keeps
+//   within half of a Node server's 16 KiB of headers): read them with
+//   members.get(member.id) — Microsoft's "groups overage", the same way.
 // - language is the language the Chest speaks to this member (their own,
 //   else the Chest's default): a BCP 47 primary tag the product speaks
 //   ("en", "fr"…). The tool's private part (/chest) speaks it to them; a
@@ -32,7 +36,7 @@ export type Member = {
   role: string | null;
   isAdmin: boolean;
   isBuilder: boolean;
-  groups: string[];
+  groups: string[] | null;
   language: string;
   timeZone: string;
   email?: string;
@@ -58,9 +62,9 @@ export const timeZonePattern = /^(?:UTC|[A-Z][A-Za-z_]{1,31}(?:\/[A-Za-z0-9_+-]{
 // reader of the former claims still reads them. This module stands alone
 // (node:* only), so that it can be copied by itself.
 const label = "Chest-Member v2";
-// The claims every assertion carries; email only for a tool that holds
-// members.email.
-const claims = ["iss", "aud", "iat", "exp", "sub", "given_name", "family_name", "name", "picture", "role", "admin", "builder", "groups", "language", "time_zone"] as const;
+// The claims every assertion carries; groups unless groups_overage says
+// they did not fit; email only for a tool that holds members.email.
+const claims = ["iss", "aud", "iat", "exp", "sub", "given_name", "family_name", "name", "picture", "role", "admin", "builder", "language", "time_zone"] as const;
 // Clocks of the Chest and of the container may differ by this much, in seconds.
 const skew = 5;
 // An assertion is a few hundred bytes; anything longer is not one.
@@ -107,13 +111,15 @@ export function member(request: IncomingMessage | Request): Member | null {
   if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return null;
   const payload = json(encodedPayload);
   if (!payload || !claims.every(name => Object.hasOwn(payload, name))) return null;
-  const { iss, aud, iat, exp, sub, given_name, family_name, name, email, picture, role, admin, builder, groups, language, time_zone } = payload;
+  const { iss, aud, iat, exp, sub, given_name, family_name, name, email, picture, role, admin, builder, groups, groups_overage, language, time_zone } = payload;
   if (typeof iss !== "string" || iss === "" || aud !== tool || typeof sub !== "string" || !memberIdPattern.test(sub)) return null;
   if (typeof iat !== "number" || !Number.isSafeInteger(iat) || typeof exp !== "number" || !Number.isSafeInteger(exp) || exp <= iat) return null;
   const now = Math.floor(Date.now() / 1000);
   if (iat > now + skew || exp <= now - skew) return null;
   if (typeof given_name !== "string" || typeof family_name !== "string" || typeof name !== "string" || typeof picture !== "string" || typeof role !== "string" || typeof admin !== "boolean" || typeof builder !== "boolean") return null;
-  if (!Array.isArray(groups) || groups.length > 16 || !groups.every(g => typeof g === "string" && groupIdPattern.test(g)) || (email !== undefined && typeof email !== "string")) return null;
+  const overage = groups_overage === true && groups === undefined;
+  if (!overage && (groups_overage !== undefined || !Array.isArray(groups) || !groups.every(g => typeof g === "string" && groupIdPattern.test(g)))) return null;
+  if (email !== undefined && typeof email !== "string") return null;
   if (typeof language !== "string" || !languagePattern.test(language) || typeof time_zone !== "string" || !timeZonePattern.test(time_zone)) return null;
-  return { id: sub, firstName: given_name, lastName: family_name, name, photo: picture === "" ? null : picture, role: role === "" ? null : role, isAdmin: admin, isBuilder: builder, groups: [...groups] as string[], language, timeZone: time_zone, ...(email === undefined ? {} : { email }) };
+  return { id: sub, firstName: given_name, lastName: family_name, name, photo: picture === "" ? null : picture, role: role === "" ? null : role, isAdmin: admin, isBuilder: builder, groups: overage ? null : [...groups as string[]], language, timeZone: time_zone, ...(email === undefined ? {} : { email }) };
 }

package/client/src/members.ts

@@ -3,7 +3,8 @@ import { ChestError, Unavailable } from "./errors.js";
 import { groupIdPattern, languagePattern, memberIdPattern, timeZonePattern, type Member } from "./member.js";
 
 // Who has the tool, for a server tool whose chest.json declares
-// "capabilities": ["members"] (and "members.email" for their addresses):
+// "capabilities": ["members"] (and "members.email" for their addresses,
+// "members.groups" for every group of the Chest):
 // exactly the members who have access to it at the time of the call — by a
 // grant, a group, open to all, or because they run it. list and get see
 // only them; lookup also names those the tool had who no longer have it
@@ -13,7 +14,7 @@ import { groupIdPattern, languagePattern, memberIdPattern, timeZonePattern, type
 //   const { members: page, next } = await members.list({ q: "cam" });
 //   const one = await members.get("mbr_…");            // null: no such member here
 //   const { members: found, former, unknown } = await members.lookup(ids);
-//   const all = await members.groups.list();          // groups that give the tool
+//   const { groups, next: more } = await members.groups.list(); // the groups the tool sees, a page
 //
 // Store member identifiers in your data, never names or addresses: resolve
 // them when rendering, with lookup. Errors: CapabilityNotGranted (403),
@@ -32,8 +33,11 @@ export type FormerMember = { id: string; name: string | null; status: "no_access
 // longer have it, and identifiers the tool does not know — never had, or
 // forgotten.
 export type Lookup = { members: Member[]; former: FormerMember[]; unknown: string[] };
-// A group that gives the tool, with the identifiers of its members.
-export type Group = { id: string; name: string; members: string[] };
+// A group the tool sees, and its size: how many of its members have the
+// tool — members.list({ group: id }) pages them.
+export type Group = { id: string; name: string; size: number };
+// A page of groups, and the cursor of the next one (null after the last).
+export type GroupPage = { groups: Group[]; next: string | null };
 
 const maxLimit = 500;
 const lookupBatch = 200;
@@ -51,7 +55,7 @@ const text = (value: unknown, max: number): value is string => typeof value ===
 // Chest's answer.
 function shown(value: unknown): Member {
   const m = value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
-  if (!m || typeof m["id"] !== "string" || !memberIdPattern.test(m["id"]) || !text(m["first_name"], 256) || !text(m["last_name"], 256) || !text(m["name"], 520) || !(m["photo"] === null || text(m["photo"], 200)) || !(m["role"] === null || text(m["role"], 48)) || typeof m["admin"] !== "boolean" || typeof m["builder"] !== "boolean" || !Array.isArray(m["groups"]) || m["groups"].length > 16 || !m["groups"].every(g => typeof g === "string" && groupIdPattern.test(g)) || typeof m["language"] !== "string" || !languagePattern.test(m["language"]) || typeof m["time_zone"] !== "string" || !timeZonePattern.test(m["time_zone"]) || !(m["email"] === undefined || text(m["email"], 254))) throw new Unavailable();
+  if (!m || typeof m["id"] !== "string" || !memberIdPattern.test(m["id"]) || !text(m["first_name"], 256) || !text(m["last_name"], 256) || !text(m["name"], 520) || !(m["photo"] === null || text(m["photo"], 200)) || !(m["role"] === null || text(m["role"], 48)) || typeof m["admin"] !== "boolean" || typeof m["builder"] !== "boolean" || !Array.isArray(m["groups"]) || !m["groups"].every(g => typeof g === "string" && groupIdPattern.test(g)) || typeof m["language"] !== "string" || !languagePattern.test(m["language"]) || typeof m["time_zone"] !== "string" || !timeZonePattern.test(m["time_zone"]) || !(m["email"] === undefined || text(m["email"], 254))) throw new Unavailable();
   return { id: m["id"], firstName: m["first_name"], lastName: m["last_name"], name: m["name"], photo: m["photo"], role: m["role"], isAdmin: m["admin"], isBuilder: m["builder"], groups: [...m["groups"]] as string[], language: m["language"], timeZone: m["time_zone"], ...(m["email"] === undefined ? {} : { email: m["email"] }) };
 }
 
@@ -155,18 +159,32 @@ export async function lookup(ids: Iterable<string>): Promise<Lookup> {
   return result;
 }
 
-// groups are the groups of the Chest that give the tool, each with the
-// identifiers of its members; nothing of the others.
+// groups are the groups of the Chest the tool sees, a page at a time like
+// members, by name then identifier: the groups that give it — or, with
+// "members.groups", every group of the Chest, so that a tool open to
+// everyone can offer "the Sales team". Each says its size; its members are
+// members.list({ group }). Store group identifiers and resolve names when
+// rendering, as for members; who joins or leaves one is member.updated
+// naming "groups".
 export const groups = {
-  async list(): Promise<Group[]> {
-    const response = await ask("members", "GET", "/groups");
+  async list(options: { after?: string; limit?: number } = {}): Promise<GroupPage> {
+    const query = new URLSearchParams();
+    if (options.after !== undefined) query.set("after", options.after);
+    if (options.limit !== undefined) {
+      if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > maxLimit) throw new ChestError("invalid_query", 400, "limit is 1 to 500");
+      query.set("limit", String(options.limit));
+    }
+    const response = await ask("members", "GET", "/groups" + (query.size ? "?" + query.toString() : ""));
     if (response.status !== 200) throw await refusal(response, "members");
-    const answer = (await json(response)) as { groups?: unknown } | null;
-    if (!answer || !Array.isArray(answer.groups) || answer.groups.length > 16) throw new Unavailable();
-    return answer.groups.map(value => {
-      const g = value as { id?: unknown; name?: unknown; members?: unknown } | null;
-      if (!g || typeof g.id !== "string" || !groupIdPattern.test(g.id) || !text(g.name, 256) || !Array.isArray(g.members) || g.members.length > 128 || !g.members.every(m => typeof m === "string" && memberIdPattern.test(m))) throw new Unavailable();
-      return { id: g.id, name: g.name, members: [...g.members] as string[] };
-    });
+    const page = (await json(response)) as { groups?: unknown; next?: unknown } | null;
+    if (!page || !Array.isArray(page.groups) || page.groups.length > maxLimit || !(page.next === null || text(page.next, 1024))) throw new Unavailable();
+    return {
+      groups: page.groups.map(value => {
+        const g = value as { id?: unknown; name?: unknown; size?: unknown } | null;
+        if (!g || typeof g.id !== "string" || !groupIdPattern.test(g.id) || !text(g.name, 256) || typeof g.size !== "number" || !Number.isSafeInteger(g.size) || g.size < 0) throw new Unavailable();
+        return { id: g.id, name: g.name, size: g.size };
+      }),
+      next: page.next,
+    };
   },
 };

package/client/src/notifications.ts

@@ -1,32 +1,51 @@
 import { ask as chest, json, refusal } from "./api.js";
 import { ChestError, Unavailable } from "./errors.js";
-import { memberIdPattern } from "./member.js";
+import { rolePattern } from "./eventrules.js";
+import { groupIdPattern, languagePattern, memberIdPattern } from "./member.js";
 
 // Counters and notifications inside the Chest, for a server tool whose
 // chest.json declares "capabilities": ["notifications"]: a badge is a count
 // shown on the tool's tile for one member; a notification is an item in a
 // member's inbox that opens a page of the tool. Only members who have access
-// to the tool receive them; nothing leaves the Chest (no email, no push).
+// to the tool receive them. The tool sends nothing else: members may get
+// mails of their notifications, as each of them chooses — the Chest's
+// service. A notice may say the same in other languages: each member reads
+// the one of theirs (member.language), the tool's own otherwise. Nothing is
+// refused for its pace: beyond ten at once to a member, then one every six
+// minutes, the Chest folds a tool's notices into one grouped item of that
+// member's inbox ("37 new notifications", the latest shown) — the call
+// still succeeds, nothing is lost.
 //
 //   import * as notifications from "@argentic/chest-sdk/notifications";
 //   const { delivered, skipped } = await notifications.notify(ids, { title: "New task", path: "/chest/tasks/42", key: "task:42" });
+//   await notifications.broadcast({ title: "New poll", translations: { fr: { title: "Nouveau sondage" } }, path: "/chest/polls/7" }, { to: { groups: ["grp_…"] }, except: [author] });
 //   await notifications.withdraw("task:42");                // the task is done: its items go
 //   const shown = await notifications.badge.set("mbr_…", 3); // false: no access
 //   await notifications.badge.setMany([{ memberId: "mbr_…", count: 0 }]);
 //
 // Text is plain: the Chest removes control characters, interprets neither
 // Markdown nor HTML, keeps line breaks in body. A member who muted the tool
-// counts as delivered: the tool never learns it. Errors: CapabilityNotGranted
-// (403), QuotaExceeded (429: 1,000 recipients an hour, 100 items per member a
-// day, 600 badge writes a minute), Unavailable (503, or the Chest not
-// reached), ChestError otherwise (invalid_id, invalid_title, invalid_text,
-// invalid_path, invalid_key, invalid_count, invalid_body 400).
+// counts as delivered: the tool never learns it. Badges are a state, the
+// last write wins. Errors: CapabilityNotGranted (403), Unavailable (503, or
+// the Chest not reached), ChestError otherwise — only a malformed or
+// oversized call
+// (invalid_id, invalid_role, invalid_title, invalid_text, invalid_path,
+// invalid_key, invalid_language, invalid_count, invalid_body 400).
 
-// What a notification says: title (1 to 80 characters), body (280 at most),
-// path (the page of the tool it opens, under /chest; /chest when not said)
-// and key (a name of the tool's: an item of the same key for the same member
-// is replaced, and withdraw removes it).
-export type Notice = { title: string; body?: string; path?: string; key?: string };
+// The words of a notification in one language: title (1 to 80 characters)
+// and body (280 at most).
+export type Words = { title: string; body?: string };
+// What a notification says: its words in the tool's own language, path (the
+// page of the tool it opens, under /chest; /chest when not said), key (a
+// name of the tool's: an item of the same key for the same member is
+// replaced, and withdraw removes it) and translations: the same words in
+// other languages, by language tag ("fr"), each member reading theirs.
+export type Notice = Words & { path?: string; key?: string; translations?: Record<string, Words> };
+// Whom a broadcast reaches: every member who has the tool, or with to those
+// in any of its groups or holding any of its roles — a group the tool does
+// not see, or a role it does not declare, reaches no one —, but those of
+// except (the author, those who already answered).
+export type Audience = { to?: { groups?: string[]; roles?: string[] }; except?: Iterable<string> };
 // Who got it and who not, each identifier once in the order given: skipped
 // are identifiers the Chest does not know and members without access.
 export type Delivery = { delivered: string[]; skipped: string[] };
@@ -36,8 +55,10 @@ export type BadgeCount = { memberId: string; count: number };
 // order given.
 export type BadgeWrite = { set: string[]; skipped: string[] };
 
-// The bounds of a Chest.
-const maxMembers = 500, maxTitle = 80, maxBody = 280, maxPath = 512, maxCount = 9999;
+// The bounds of a Chest on a call's texts and counts, and the roles a tool
+// declares. No count bounds the members a call names: the Chest takes as
+// many as its team holds, and refuses a body beyond (invalid_body).
+const maxTitle = 80, maxBody = 280, maxPath = 512, maxCount = 9999, toolRoles = 16;
 const keyPattern = /^[a-z0-9._:-]{1,64}$/u;
 // What the Chest removes from a title before keeping it: control characters
 // and the characters that reorder text.
@@ -60,10 +81,10 @@ function checkId(id: unknown): string {
   if (typeof id !== "string" || !memberIdPattern.test(id)) throw new ChestError("invalid_id", 400, "invalid member identifier");
   return id;
 }
-// checkIds reads 1 to 500 member identifiers, as given.
+// checkIds reads member identifiers, one at least, as given.
 function checkIds(ids: Iterable<string>): string[] {
   const all = [...ids];
-  if (all.length < 1 || all.length > maxMembers) throw new ChestError("invalid_body", 400, "1 to 500 member identifiers");
+  if (all.length < 1) throw new ChestError("invalid_body", 400, "one member identifier at least");
   return all.map(checkId);
 }
 function checkKey(key: unknown): string {
@@ -95,24 +116,60 @@ function partition(answer: unknown, first: string, second: string, asked: string
   return [[...one], [...two]];
 }
 
+// checkWords reads a title and a body as the Chest bounds them.
+function checkWords(words: unknown): Words {
+  const { title, body } = (words ?? {}) as Partial<Words>;
+  if (typeof title !== "string" || length(title) < 1 || length(title) > maxTitle || title.replace(removed, "").trim() === "") throw new ChestError("invalid_title", 400, "a title is 1 to 80 characters");
+  if (body !== undefined && (typeof body !== "string" || length(body) > maxBody)) throw new ChestError("invalid_text", 400, "a body is 280 characters at most");
+  return { title, ...(body ? { body } : {}) };
+}
+
+// command is a notice as the Chest reads it.
+function command(notice: Notice): Record<string, unknown> {
+  const { path, key, translations } = notice;
+  const other: Record<string, Words> = {};
+  for (const [language, words] of Object.entries(translations ?? {})) {
+    if (!languagePattern.test(language)) throw new ChestError("invalid_language", 400, "a language is a tag such as fr");
+    other[language] = checkWords(words);
+  }
+  return { ...checkWords(notice), ...(path !== undefined ? { path: checkPath(path) } : {}), ...(key !== undefined ? { key: checkKey(key) } : {}), ...(translations !== undefined ? { translations: other } : {}) };
+}
+
 // notify puts one item in the inbox of each member who has the tool, among
-// 1 to 500 identifiers (each counted once). A link to path, on the tool's
-// team host, opens it. With a key, the member's item of that key is replaced:
-// new text, new time, first and unread again.
+// the identifiers given (each counted once), in their language. A link to
+// path, on the tool's team host, opens it. With a key, the member's item of
+// that key is replaced: new text, new time, first and unread again.
 export async function notify(memberIds: Iterable<string>, notice: Notice): Promise<Delivery> {
   const members = checkIds(memberIds);
-  const { title, body, path, key } = notice;
-  if (typeof title !== "string" || length(title) < 1 || length(title) > maxTitle || title.replace(removed, "").trim() === "") throw new ChestError("invalid_title", 400, "a title is 1 to 80 characters");
-  if (body !== undefined && (typeof body !== "string" || length(body) > maxBody)) throw new ChestError("invalid_text", 400, "a body is 280 characters at most");
-  const command = { members, title, ...(body ? { body } : {}), ...(path !== undefined ? { path: checkPath(path) } : {}), ...(key !== undefined ? { key: checkKey(key) } : {}) };
-  const response = await ask("POST", "/notifications", command);
+  const response = await ask("POST", "/notifications", { members, ...command(notice) });
   await expect(response, 200);
   const [delivered, skipped] = partition(await json(response), "delivered", "skipped", members);
   return { delivered, skipped };
 }
 
+// broadcast puts one item, in their language, in the inbox of every member
+// who has the tool now — or of those the audience names —, the Chest
+// resolving who they are: the tool needs not see its members. It never says
+// how many received it. Each recipient counts in the quotas, all or none.
+export async function broadcast(notice: Notice, audience: Audience = {}): Promise<void> {
+  const { to } = audience;
+  let target: { groups?: string[]; roles?: string[] } | undefined;
+  if (to !== undefined) {
+    const groups = to.groups === undefined ? undefined : [...to.groups], roles = to.roles === undefined ? undefined : [...to.roles];
+    if (!groups?.length && !roles?.length) throw new ChestError("invalid_body", 400, "to names groups or roles: leave it out for everyone");
+    if ((roles?.length ?? 0) > toolRoles) throw new ChestError("invalid_body", 400, "16 roles at most: those the tool declares");
+    if (groups && !groups.every(g => typeof g === "string" && groupIdPattern.test(g))) throw new ChestError("invalid_id", 400, "invalid group identifier");
+    if (roles && !roles.every(r => typeof r === "string" && rolePattern.test(r))) throw new ChestError("invalid_role", 400, "invalid role");
+    target = { ...(groups?.length ? { groups } : {}), ...(roles?.length ? { roles } : {}) };
+  }
+  const except = audience.except === undefined ? undefined : [...audience.except];
+  except?.forEach(checkId);
+  const response = await ask("POST", "/notifications/broadcast", { ...command(notice), ...(target ? { to: target } : {}), ...(except?.length ? { except } : {}) });
+  await expect(response, 204);
+}
+
 // withdraw removes the items of that key, from every member or from those
-// named (1 to 500): the thing they were about is done. It never says what
+// named: the thing they were about is done. It never says what
 // existed.
 export async function withdraw(key: string, memberIds?: Iterable<string>): Promise<void> {
   const command = { key: checkKey(key), ...(memberIds !== undefined ? { members: checkIds(memberIds) } : {}) };
@@ -131,10 +188,10 @@ export const badge = {
     await expect(response, 200);
     return partition(await json(response), "set", "skipped", [memberId])[0].length === 1;
   },
-  // setMany sets 1 to 500 badges, a member at most once.
+  // setMany sets badges, one at least, a member at most once.
   async setMany(counts: Iterable<BadgeCount>): Promise<BadgeWrite> {
     const all = [...counts];
-    if (all.length < 1 || all.length > maxMembers) throw new ChestError("invalid_body", 400, "1 to 500 badges");
+    if (all.length < 1) throw new ChestError("invalid_body", 400, "one badge at least");
     const badges = all.map(b => {
       if (b === null || typeof b !== "object") throw new ChestError("invalid_body", 400, "a badge is {memberId, count}");
       return { member: checkId(b.memberId), count: checkCount(b.count) };