@argentic/chest-sdk 0.1.0 → 0.2.0

package/client/src/members.ts

@@ -0,0 +1,167 @@
+import { ask, json, refusal } from "./api.js";
+import { ChestError, Unavailable } from "./errors.js";
+import { groupIdPattern, memberIdPattern, 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):
+// 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. A member without
+// access is indistinguishable from an identifier that does not exist.
+//
+//   import * as members from "@argentic/chest-sdk/members";
+//   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
+//
+// Store member identifiers in your data, never names or addresses: resolve
+// them when rendering, with lookup. Errors: CapabilityNotGranted (403),
+// RateLimited (429, 600 calls a minute), Unavailable (503, or the Chest not
+// reached), ChestError otherwise (invalid_id, invalid_query 400).
+
+// A page of the list, and the cursor of the next one (null after the last).
+export type MemberPage = { members: Member[]; next: string | null };
+// A member who left the Chest after having the tool: "former" with the name
+// they had, or "erased" without any once the owner had their data erased —
+// render “Former member”.
+export type FormerMember = { id: string; name: string | null; status: "former" | "erased" };
+// What a lookup found: members who have the tool, former members, and
+// identifiers the tool does not know.
+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[] };
+
+const maxLimit = 500;
+const lookupBatch = 200;
+const cacheTime = 60_000;
+const cacheSize = 5000;
+
+function checkId(id: unknown): string {
+  if (typeof id !== "string" || !memberIdPattern.test(id)) throw new ChestError("invalid_id", 400, "invalid member identifier");
+  return id;
+}
+
+const text = (value: unknown, max: number): value is string => typeof value === "string" && value.length <= max;
+
+// shown reads a member as the Chest answers it; anything else is not the
+// 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)) || !(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[], ...(m["email"] === undefined ? {} : { email: m["email"] }) };
+}
+
+// list says the members who have the tool, by name then identifier, limit
+// at a time (100 by default, 500 at most), after the cursor of the previous
+// page. q finds the start of a first name, a last name or a name (and of an
+// address with members.email), whatever its case and accents; role and group
+// keep the members of that role, or of that group.
+export async function list(options: { after?: string; limit?: number; q?: string; role?: string; group?: string } = {}): Promise<MemberPage> {
+  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));
+  }
+  if (options.q !== undefined && options.q !== "") query.set("q", options.q);
+  if (options.role !== undefined) query.set("role", options.role);
+  if (options.group !== undefined) {
+    if (!groupIdPattern.test(options.group)) throw new ChestError("invalid_query", 400, "invalid group identifier");
+    query.set("group", options.group);
+  }
+  const response = await ask("members", "GET", "/members" + (query.size ? "?" + query.toString() : ""));
+  if (response.status !== 200) throw await refusal(response, "members");
+  const page = (await json(response)) as { members?: unknown; next?: unknown } | null;
+  if (!page || !Array.isArray(page.members) || page.members.length > maxLimit || !(page.next === null || text(page.next, 1024))) throw new Unavailable();
+  return { members: page.members.map(shown), next: page.next };
+}
+
+// get is the member of that identifier, or null when the tool does not know
+// them: never a member, a former one, or one without access.
+export async function get(id: string): Promise<Member | null> {
+  const response = await ask("members", "GET", "/members/" + checkId(id));
+  if (response.status === 404) {
+    await response.body?.cancel();
+    return null;
+  }
+  if (response.status !== 200) throw await refusal(response, "members");
+  return shown(await json(response));
+}
+
+// What lookup keeps in this process: each identifier's answer for a minute,
+// 5000 of them at most, the oldest forgotten first — and nothing once an
+// event of the members' lifecycle comes (events.handle).
+type Known = { at: number } & ({ member: Member } | { former: FormerMember } | { unknown: true });
+const known = new Map<string, Known>();
+
+// forget empties what lookup keeps: the next lookup asks the Chest again.
+export function forget(): void {
+  known.clear();
+}
+
+function keep(id: string, answer: Omit<Known, "at">): void {
+  known.delete(id);
+  known.set(id, { ...answer, at: Date.now() } as Known);
+  while (known.size > cacheSize) known.delete(known.keys().next().value as string);
+}
+
+// lookup resolves identifiers, each once, in the order given: the members
+// who have the tool, the former members who had it, and the identifiers it
+// does not know. Any number of them: the SDK asks 200 at a time, and keeps
+// each answer a minute.
+export async function lookup(ids: Iterable<string>): Promise<Lookup> {
+  const wanted = [...new Set([...ids].map(checkId))];
+  const now = Date.now();
+  const missing = wanted.filter(id => {
+    const k = known.get(id);
+    return !k || now - k.at >= cacheTime;
+  });
+  for (let i = 0; i < missing.length; i += lookupBatch) {
+    const batch = missing.slice(i, i + lookupBatch);
+    const response = await ask("members", "POST", "/members/lookup", { body: JSON.stringify({ ids: batch }), type: "application/json" });
+    if (response.status !== 200) throw await refusal(response, "members");
+    const answer = (await json(response)) as { members?: unknown; former?: unknown; unknown?: unknown } | null;
+    if (!answer || !Array.isArray(answer.members) || !Array.isArray(answer.former) || !Array.isArray(answer.unknown)) throw new Unavailable();
+    const told = new Set<string>();
+    for (const m of answer.members.map(shown)) {
+      keep(m.id, { member: m });
+      told.add(m.id);
+    }
+    for (const value of answer.former) {
+      const f = value as { id?: unknown; name?: unknown; status?: unknown } | null;
+      if (!f || typeof f.id !== "string" || !memberIdPattern.test(f.id) || !(f.status === "former" ? f.name === undefined || text(f.name, 520) : f.status === "erased" && f.name === undefined)) throw new Unavailable();
+      keep(f.id, { former: { id: f.id, name: (f.name as string | undefined) ?? null, status: f.status as FormerMember["status"] } });
+      told.add(f.id);
+    }
+    for (const id of answer.unknown) {
+      if (typeof id !== "string" || !memberIdPattern.test(id)) throw new Unavailable();
+      keep(id, { unknown: true });
+      told.add(id);
+    }
+    if (batch.some(id => !told.has(id))) throw new Unavailable();
+  }
+  const result: Lookup = { members: [], former: [], unknown: [] };
+  for (const id of wanted) {
+    const k = known.get(id);
+    if (k && "member" in k) result.members.push(k.member);
+    else if (k && "former" in k) result.former.push(k.former);
+    else result.unknown.push(id);
+  }
+  return result;
+}
+
+// groups are the groups of the Chest that give the tool, each with the
+// identifiers of its members; nothing of the others.
+export const groups = {
+  async list(): Promise<Group[]> {
+    const response = await ask("members", "GET", "/groups");
+    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[] };
+    });
+  },
+};

