@htilabs/platform-common-models 0.29.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,6 +16,19 @@
16
16
  * ObjectId filter for `users._id`; the reader passes a {@link SeatResolver}
17
17
  * that reads its own `users`. The partner rollup REQUIRES one, so a reader
18
18
  * cannot silently drop seat-linked referral contacts.
19
+ *
20
+ * ## Confidential Referrals (magic link) holders (pl-iza, 0.32.0)
21
+ *
22
+ * A confidential holder still receives the magic link; the sender never sees
23
+ * the address (CVC-338, prototype `data/cvcs/core_contact_purpose.yaml` @
24
+ * 184893b6 L95; HANDOFF.md @ 184893b6 L569, L575 "POC-PROFILE-ALIGNMENTS"
25
+ * D(ii)). Confidential rows are absent from every view another organization
26
+ * sees (only the owner and steward reads carry them). The referral rollup
27
+ * reads them in a SEPARATE query and hands out only a count
28
+ * (`confidentialCount`) or, to a send, a {@link ConfidentialReferralRecipients}
29
+ * whose `deliver` alone touches the addresses (the implementation is not
30
+ * exported). A confidential row never reaches `unreachable`, and a corrupt
31
+ * row that may be confidential is counted, never thrown.
19
32
  */
20
33
 
21
34
  import { POINTS_OF_CONTACT_COLLECTION, type PointOfContactDoc } from "./schemas.js";
@@ -48,21 +61,21 @@ export type SeatResolver = (userIds: readonly string[]) => Promise<ReadonlyMap<s
48
61
 
49
62
  /**
50
63
  * A subject, always read together with its agency where ids can collide.
51
- * Program, team and site ids can be slugs two agencies share, so their reads
64
+ * Program, team and location ids can be slugs two agencies share, so their reads
52
65
  * REQUIRE `agency_id`. A service listing's contact names `agency_id` too:
53
66
  * the listing org's genuine-mirror agency, or `null` for an org-only partner.
54
67
  * Only agency and org subjects (whose ids are themselves unique) may omit it.
55
68
  */
56
69
  export type PocSubjectRef =
57
70
  | { subject_type: "agency" | "org"; subject_id: string; agency_id?: string | null }
58
- | { subject_type: "program" | "team" | "site"; subject_id: string; agency_id: string }
71
+ | { subject_type: "program" | "team" | "location"; subject_id: string; agency_id: string }
59
72
  | { subject_type: "service"; subject_id: string; agency_id: string | null };
60
73
 
