@htilabs/platform-common-models 0.30.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.
- package/README.md +107 -1
- package/dist/{index-Pt82NxQg.d.cts → index-BTqHP4DM.d.cts} +1 -1
- package/dist/{index-ClTjjJ_S.d.ts → index-Dr6GBCoY.d.ts} +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/points-of-contact/index.cjs +135 -16
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.d.cts +128 -5
- package/dist/points-of-contact/index.d.ts +128 -5
- package/dist/points-of-contact/index.js +134 -16
- package/dist/points-of-contact/index.js.map +1 -1
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/package.json +1 -1
- package/src/pointsOfContact/__tests__/pointsOfContact.test.ts +447 -0
- package/src/pointsOfContact/__tests__/reader.mongo.test.ts +211 -0
- package/src/pointsOfContact/index.ts +3 -1
- package/src/pointsOfContact/readRules.ts +8 -1
- package/src/pointsOfContact/reader.ts +353 -37
- package/src/pointsOfContact/vocabulary.ts +4 -1
- package/dist/{cvcEntry-Asg7mxjB.d.cts → cvcEntry-BqAGctqK.d.cts} +8 -8
- package/dist/{cvcEntry-Asg7mxjB.d.ts → cvcEntry-BqAGctqK.d.ts} +8 -8
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
* The Point of contact contract (pl-3r8): the platform-db `pointsofcontact`
|
|
5
5
|
* collection's vocabularies, Zod schemas, stored and view types, read rules
|
|
6
6
|
* (network vs owner view, confidential exclusion, the Referrals (magic link)
|
|
7
|
-
* partner rollup
|
|
7
|
+
* partner rollup with its confidential-holder count and send-only
|
|
8
|
+
* `resolveMagicLinkRecipients` / `ConfidentialReferralRecipients`, pl-iza)
|
|
9
|
+
* and raw-driver reads, plus the ONE shared writer every app
|
|
8
10
|
* runs: the in-app partner add (`mintPartnerContact`, pl-bt1) and the index
|
|
9
11
|
* set it relies on (`ensurePocIndexes`). Pure TypeScript, no mongoose, no
|
|
10
12
|
* driver import. The platform app owns every other write (its own Admin Hub,
|
|
@@ -15,7 +15,14 @@
|
|
|
15
15
|
* `Org + Personnel Registry/DIRECTORY_CSV_EDITING_GUIDE.md` @ 6c2db859
|
|
16
16
|
* § 0.9 L958; hti-features `PointOfContact.v1.json` `is_confidential`:
|
|
17
17
|
* "Never publish this contact"), so it is left out entirely rather
|
|
18
|
-
* than masked
|
|
18
|
+
* than masked. The network view is unchanged by pl-iza (0.32.0):
|
|
19
|
+
* confidential rows are absent from every view another organization
|
|
20
|
+
* sees (this view, `getContact`, `listContactsForSubject`, the
|
|
21
|
+
* referral `recipients`; only the subject's owner and the steward see
|
|
22
|
+
* them). A confidential Referrals (magic link) holder still receives
|
|
23
|
+
* the magic link, but only through the send-only
|
|
24
|
+
* `resolveMagicLinkRecipients` (`./reader.ts`), which never projects
|
|
25
|
+
* the row and exposes a count;
|
|
19
26
|
* - the seat / person links, `notes`, review stamps, actor ids and the
|
|
20
27
|
* identity key are not projected.
|
|
21
28
|
* - **Owner view** ({@link toOwnerView}): the subject's own editor (Admin
|
|
@@ -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";
|
|
@@ -165,30 +178,24 @@ export interface ReferralContactsOptions {
|
|
|
165
178
|
export interface ReferralContactsResult {
|
|
166
179
|
/** One per distinct email, in reading order (the agency's own contacts first). */
|
|
167
180
|
recipients: ReferralRecipient[];
|
|
168
|
-
/**
|
|
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
|
+
*/
|
|
169
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;
|
|
170
195
|
}
|
|
171
196
|
|
|
172
|
-
/**
|
|
173
|
-
|
|
174
|
-
* non-confidential contact tagged `REFERRALS_MAGIC_LINK` on the partner's
|
|
175
|
-
* agency AND on its programs, teams and locations (the rollup, via the row's
|
|
176
|
-
* `agency_id`), and on its organization (via `org_id`). A magic link goes to
|
|
177
|
-
* every one of them (Crysta 2026-08-23, restated 2026-10-14), at its PREFERRED
|
|
178
|
-
* email (pl-e98; the view's `email`). The same email tagged on two subjects is
|
|
179
|
-
* one recipient.
|
|
180
|
-
*
|
|
181
|
-
* With `includeOwnPendingFor` (Nate 2026-10-15), the advocate also sees their
|
|
182
|
-
* own pending in-app adds on the partner, so a contact they just added can be
|
|
183
|
-
* picked before HTI Labs confirms it (pending, marked, after the confirmed
|
|
184
|
-
* recipients; an email a confirmed recipient already has is not repeated).
|
|
185
|
-
* Confidential rows stay excluded.
|
|
186
|
-
*/
|
|
187
|
-
export async function listReferralContactsForPartner(
|
|
188
|
-
db: PocDbLike,
|
|
189
|
-
partner: PocPartnerSelector,
|
|
190
|
-
opts: ReferralContactsOptions,
|
|
191
|
-
): Promise<ReferralContactsResult> {
|
|
197
|
+
/** The partner rollup keys: its agency, its organization, or both. */
|
|
198
|
+
function partnerKeys(partner: PocPartnerSelector): Record<string, string>[] {
|
|
192
199
|
const keys: Record<string, string>[] = [];
|
|
193
200
|
if (partner.agency_id !== undefined && partner.agency_id !== null) {
|
|
194
201
|
keys.push({ agency_id: requireId("agency_id", partner.agency_id) });
|
|
@@ -197,21 +204,99 @@ export async function listReferralContactsForPartner(
|
|
|
197
204
|
keys.push({ org_id: requireId("org_id", partner.org_id) });
|
|
198
205
|
}
|
|
199
206
|
if (keys.length === 0) throw new TypeError("points-of-contact: select a partner by agency_id, org_id or both");
|
|
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);
|
|
200
266
|
const pendingFor =
|
|
201
267
|
opts.includeOwnPendingFor === undefined
|
|
202
268
|
? null
|
|
203
269
|
: requireId("includeOwnPendingFor", opts.includeOwnPendingFor);
|
|
204
|
-
const
|
|
205
|
-
|
|
206
|
-
purposes: REFERRALS_MAGIC_LINK_PURPOSE,
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
const
|
|
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);
|
|
210
295
|
|
|
211
296
|
const recipients: ReferralRecipient[] = [];
|
|
212
297
|
const unreachable: string[] = [];
|
|
213
298
|
const seen = new Set<string>();
|
|
214
|
-
for (const v of
|
|
299
|
+
for (const v of networkViews(docs, seats)) {
|
|
215
300
|
if (!v.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE)) continue;
|
|
216
301
|
const email = v.email;
|
|
217
302
|
if (!email) {
|
|
@@ -222,15 +307,8 @@ export async function listReferralContactsForPartner(
|
|
|
222
307
|
seen.add(email);
|
|
223
308
|
recipients.push({ ...v, email });
|
|
224
309
|
}
|
|
225
|
-
|
|
226
310
|
if (pendingFor !== null) {
|
|
227
|
-
const
|
|
228
|
-
$or: keys,
|
|
229
|
-
purposes: REFERRALS_MAGIC_LINK_PURPOSE,
|
|
230
|
-
...OWN_PENDING_IN_APP,
|
|
231
|
-
createdBy: pendingFor,
|
|
232
|
-
});
|
|
233
|
-
for (const d of pending) {
|
|
311
|
+
for (const d of pending.docs) {
|
|
234
312
|
// The same filter again, on the parsed row: a reader never widens it.
|
|
235
313
|
if (!isOwnPendingInApp(d, pendingFor)) continue;
|
|
236
314
|
// An in-app add is a write-in (never seat-linked): its view is its own row's,
|
|
@@ -242,7 +320,236 @@ export async function listReferralContactsForPartner(
|
|
|
242
320
|
recipients.push({ ...v, email, pending: true });
|
|
243
321
|
}
|
|
244
322
|
}
|
|
245
|
-
|
|
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 };
|
|
348
|
+
}
|
|
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
|
+
}
|
|
246
553
|
}
|
|
247
554
|
|
|
248
555
|
/** An outstanding in-app add, visible to its own adder only (and never when confidential). */
|
|
@@ -262,6 +569,15 @@ const isOwnPendingInApp = (d: PointOfContactDoc, sub: string) =>
|
|
|
262
569
|
d.createdBy === sub &&
|
|
263
570
|
d.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE);
|
|
264
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
|
+
|
|
265
581
|
/** One contact as other organizations see it, or null (absent or not network-visible). */
|
|
266
582
|
export async function getContact(
|
|
267
583
|
db: PocDbLike,
|
|
@@ -137,7 +137,10 @@ export const CONTACT_PURPOSES: readonly ContactPurpose[] = [
|
|
|
137
137
|
/**
|
|
138
138
|
* The magic-link purpose. A magic link goes to EVERY contact on the partner
|
|
139
139
|
* carrying it (Crysta 2026-08-23, restated 2026-10-14), and a contact carrying
|
|
140
|
-
* it must have an email (Crysta 2026-10-14, the Admin Hub editor rule).
|
|
140
|
+
* it must have an email (Crysta 2026-10-14, the Admin Hub editor rule). CVC-338
|
|
141
|
+
* (prototype `data/cvcs/core_contact_purpose.yaml` @ 184893b6 L95): "A
|
|
142
|
+
* confidential holder still receives it; the sender never sees the address."
|
|
143
|
+
* (pl-iza: `resolveMagicLinkRecipients`, `ConfidentialReferralRecipients`.)
|
|
141
144
|
*/
|
|
142
145
|
export const REFERRALS_MAGIC_LINK_PURPOSE: ContactPurposeCode = "REFERRALS_MAGIC_LINK";
|
|
143
146
|
|
|
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
|
|
|
233
233
|
declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
|
|
234
234
|
_id: false;
|
|
235
235
|
}, {
|
|
236
|
-
text: string;
|
|
237
236
|
type: "tip" | "warning" | "prompt";
|
|
238
|
-
}, mongoose.Document<unknown, {}, {
|
|
239
237
|
text: string;
|
|
238
|
+
}, mongoose.Document<unknown, {}, {
|
|
240
239
|
type: "tip" | "warning" | "prompt";
|
|
240
|
+
text: string;
|
|
241
241
|
}, {
|
|
242
242
|
id: string;
|
|
243
243
|
}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
|
|
244
244
|
_id: false;
|
|
245
245
|
}> & Omit<{
|
|
246
|
-
text: string;
|
|
247
246
|
type: "tip" | "warning" | "prompt";
|
|
247
|
+
text: string;
|
|
248
248
|
} & {
|
|
249
249
|
_id: mongoose.Types.ObjectId;
|
|
250
250
|
} & {
|
|
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
|
|
|
252
252
|
}, "id"> & {
|
|
253
253
|
id: string;
|
|
254
254
|
}, unknown, {
|
|
255
|
-
text: string;
|
|
256
255
|
type: "tip" | "warning" | "prompt";
|
|
256
|
+
text: string;
|
|
257
257
|
} & {
|
|
258
258
|
_id: mongoose.Types.ObjectId;
|
|
259
259
|
} & {
|
|
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
|
|
|
294
294
|
type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
|
|
295
295
|
_id: false;
|
|
296
296
|
}, {
|
|
297
|
-
text: string;
|
|
298
297
|
type: "tip" | "warning" | "prompt";
|
|
299
|
-
}, mongoose.Document<unknown, {}, {
|
|
300
298
|
text: string;
|
|
299
|
+
}, mongoose.Document<unknown, {}, {
|
|
301
300
|
type: "tip" | "warning" | "prompt";
|
|
301
|
+
text: string;
|
|
302
302
|
}, {
|
|
303
303
|
id: string;
|
|
304
304
|
}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
|
|
305
305
|
_id: false;
|
|
306
306
|
}> & Omit<{
|
|
307
|
-
text: string;
|
|
308
307
|
type: "tip" | "warning" | "prompt";
|
|
308
|
+
text: string;
|
|
309
309
|
} & {
|
|
310
310
|
_id: mongoose.Types.ObjectId;
|
|
311
311
|
} & {
|
|
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
|
|
|
313
313
|
}, "id"> & {
|
|
314
314
|
id: string;
|
|
315
315
|
}, unknown, {
|
|
316
|
-
text: string;
|
|
317
316
|
type: "tip" | "warning" | "prompt";
|
|
317
|
+
text: string;
|
|
318
318
|
} & {
|
|
319
319
|
_id: mongoose.Types.ObjectId;
|
|
320
320
|
} & {
|
|
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
|
|
|
233
233
|
declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
|
|
234
234
|
_id: false;
|
|
235
235
|
}, {
|
|
236
|
-
text: string;
|
|
237
236
|
type: "tip" | "warning" | "prompt";
|
|
238
|
-
}, mongoose.Document<unknown, {}, {
|
|
239
237
|
text: string;
|
|
238
|
+
}, mongoose.Document<unknown, {}, {
|
|
240
239
|
type: "tip" | "warning" | "prompt";
|
|
240
|
+
text: string;
|
|
241
241
|
}, {
|
|
242
242
|
id: string;
|
|
243
243
|
}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
|
|
244
244
|
_id: false;
|
|
245
245
|
}> & Omit<{
|
|
246
|
-
text: string;
|
|
247
246
|
type: "tip" | "warning" | "prompt";
|
|
247
|
+
text: string;
|
|
248
248
|
} & {
|
|
249
249
|
_id: mongoose.Types.ObjectId;
|
|
250
250
|
} & {
|
|
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
|
|
|
252
252
|
}, "id"> & {
|
|
253
253
|
id: string;
|
|
254
254
|
}, unknown, {
|
|
255
|
-
text: string;
|
|
256
255
|
type: "tip" | "warning" | "prompt";
|
|
256
|
+
text: string;
|
|
257
257
|
} & {
|
|
258
258
|
_id: mongoose.Types.ObjectId;
|
|
259
259
|
} & {
|
|
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
|
|
|
294
294
|
type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
|
|
295
295
|
_id: false;
|
|
296
296
|
}, {
|
|
297
|
-
text: string;
|
|
298
297
|
type: "tip" | "warning" | "prompt";
|
|
299
|
-
}, mongoose.Document<unknown, {}, {
|
|
300
298
|
text: string;
|
|
299
|
+
}, mongoose.Document<unknown, {}, {
|
|
301
300
|
type: "tip" | "warning" | "prompt";
|
|
301
|
+
text: string;
|
|
302
302
|
}, {
|
|
303
303
|
id: string;
|
|
304
304
|
}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
|
|
305
305
|
_id: false;
|
|
306
306
|
}> & Omit<{
|
|
307
|
-
text: string;
|
|
308
307
|
type: "tip" | "warning" | "prompt";
|
|
308
|
+
text: string;
|
|
309
309
|
} & {
|
|
310
310
|
_id: mongoose.Types.ObjectId;
|
|
311
311
|
} & {
|
|
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
|
|
|
313
313
|
}, "id"> & {
|
|
314
314
|
id: string;
|
|
315
315
|
}, unknown, {
|
|
316
|
-
text: string;
|
|
317
316
|
type: "tip" | "warning" | "prompt";
|
|
317
|
+
text: string;
|
|
318
318
|
} & {
|
|
319
319
|
_id: mongoose.Types.ObjectId;
|
|
320
320
|
} & {
|