package/client/src/notifications.ts

@@ -0,0 +1,148 @@
+import { ask as chest, json, refusal } from "./api.js";
+import { ChestError, Unavailable } from "./errors.js";
+import { 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).
+//
+//   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.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).
+
+// 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 };
+// 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[] };
+// A badge to set: a member and their count, 0 to clear it.
+export type BadgeCount = { memberId: string; count: number };
+// The members whose badge was set, and those skipped (no access), in the
+// 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;
+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.
+const removed = /[\p{Cc}\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+
+const ask = (method: string, path: string, value: unknown) => chest("notifications", method, path, { body: JSON.stringify(value), type: "application/json" });
+// expect lets through the one answer expected; a refusal is what the Chest
+// says, any other success is not the Chest's.
+async function expect(response: Response, status: number): Promise<void> {
+  if (response.status === status) return;
+  if (response.status < 400) {
+    await response.body?.cancel();
+    throw new Unavailable();
+  }
+  throw await refusal(response, "notifications");
+}
+const length = (s: string): number => [...s].length;
+
+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.
+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");
+  return all.map(checkId);
+}
+function checkKey(key: unknown): string {
+  if (typeof key !== "string" || !keyPattern.test(key)) throw new ChestError("invalid_key", 400, "a key is 1 to 64 of a-z 0-9 . _ : -");
+  return key;
+}
+function checkCount(count: unknown): number {
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 0 || count > maxCount) throw new ChestError("invalid_count", 400, "a count is 0 to 9999");
+  return count;
+}
+// checkPath accepts /chest, or /chest followed by '/', '?' or '#': printable
+// ASCII but '\', 512 bytes at most, never '//', no '.' or '..' segment
+// (written %2e either).
+function checkPath(path: unknown): string {
+  if (typeof path !== "string" || path.length > maxPath || !/^\/chest([/?#][\x21-\x5b\x5d-\x7e]*)?$/u.test(path) || path.includes("//") || path.split(/[?#]/u)[0]!.split("/").some(s => /^(\.|%2e){1,2}$/iu.test(s))) throw new ChestError("invalid_path", 400, "a path is /chest or under it");
+  return path;
+}
+
+// partition checks an answer that splits the identifiers asked, each once,
+// in their order, between two lists of it; anything else is not the Chest's.
+function partition(answer: unknown, first: string, second: string, asked: string[]): [string[], string[]] {
+  const a = answer !== null && typeof answer === "object" && !Array.isArray(answer) ? answer as Record<string, unknown> : null;
+  const lists = [a?.[first], a?.[second]];
+  if (!lists.every(l => Array.isArray(l) && l.every(id => typeof id === "string"))) throw new Unavailable();
+  const [one, two] = lists as [string[], string[]];
+  const wanted = [...new Set(asked)];
+  const inOrder = (l: string[]) => l.every((id, i) => wanted.indexOf(id) > (i === 0 ? -1 : wanted.indexOf(l[i - 1]!)));
+  if (one.length + two.length !== wanted.length || !inOrder(one) || !inOrder(two) || one.some(id => two.includes(id))) throw new Unavailable();
+  return [[...one], [...two]];
+}
+
+// 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.
+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);
+  await expect(response, 200);
+  const [delivered, skipped] = partition(await json(response), "delivered", "skipped", members);
+  return { delivered, skipped };
+}
+
+// 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
+// existed.
+export async function withdraw(key: string, memberIds?: Iterable<string>): Promise<void> {
+  const command = { key: checkKey(key), ...(memberIds !== undefined ? { members: checkIds(memberIds) } : {}) };
+  const response = await ask("POST", "/notifications/withdraw", command);
+  await expect(response, 204);
+}
+
+// badge sets the count shown on the tool's tile for a member (0 to 9,999; 0
+// clears it): a state, not an event, so setting it again changes nothing.
+export const badge = {
+  // set is true once the member's badge is set, false when they do not have
+  // the tool.
+  async set(memberId: string, count: number): Promise<boolean> {
+    checkId(memberId);
+    const response = await ask("PUT", "/badges/" + memberId, { count: checkCount(count) });
+    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.
+  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");
+    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) };
+    });
+    if (new Set(badges.map(b => b.member)).size !== badges.length) throw new ChestError("invalid_body", 400, "a member at most once");
+    const response = await ask("PUT", "/badges", { badges });
+    await expect(response, 200);
+    const [set, skipped] = partition(await json(response), "set", "skipped", badges.map(b => b.member));
+    return { set, skipped };
+  },
+};