61
74
  function subjectFilter(subject: PocSubjectRef): Record<string, unknown> {
62
75
  const type = requireId("subject_type", subject.subject_type) as PocSubjectType;
63
76
  const base = { subject_type: type, subject_id: requireId("subject_id", subject.subject_id) };
64
77
  const agency = subject.agency_id;
65
- if (type === "program" || type === "team" || type === "site") {
78
+ if (type === "program" || type === "team" || type === "location") {
66
79
  return { ...base, agency_id: requireId("agency_id", agency) };
67
80
  }
68
81
  if (type === "service" && agency === undefined) {
@@ -141,29 +154,48 @@ export async function listContactsForSubject(
141
154
  return networkViews(docs, await seatsFor(docs, opts.resolveSeats));
142
155
  }
143
156
 
144
- /** A referral recipient: a network-visible contact with a resolved email. */
145
- export type ReferralRecipient = PointOfContactNetworkView & { email: string };
157
+ /**
158
+ * A referral recipient: a network-visible contact with a resolved email, or
159
+ * (only when asked, {@link ReferralContactsOptions.includeOwnPendingFor}) the
160
+ * asking advocate's OWN pending in-app add, marked `pending: true` so a UI can
161
+ * label it.
162
+ */
163
+ export type ReferralRecipient = PointOfContactNetworkView & { email: string; pending?: true };
164
+
165
+ export interface ReferralContactsOptions {
166
+ resolveSeats: SeatResolver;
167
+ /**
168
+ * The asking advocate's Auth0 `sub`, taken server-side from the verified
169
+ * token (the same pinning as `mintPartnerContact`'s `actor.id`). When set,
170
+ * the advocate's OWN pending in-app adds on the partner (`status: pending`,
171
+ * active, `origin: in_app`, `createdBy` = this sub, tagged Referrals (magic
172
+ * link), not confidential) are returned too, after the confirmed recipients
173
+ * and marked `pending: true`. Nobody else's pending add is ever returned.
174
+ */
175
+ includeOwnPendingFor?: string;
176
+ }
146
177
 
147
178
  export interface ReferralContactsResult {
148
179
  /** One per distinct email, in reading order (the agency's own contacts first). */
149
180
  recipients: ReferralRecipient[];
150
- /** Ids of tagged, visible contacts with no email to send to (a seat whose `users` row has none). */
181
+ /**
182
+ * Ids of tagged, VISIBLE contacts with no email to send to (a seat whose
183
+ * `users` row has none). Never a confidential holder's id.
184
+ */
151
185
  unreachable: string[];
186
+ /**
187
+ * The number of distinct confidential Referrals (magic link) holder
188
+ * addresses (pl-iza): active, confirmed, `is_confidential`, tagged, on the
189
+ * same rollup. Deduped among the confidential holders ONLY, never against
190
+ * any visible, pending, typed or added address, so no other row or input
191
+ * moves it. A sender sees this number, never a name, an id or an address
192
+ * ("+ 1 confidential recipient").
193
+ */
194
+ confidentialCount: number;
152
195
  }
153
196
 
154
- /**
155
- * The partner's Referrals (magic link) contacts: every active, confirmed,
156
- * non-confidential contact tagged `REFERRALS_MAGIC_LINK` on the partner's
157
- * agency AND on its programs, teams and sites (the rollup, via the row's
158
- * `agency_id`), and on its organization (via `org_id`). A magic link goes to
159
- * every one of them (Crysta 2026-08-23, restated 2026-10-14). The same email
160
- * tagged on two subjects is one recipient.
161
- */
162
- export async function listReferralContactsForPartner(
163
- db: PocDbLike,
164
- partner: PocPartnerSelector,
165
- opts: { resolveSeats: SeatResolver },
166
- ): Promise<ReferralContactsResult> {
197
+ /** The partner rollup keys: its agency, its organization, or both. */
198
+ function partnerKeys(partner: PocPartnerSelector): Record<string, string>[] {
167
199
  const keys: Record<string, string>[] = [];
168
200
  if (partner.agency_id !== undefined && partner.agency_id !== null) {
169
201
  keys.push({ agency_id: requireId("agency_id", partner.agency_id) });
@@ -172,17 +204,99 @@ export async function listReferralContactsForPartner(
172
204
  keys.push({ org_id: requireId("org_id", partner.org_id) });
173
205
  }
174
206
  if (keys.length === 0) throw new TypeError("points-of-contact: select a partner by agency_id, org_id or both");
175
- const docs = await findDocs(db, {
176
- $or: keys,
177
- purposes: REFERRALS_MAGIC_LINK_PURPOSE,
178
- ...NETWORK_VISIBLE,
179
- });
180
- const views = networkViews(docs, await seatsFor(docs, opts.resolveSeats));
207
+ return keys;
208
+ }
209
+
210
+ /** The two public referral reads' shared result: confidential addresses stay inside this module. */
211
+ interface ReferralHolders {
212
+ recipients: ReferralRecipient[];
213
+ unreachable: string[];
214
+ confidentialAddresses: string[];
215
+ confidentialUnreachableCount: number;
216
+ }
217
+
218
+ /** A raw row that may be confidential: its stored flag is anything but `false` or absent. */
219
+ const mayBeConfidential = (raw: Record<string, unknown>) =>
220
+ raw.is_confidential !== false && raw.is_confidential !== undefined;
221
+
222
+ /**
223
+ * A referral leg's rows. A row that does not match the contract and MAY be
224
+ * confidential is skipped and counted, not thrown: a
225
+ * `PointOfContactShapeError` names the row's id, and an app's error handler
226
+ * can return an error message to the browser. Nothing is logged. In the
227
+ * confidential leg every such row may be; in the visible and pending legs it
228
+ * is one whose stored `is_confidential` is malformed (`"true"`, `1`, `null`:
229
+ * it matches `{ $ne: true }`). Any other corrupt row still throws, as
230
+ * {@link findDocs} does.
231
+ */
232
+ async function findHolderDocs(
233
+ db: PocDbLike,
234
+ filter: Record<string, unknown>,
235
+ confidentialLeg: boolean,
236
+ ): Promise<{ docs: PointOfContactDoc[]; skipped: number }> {
237
+ const raw = await db.collection(POINTS_OF_CONTACT_COLLECTION).find(filter).toArray();
238
+ const docs: PointOfContactDoc[] = [];
239
+ let skipped = 0;
240
+ for (const r of raw) {
241
+ const row = rowOf(r);
242
+ try {
243
+ docs.push(normalizePointOfContact(row));
244
+ } catch (err) {
245
+ if (!confidentialLeg && !mayBeConfidential(row)) throw err;
246
+ skipped++;
247
+ }
248
+ }
249
+ return { docs: docs.sort(byContactReadingOrder), skipped };
250
+ }
251
+
252
+ /**
253
+ * The partner's Referrals (magic link) holders, read once for both public
254
+ * reads. Three queries on the same rollup keys, in this order: the visible
255
+ * confirmed holders, the asking advocate's own pending adds (only when asked),
256
+ * and (pl-iza) the confidential confirmed holders. The first two are the
257
+ * pre-0.32.0 queries, unchanged. Seats are resolved ONCE, over the visible and
258
+ * confidential rows together (pending in-app adds are never seat-linked).
259
+ */
260
+ async function readReferralHolders(
261
+ db: PocDbLike,
262
+ partner: PocPartnerSelector,
263
+ opts: ReferralContactsOptions,
264
+ ): Promise<ReferralHolders> {
265
+ const keys = partnerKeys(partner);
266
+ const pendingFor =
267
+ opts.includeOwnPendingFor === undefined
268
+ ? null
269
+ : requireId("includeOwnPendingFor", opts.includeOwnPendingFor);
270
+ const visible = await findHolderDocs(
271
+ db,
272
+ { $or: keys, purposes: REFERRALS_MAGIC_LINK_PURPOSE, ...NETWORK_VISIBLE },
273
+ false,
274
+ );
275
+ const pending =
276
+ pendingFor === null
277
+ ? { docs: [], skipped: 0 }
278
+ : await findHolderDocs(
279
+ db,
280
+ {
281
+ $or: keys,
282
+ purposes: REFERRALS_MAGIC_LINK_PURPOSE,
283
+ ...OWN_PENDING_IN_APP,
284
+ createdBy: pendingFor,
285
+ },
286
+ false,
287
+ );
288
+ const confidential = await findHolderDocs(
289
+ db,
290
+ { $or: keys, purposes: REFERRALS_MAGIC_LINK_PURPOSE, ...CONFIDENTIAL_CONFIRMED },
291
+ true,
292
+ );
293
+ const docs = visible.docs;
294
+ const seats = await seatsFor([...docs, ...confidential.docs], opts.resolveSeats);
181
295
 
182
296
  const recipients: ReferralRecipient[] = [];
183
297
  const unreachable: string[] = [];
184
298
  const seen = new Set<string>();
185
- for (const v of views) {
299
+ for (const v of networkViews(docs, seats)) {
186
300
  if (!v.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE)) continue;
187
301
  const email = v.email;
188
302
  if (!email) {
@@ -193,9 +307,277 @@ export async function listReferralContactsForPartner(
193
307
  seen.add(email);
194
308
  recipients.push({ ...v, email });
195
309
  }
196
- return { recipients, unreachable };
310
+ if (pendingFor !== null) {
311
+ for (const d of pending.docs) {
312
+ // The same filter again, on the parsed row: a reader never widens it.
313
+ if (!isOwnPendingInApp(d, pendingFor)) continue;
314
+ // An in-app add is a write-in (never seat-linked): its view is its own row's,
315
+ // drawn as the network view would draw it once confirmed.
316
+ const v = toNetworkView({ ...d, status: "confirmed" });
317
+ const email = v?.email;
318
+ if (!v || !email || seen.has(email)) continue;
319
+ seen.add(email);
320
+ recipients.push({ ...v, email, pending: true });
321
+ }
322
+ }
323
+
324
+ // pl-iza: confidential holders still receive the link; the sender never sees
325
+ // the address. Deduped among THEMSELVES only, never against a visible,
326
+ // pending, typed or added address: any of those can change under the
327
+ // advocate's eye (their add confirmed by a steward, a seat's email edited,
328
+ // their own typing), and a count that dropped when one matched would tell
329
+ // them a confidential holder's address. An overlap is simply sent twice.
330
+ const confidentialAddresses: string[] = [];
331
+ const confidentialSeen = new Set<string>();
332
+ let confidentialUnreachableCount = visible.skipped + pending.skipped + confidential.skipped;
333
+ for (const d of confidential.docs) {
334
+ // The same filter again, on the parsed row.
335
+ if (!isConfidentialHolder(d)) continue;
336
+ // The steward view's `email` is the reachable preferred address (the
337
+ // seat's for a seat-linked row), drawn as the network view draws it.
338
+ const email = toStewardView(d, seatOf(d, seats)).email;
339
+ if (!email) {
340
+ confidentialUnreachableCount++;
341
+ continue;
342
+ }
343
+ if (confidentialSeen.has(email)) continue;
344
+ confidentialSeen.add(email);
345
+ confidentialAddresses.push(email);
346
+ }
347
+ return { recipients, unreachable, confidentialAddresses, confidentialUnreachableCount };
197
348
  }
198
349
 
350
+ /**
351
+ * The partner's Referrals (magic link) contacts: every active, confirmed,
352
+ * non-confidential contact tagged `REFERRALS_MAGIC_LINK` on the partner's
353
+ * agency AND on its programs, teams and locations (the rollup, via the row's
354
+ * `agency_id`), and on its organization (via `org_id`). A magic link goes to
355
+ * every one of them (Crysta 2026-08-23, restated 2026-10-14), at its PREFERRED
356
+ * email (pl-e98; the view's `email`). The same email tagged on two subjects is
357
+ * one recipient.
358
+ *
359
+ * With `includeOwnPendingFor` (Nate 2026-10-15), the advocate also sees their
360
+ * own pending in-app adds on the partner, so a contact they just added can be
361
+ * picked before HTI Labs confirms it (pending, marked, after the confirmed
362
+ * recipients; an email a confirmed recipient already has is not repeated).
363
+ * Confidential rows stay out of `recipients` and `unreachable`; they are
364
+ * counted (`confidentialCount`, pl-iza) and reached only through
365
+ * {@link resolveMagicLinkRecipients}. The partner has a
366
+ * magic-link holder when `recipients.length + confidentialCount > 0`.
367
+ */
368
+ export async function listReferralContactsForPartner(
369
+ db: PocDbLike,
370
+ partner: PocPartnerSelector,
371
+ opts: ReferralContactsOptions,
372
+ ): Promise<ReferralContactsResult> {
373
+ const holders = await readReferralHolders(db, partner, opts);
374
+ return {
375
+ recipients: holders.recipients,
376
+ unreachable: holders.unreachable,
377
+ confidentialCount: holders.confidentialAddresses.length,
378
+ };
379
+ }
380
+
381
+ /** What a send needs: the visible recipients, plus the confidential holders behind a count. */
382
+ export interface MagicLinkSendList {
383
+ /** As {@link ReferralContactsResult.recipients}. */
384
+ recipients: ReferralRecipient[];
385
+ /** As {@link ReferralContactsResult.unreachable}: visible contacts only. */
386
+ unreachable: string[];
387
+ /** The confidential holders: a count, and a `deliver` that alone touches their addresses. */
388
+ confidential: ConfidentialReferralRecipients;
389
+ /**
390
+ * SERVER-SIDE diagnostic, never returned to a sender: the confidential
391
+ * holder rows that cannot be sent to (no email, a seat with none or not
392
+ * found), plus skipped rows that do not match the contract and may be
393
+ * confidential (their error would name their id). A count, never an id.
394
+ */
395
+ confidentialUnreachableCount: number;
396
+ }
397
+
398
+ /**
399
+ * SEND-ONLY (pl-iza). The same read as {@link listReferralContactsForPartner},
400
+ * with the confidential holders as a {@link ConfidentialReferralRecipients}
401
+ * instead of a bare count. Call it at send time, server-side, and hand
402
+ * `confidential.deliver` the mailer; never return the result to a browser
403
+ * beyond `confidential.count` (its `toJSON` is `{ count }`). This is the only
404
+ * way to obtain a `ConfidentialReferralRecipients` (the implementation is
405
+ * not exported).
406
+ *
407
+ * Canon: CVC-338 `REFERRALS_MAGIC_LINK` (prototype
408
+ * `data/cvcs/core_contact_purpose.yaml` @ 184893b6 L95): "A confidential
409
+ * holder still receives it; the sender never sees the address."
410
+ */
411
+ export async function resolveMagicLinkRecipients(
412
+ db: PocDbLike,
413
+ partner: PocPartnerSelector,
414
+ opts: ReferralContactsOptions,
415
+ ): Promise<MagicLinkSendList> {
416
+ const holders = await readReferralHolders(db, partner, opts);
417
+ return {
418
+ recipients: holders.recipients,
419
+ unreachable: holders.unreachable,
420
+ confidential: new ConfidentialHolders(holders.confidentialAddresses),
421
+ confidentialUnreachableCount: holders.confidentialUnreachableCount,
422
+ };
423
+ }
424
+
425
+ /**
426
+ * Sends one magic link to one address. It must THROW (or reject) on failure;
427
+ * returning normally counts as delivered. It must not log, persist or return
428
+ * `address`.
429
+ */
430
+ export type ConfidentialSendOne = (address: string) => void | Promise<void>;
431
+
432
+ export interface ConfidentialDeliverOptions {
433
+ /** At most this many sends (a non-negative integer); the rest are `overflow`. Unlimited when omitted. */
434
+ capacity?: number;
435
+ }
436
+
437
+ /**
438
+ * A confidential delivery's outcome: numbers and an error class name, never an
439
+ * address. SERVER-SIDE, for audit only: a sender may see `count`, or one
440
+ * all-or-nothing status derived from it, never `delivered`, `failed`,
441
+ * `overflow` or `firstErrorName`.
442
+ */
443
+ export interface ConfidentialDeliveryResult {
444
+ /** The holder count (`delivered + failed + overflow`). */
445
+ count: number;
446
+ delivered: number;
447
+ failed: number;
448
+ /** Holders beyond `capacity`, not sent: `max(0, count - capacity)`. */
449
+ overflow: number;
450
+ /** The first failed send's `err.name` (never its message, which can echo the address), or null. */
451
+ firstErrorName: string | null;
452
+ }
453
+
454
+ const SAFE_ERROR_NAME = /^[A-Za-z_$][\w$.-]{0,63}$/;
455
+
456
+ /**
457
+ * An error's class name only. Anything that is not a plain identifier, or a
458
+ * `name` that cannot be read (a throwing getter, a revoked proxy), reads "Error".
459
+ */
460
+ function errorName(err: unknown): string {
461
+ try {
462
+ if (err === null || (typeof err !== "object" && typeof err !== "function")) return "Error";
463
+ const name: unknown = (err as { name?: unknown }).name;
464
+ return typeof name === "string" && SAFE_ERROR_NAME.test(name) ? name : "Error";
465
+ } catch {
466
+ return "Error";
467
+ }
468
+ }
469
+
470
+ /**
471
+ * A partner's confidential Referrals (magic link) holders (pl-iza). It carries
472
+ * their addresses privately and exposes only `count`: `toJSON()` is
473
+ * `{ count }`, `util.inspect` draws `ConfidentialReferralRecipients(n)`, and
474
+ * no public member returns an address. Only {@link deliver} touches them,
475
+ * handing each to the caller's `sendOne`.
476
+ *
477
+ * An interface, exported as a type only. The implementation is not
478
+ * exported: obtain values only via {@link resolveMagicLinkRecipients}.
479
+ */
480
+ export interface ConfidentialReferralRecipients {
481
+ readonly count: number;
482
+ /**
483
+ * Sends to the first `capacity` holders (all when omitted), one at a time.
484
+ * The outcome depends only on the holders, `capacity` and each send's
485
+ * result, never on any address the caller handled: an address the sender
486
+ * also typed is sent again, so nothing observable moves when one matches.
487
+ * Never rejects for a failed send: each error is caught and only its `name`
488
+ * is kept (a provider's message can echo the address). The result is
489
+ * server-side only (see {@link ConfidentialDeliveryResult}).
490
+ */
491
+ deliver(
492
+ sendOne: ConfidentialSendOne,
493
+ opts?: ConfidentialDeliverOptions,
494
+ ): Promise<ConfidentialDeliveryResult>;
495
+ /** `{ count }`: what a response, a record or an event may carry. */
496
+ toJSON(): { count: number };
497
+ /** `ConfidentialReferralRecipients(n)`. */
498
+ toString(): string;
499
+ }
500
+
501
+ /** The one implementation (not exported). */
502
+ class ConfidentialHolders implements ConfidentialReferralRecipients {
503
+ readonly count: number;
504
+ readonly #addresses: readonly string[];
505
+
506
+ constructor(addresses: readonly string[]) {
507
+ this.#addresses = Object.freeze([...addresses]);
508
+ this.count = this.#addresses.length;
509
+ Object.freeze(this);
510
+ }
511
+
512
+ /** See {@link ConfidentialReferralRecipients.deliver}. */
513
+ async deliver(
514
+ sendOne: ConfidentialSendOne,
515
+ opts: ConfidentialDeliverOptions = {},
516
+ ): Promise<ConfidentialDeliveryResult> {
517
+ const { capacity } = opts;
518
+ if (capacity !== undefined && !(Number.isInteger(capacity) && capacity >= 0)) {
519
+ throw new TypeError("points-of-contact: capacity must be a non-negative integer");
520
+ }
521
+ const toSend = capacity === undefined ? this.#addresses : this.#addresses.slice(0, capacity);
522
+ const out: ConfidentialDeliveryResult = {
523
+ count: this.count,
524
+ delivered: 0,
525
+ failed: 0,
526
+ overflow: this.count - toSend.length,
527
+ firstErrorName: null,
528
+ };
529
+ for (const address of toSend) {
530
+ try {
531
+ await sendOne(address);
532
+ out.delivered++;
533
+ } catch (err) {
534
+ out.failed++;
535
+ out.firstErrorName ??= errorName(err);
536
+ }
537
+ }
538
+ return out;
539
+ }
540
+
541
+ /** `{ count }`: what a response, a record or an event may carry. */
542
+ toJSON(): { count: number } {
543
+ return { count: this.count };
544
+ }
545
+
546
+ toString(): string {
547
+ return `ConfidentialReferralRecipients(${this.count})`;
548
+ }
549
+
550
+ [Symbol.for("nodejs.util.inspect.custom")](): string {
551
+ return this.toString();
552
+ }
553
+ }
554
+
555
+ /** An outstanding in-app add, visible to its own adder only (and never when confidential). */
556
+ const OWN_PENDING_IN_APP = {
557
+ active: true,
558
+ status: "pending",
559
+ origin: "in_app",
560
+ is_confidential: { $ne: true },
561
+ } as const;
562
+
563
+ const isOwnPendingInApp = (d: PointOfContactDoc, sub: string) =>
564
+ d.active &&
565
+ d.status === "pending" &&
566
+ d.origin === "in_app" &&
567
+ !d.is_confidential &&
568
+ !d.user_id &&
569
+ d.createdBy === sub &&
570
+ d.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE);
571
+
572
+ /** A confidential holder that receives magic links (pl-iza): active, confirmed, confidential. */
573
+ const CONFIDENTIAL_CONFIRMED = { active: true, status: "confirmed", is_confidential: true } as const;
574
+
575
+ const isConfidentialHolder = (d: PointOfContactDoc) =>
576
+ d.active &&
577
+ d.status === "confirmed" &&
578
+ d.is_confidential &&
579
+ d.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE);
580
+
199
581
  /** One contact as other organizations see it, or null (absent or not network-visible). */
200
582
  export async function getContact(
201
583
  db: PocDbLike,