@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.
@@ -39,10 +39,22 @@ import { z } from 'zod';
39
39
  * in-app add "creates the organization and a contact", canon `hubSavePocs`
40
40
  * stamping an empty `agency_id` when it has none (platform-prototype
41
41
  * `src/agencyhub.jsx` @ 0fa04c1 L411), and the Notion draft's proposed `org`
42
- * subject (§ 5). The hti-features schema
43
- * (`udd-schemas/pointOfContact/PointOfContact.v1.json`) and the prototype CSV
44
- * spell `site` as `location`; the ruling's word is stored. `account` is not
45
- * accepted.
42
+ * subject (§ 5). `account` is not accepted.
43
+ *
44
+ * ## `location` is stored; "Site" is displayed (pl-f4c, 0.30.0)
45
+ *
46
+ * The UDD names the object Site (since 2026-10-04), but its stored names, ids
47
+ * and columns stay `location`: the schema of record is hti-features
48
+ * `udd-schemas/location/Location.v1.json`, and the POC draft enum is
49
+ * `agency | program | location | team`. Canon stores `location` everywhere:
50
+ * the POC directory columns (prototype
51
+ * `docs/leads-platform/ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 L236,
52
+ * "subject_type (agency · program · location · team)"), the registry kind
53
+ * (`leads-app/server/models/RegistryEntities.mjs` @ fa0fd0b0 L105-L117) and
54
+ * the object-log subject enum (`leads-app/server/models/ObjectDirectoryEntry.mjs`
55
+ * @ fa0fd0b0 L51). So the stored value is `location` and the display word is
56
+ * {@link pocSubjectTypeLabel}'s "Site". 0.28.0 stored `site`; there is no prod
57
+ * data, so `site` is simply refused (no legacy acceptance, no migration).
46
58
  *
47
59
  * `service` is a Service Listing's contact (Crysta's kickoff D4, prototype
48
60
  * `KICKOFF_SERVICE_LISTING_AND_PARTNER_CONTACT_BUILD_2026-10-14.md` @ c6380f73
@@ -54,8 +66,18 @@ import { z } from 'zod';
54
66
  * else the org"); the platform writer rewrites an `org` subject whose org
55
67
  * genuinely mirrors an agency to that agency.
56
68
  */
57
- declare const POC_SUBJECT_TYPES: readonly ["agency", "org", "program", "team", "site", "service"];
69
+ declare const POC_SUBJECT_TYPES: readonly ["agency", "org", "program", "team", "location", "service"];
58
70
  type PocSubjectType = (typeof POC_SUBJECT_TYPES)[number];
71
+ /**
72
+ * The display word for each subject type: the object names of prototype
73
+ * `docs/leads-platform/ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 § 1
74
+ * (L60-L68: Org · Agency · Program / department · Team · Service listing),
75
+ * with `location` shown as "Site", the UDD's object name since 2026-10-04
76
+ * (pl-f4c). Store the code, render the label.
77
+ */
78
+ declare const POC_SUBJECT_TYPE_LABELS: Readonly<Record<PocSubjectType, string>>;
79
+ /** The display word of a subject type; an unknown type reads as itself. */
80
+ declare function pocSubjectTypeLabel(type: string): string;
59
81
  /** The declared purpose codes (prototype `data/contact_purposes.yaml` @ 6c2db859 L11-L33). */
60
82
  declare const CONTACT_PURPOSE_CODES: readonly ["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"];
61
83
  type ContactPurposeCode = (typeof CONTACT_PURPOSE_CODES)[number];
@@ -74,7 +96,10 @@ declare const CONTACT_PURPOSES: readonly ContactPurpose[];
74
96
  /**
75
97
  * The magic-link purpose. A magic link goes to EVERY contact on the partner
76
98
  * carrying it (Crysta 2026-08-23, restated 2026-10-14), and a contact carrying
77
- * it must have an email (Crysta 2026-10-14, the Admin Hub editor rule).
99
+ * it must have an email (Crysta 2026-10-14, the Admin Hub editor rule). CVC-338
100
+ * (prototype `data/cvcs/core_contact_purpose.yaml` @ 184893b6 L95): "A
101
+ * confidential holder still receives it; the sender never sees the address."
102
+ * (pl-iza: `resolveMagicLinkRecipients`, `ConfidentialReferralRecipients`.)
78
103
  */
79
104
  declare const REFERRALS_MAGIC_LINK_PURPOSE: ContactPurposeCode;
80
105
  declare function isContactPurposeCode(code: unknown): code is ContactPurposeCode;
@@ -120,8 +145,9 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
120
145
  * Point of contact schemas and stored types (pl-3r8).
121
146
  *
122
147
  * A **Point of contact** is a reachable person FOR a subject (agency, org,
123
- * program, team, site), for one or more purposes. It is a platform-wide record
124
- * on platform-db, not something created at first login (Crysta 2026-10-14,
148
+ * program, team, location (shown "Site"), service listing), for one or more
149
+ * purposes. It is a platform-wide record on platform-db, not something
150
+ * created at first login (Crysta 2026-10-14,
125
151
  * Slack D0811D2R6QN p1792036474007189). Columns follow the prototype directory
126
152
  * (`Org + Personnel Registry/HTI_POINT_OF_CONTACT_DIRECTORY.csv` @ prototype
127
153
  * 6c2db859 L1): `poc_id · subject_type · subject_id · user_id | person_id ·
@@ -129,6 +155,66 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
129
155
  * is_confidential · active · notes`. `poc_id` is stored as `id` (the
130
156
  * hti-features schema's name).
131
157
  *
158
+ * ## Emails and phones are lists (pl-e98, 0.30.0)
159
+ *
160
+ * The sheet's single `email` / `phone` columns became `emails[]` / `phones[]`
161
+ * of {@link PocContactEntry} `{ value, is_preferred }`, Crysta's 2026-08-24
162
+ * multi-entry correction. Canon's Admin Hub ledger keeps "every active email
163
+ * and phone as its own row, one preferred per type" (platform-prototype
164
+ * `src/agencyhub.jsx` @ 6f428116 L8096-L8106) and stores each as `{type,
165
+ * value, preferred}` (`methodsFor` L8107-L8132, the save L8181); on a Point of
166
+ * contact the type is the list the entry sits in. The flag is named after the
167
+ * CONTACT rail's `is_preferred` (prototype
168
+ * `leads-app/server/models/ObjectDirectoryEntry.mjs` @ fa0fd0b0 L52); the
169
+ * contact-level `is_primary` (the subject's primary contact) is unrelated and
170
+ * unchanged. No per-entry use label: CVC-154 `contact_info_use_type` is
171
+ * investigative-only and offered by no Platform, PAVE or Thread picker
172
+ * (prototype `data/cvcs/core_contact_info_use_type.yaml` @ fa0fd0b0 L93-L97).
173
+ *
174
+ * The single fields are GONE from the stored row and from every writer body
175
+ * (no prod data, clean cut; no read shim for stored single fields). Read the
176
+ * preferred address through {@link preferredEmail} / {@link preferredPhone};
177
+ * every view also carries read-only `email` / `phone` projections of the
178
+ * preferred entries, as canon's card does (L8195-L8202).
179
+ *
180
+ * The preferred rule. A WRITER list ({@link PocEmailListSchema} /
181
+ * {@link PocPhoneListSchema}) holds at most one entry marked `is_preferred`
182
+ * and is normalized to exactly one: the marked entry, else the FIRST (canon
183
+ * L8126-L8129). It refuses the same email twice or the same phone line twice
184
+ * (by digits, canon's `phoneDigits`, prototype
185
+ * `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
186
+ * L282-L286), and a phone with no digit. A phone is stored AS TYPED, trimmed,
187
+ * as this object's canon writer, the Admin Hub ledger, stores it
188
+ * (`agencyhub.jsx` @ 6f428116 L8124-L8125, L8173, L8511-L8518). An extension
189
+ * makes a distinct line: `402-677-3902 x5` and `402-677-3902` differ by
190
+ * digits, so both may sit on one contact. {@link formatPocPhone} is a
191
+ * DISPLAY-only helper readers apply (canon calls `formatPhone` "display
192
+ * only", L229-L245). A list in an edit replaces the stored list; `[]` clears
193
+ * it, `null` is refused.
194
+ *
195
+ * A STORED list is READ leniently ({@link PointOfContactDocSchema}): the same
196
+ * normalization repairs it (emails trimmed and lowercased, empty and duplicate
197
+ * entries dropped, a missing or null `is_preferred` read as false, no
198
+ * preferred → the first, several → the first marked), so one row's list
199
+ * never takes down a partner's whole read. Only structurally invalid data
200
+ * (not an array, a non-object entry, a non-string value, a non-boolean flag)
201
+ * throws.
202
+ *
203
+ * ## Known deviations (0.30.0)
204
+ *
205
+ * - A seat-linked contact still reads ONE email and ONE phone from `users`
206
+ * until a person Contact log exists (pl-9h4). Canon's motivating case
207
+ * (Crysta's own seat-linked contact) is therefore not yet met.
208
+ * - An entry is removed, not retired: canon's write-in ledger keeps retired
209
+ * entries stamped `retiredOn` (retire-not-remove, L8181-L8185); this list
210
+ * keeps only the live ones.
211
+ * - The write-in identity key uses the preferred email only
212
+ * ({@link pocIdentityKey}, as canon's `hubSavePocs` L382-L384 uses the card's flat
213
+ * email): changing the preferred email changes `identity_key`, and a
214
+ * secondary email shared with another row is not deduplicated. The writer
215
+ * maps an identity unique-index collision to a domain error (the
216
+ * platform's job).
217
+ *
132
218
  * ## Shapes and trust levels
133
219
  *
134
220
  * - {@link PocOwnerSchema}: WHOSE contact it is. Resolved by the platform
@@ -147,18 +233,25 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
147
233
  * Checked on a mint and on the MERGED document of an edit:
148
234
  * 1. `user_id` XOR `person_id` (prototype generator
149
235
  * `tools/build_platform_directory.py` @ 6c2db859 L2556-L2557).
150
- * 2. A seat-linked contact stores no email or phone of its own; they resolve
151
- * from the seat (L2561-L2563; Notion profile § 3 "A contact's phone and
152
- * email belong to the person").
236
+ * 2. A seat-linked contact stores no emails or phones of its own (both
237
+ * lists empty); they resolve from the seat (L2561-L2563; Notion profile
238
+ * § 3 "A contact's phone and email belong to the person").
153
239
  * 3. A contact that is not seat-linked carries a `display_name` (L2571-L2572).
154
240
  * 4. A contact tagged Referrals (magic link) has an email (Crysta
155
- * 2026-10-14). For a seat-linked contact the seat must have one; the
156
- * writer checks the seat.
241
+ * 2026-10-14); the magic link goes to its preferred email. For a
242
+ * seat-linked contact the seat must have one; the writer checks the seat.
157
243
  */
158
244
 
159
- /** The platform-db collection. Platform is its only writer. */
245
+ /**
246
+ * The platform-db collection. The platform writes it; the one exception is the
247
+ * in-app partner add, which every app writes through the shared
248
+ * `mintPartnerContact` (`./writer.ts`).
249
+ */
160
250
  declare const POINTS_OF_CONTACT_COLLECTION = "pointsofcontact";
161
- /** Index names. The platform writer creates them; readers rely on them. */
251
+ /**
252
+ * Index names. `ensurePocIndexes` (`./writer.ts`) creates them, with the
253
+ * in-app pending and review-queue indexes; readers rely on them.
254
+ */
162
255
  declare const POINT_OF_CONTACT_INDEXES: {
163
256
  /** `{id}` unique. */
164
257
  readonly id: "pointsofcontact_id_unique";
@@ -183,6 +276,15 @@ declare const POINT_OF_CONTACT_INDEXES: {
183
276
  * pending add can never hold the slot.
184
277
  */
185
278
  readonly primary: "pointsofcontact_primary_unique";
279
+ /**
280
+ * `{agency_id, subject_type, subject_id, identity_key, createdBy}` unique
281
+ * where {@link POC_IN_APP_PENDING_INDEX_FILTER}: one outstanding in-app add
282
+ * per adder, subject and IDENTITY ({@link pocIdentityKey}: name + preferred
283
+ * email). See `POC_IN_APP_PENDING_INDEX`.
284
+ */
285
+ readonly inAppPending: "pointsofcontact_inapp_pending_unique";
286
+ /** `{status, createdAt, id}`: the steward's review queue, paged oldest first. */
287
+ readonly pendingQueue: "pointsofcontact_pending_queue";
186
288
  };
187
289
  /** The partial filter of {@link POINT_OF_CONTACT_INDEXES.identity}. */
188
290
  declare const POC_IDENTITY_INDEX_FILTER: {
@@ -195,12 +297,163 @@ declare const POC_PRIMARY_INDEX_FILTER: {
195
297
  readonly active: true;
196
298
  readonly status: "confirmed";
197
299
  };
300
+ /** The partial filter of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: an outstanding in-app add. */
301
+ declare const POC_IN_APP_PENDING_INDEX_FILTER: {
302
+ readonly status: "pending";
303
+ readonly origin: "in_app";
304
+ readonly active: true;
305
+ };
306
+ /**
307
+ * The key of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: the stored scalar
308
+ * `identity_key`. Never an email list: two people may share a mailbox
309
+ * (`intake@`), and an email-list key would merge them.
310
+ */
311
+ declare const POC_IN_APP_PENDING_INDEX_KEY: {
312
+ readonly agency_id: 1;
313
+ readonly subject_type: 1;
314
+ readonly subject_id: 1;
315
+ readonly identity_key: 1;
316
+ readonly createdBy: 1;
317
+ };
198
318
  /** A caller-chosen id (seed path only): the hti-features `^poc-[a-z0-9_-]+$` pattern. */
199
319
  declare const POC_ID_PATTERN: RegExp;
200
320
  /** A seat or person id. A 24-hex id is lowercased so one seat has one spelling. */
201
321
  declare const PocLinkIdSchema: z.ZodEffects<z.ZodString, string, string>;
202
322
  /** A lowercased, trimmed email address. */
203
323
  declare const PocEmailSchema: z.ZodString;
324
+ /** At most this many emails, and this many phones, on one contact. */
325
+ declare const POC_MAX_CONTACT_ENTRIES = 10;
326
+ /** One stored email or phone entry. The single source of {@link PocContactEntry}. */
327
+ declare const StoredContactEntrySchema: z.ZodObject<{
328
+ /** An email (lowercased) or a phone as typed (trimmed). */
329
+ value: z.ZodString;
330
+ /** Exactly one entry of a non-empty list is the preferred one. */
331
+ is_preferred: z.ZodBoolean;
332
+ }, "strip", z.ZodTypeAny, {
333
+ value: string;
334
+ is_preferred: boolean;
335
+ }, {
336
+ value: string;
337
+ is_preferred: boolean;
338
+ }>;
339
+ /** One email or phone on a contact (pl-e98). */
340
+ type PocContactEntry = z.infer<typeof StoredContactEntrySchema>;
341
+ /**
342
+ * The line a phone value names: digits only, a leading US country code
343
+ * dropped. Canon's `phoneDigits` (prototype
344
+ * `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
345
+ * L282-L286), verbatim in behaviour.
346
+ */
347
+ declare function pocPhoneDigits(v: string): string;
348
+ /**
349
+ * DISPLAY only: how a reader may draw a stored phone. Canon's `formatPhone`
350
+ * (same file, L246-L256; "This is display only", L244), verbatim in
351
+ * behaviour: every non-digit is dropped, a redundant US `1` is dropped, and
352
+ * the digits are drawn `(AAA) BBB-CCCC`, or `+cc (AAA) BBB-CCCC` past ten
353
+ * digits. Empty when the value has no digit. Never written back: it is lossy
354
+ * (an extension becomes digits of the number, a short number draws oddly), so
355
+ * the store keeps the phone as typed.
356
+ */
357
+ declare function formatPocPhone(s: string): string;
358
+ /** Stored `emails`, read: trimmed, lowercased, empty and repeated entries dropped, one preferred. */
359
+ declare const StoredEmailListSchema: z.ZodEffects<z.ZodArray<z.ZodObject<{
360
+ value: z.ZodString;
361
+ } & {
362
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
363
+ }, "strip", z.ZodTypeAny, {
364
+ value: string;
365
+ is_preferred: boolean;
366
+ }, {
367
+ value: string;
368
+ is_preferred?: boolean | null | undefined;
369
+ }>, "many">, {
370
+ value: string;
371
+ is_preferred: boolean;
372
+ }[], {
373
+ value: string;
374
+ is_preferred?: boolean | null | undefined;
375
+ }[]>;
376
+ /** Stored `phones`, read: trimmed, digitless and repeated lines dropped, one preferred. */
377
+ declare const StoredPhoneListSchema: z.ZodEffects<z.ZodArray<z.ZodObject<{
378
+ value: z.ZodString;
379
+ } & {
380
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
381
+ }, "strip", z.ZodTypeAny, {
382
+ value: string;
383
+ is_preferred: boolean;
384
+ }, {
385
+ value: string;
386
+ is_preferred?: boolean | null | undefined;
387
+ }>, "many">, {
388
+ value: string;
389
+ is_preferred: boolean;
390
+ }[], {
391
+ value: string;
392
+ is_preferred?: boolean | null | undefined;
393
+ }[]>;
394
+ /** A writer's `emails`: lowercased addresses, at most one preferred, the first when none is marked. */
395
+ declare const PocEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
396
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
397
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
398
+ }, "strict", z.ZodTypeAny, {
399
+ value: string;
400
+ is_preferred?: boolean | undefined;
401
+ }, {
402
+ value?: unknown;
403
+ is_preferred?: boolean | undefined;
404
+ }>, "many">, {
405
+ value: string;
406
+ is_preferred?: boolean | undefined;
407
+ }[], {
408
+ value?: unknown;
409
+ is_preferred?: boolean | undefined;
410
+ }[]>, {
411
+ value: string;
412
+ is_preferred: boolean;
413
+ }[], {
414
+ value?: unknown;
415
+ is_preferred?: boolean | undefined;
416
+ }[]>;
417
+ /** A writer's `phones`: as typed, one per line (by digits), at most one preferred, the first when none is marked. */
418
+ declare const PocPhoneListSchema: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
419
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
420
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
421
+ }, "strict", z.ZodTypeAny, {
422
+ value: string;
423
+ is_preferred?: boolean | undefined;
424
+ }, {
425
+ value?: unknown;
426
+ is_preferred?: boolean | undefined;
427
+ }>, "many">, {
428
+ value: string;
429
+ is_preferred?: boolean | undefined;
430
+ }[], {
431
+ value?: unknown;
432
+ is_preferred?: boolean | undefined;
433
+ }[]>, {
434
+ value: string;
435
+ is_preferred: boolean;
436
+ }[], {
437
+ value?: unknown;
438
+ is_preferred?: boolean | undefined;
439
+ }[]>;
440
+ /**
441
+ * The preferred entry of a list: the one marked `is_preferred`, else the
442
+ * first (the first-entry rule), else null for an empty or absent list.
443
+ */
444
+ declare function preferredContactEntry(list: readonly PocContactEntry[] | null | undefined): PocContactEntry | null;
445
+ /**
446
+ * The contact's preferred email from its `emails`, or null. Takes a stored
447
+ * row or any view. On a stored seat-linked row it is null (the email is the
448
+ * seat's); a view's own `email` projection already resolves the seat.
449
+ */
450
+ declare function preferredEmail(c: {
451
+ readonly emails: readonly PocContactEntry[];
452
+ }): string | null;
453
+ /** The contact's preferred phone, or null ({@link preferredEmail}'s rules). */
454
+ declare function preferredPhone(c: {
455
+ readonly phones: readonly PocContactEntry[];
456
+ }): string | null;
204
457
  /**
205
458
  * WHOSE contact this is, resolved by the platform route and normalized by the
206
459
  * platform writer.
@@ -224,39 +477,39 @@ declare const PocEmailSchema: z.ZodString;
224
477
  * - `subject_id`: `agency` → `agency_id`; `org` → `org_id`; `program` →
225
478
  * `organizations.programs[].programId` on the agency's genuine-mirror org;
226
479
  * `team` → the team's `entity_id ?? id ?? String(_id)` (a `teams` row of
227
- * that agency); `site` → the site's id; `service` → the Service Listing's
228
- * `id` (a `servicelistings` row of `org_id`; `agency_id` null or the org's
229
- * genuine-mirror agency). The writer verifies membership;
230
- * `site` is refused until a site directory exists. Team and site ids may
231
- * be slugs two agencies share, so the subject is always read and keyed
232
- * together with `agency_id`.
480
+ * that agency); `location` → the site's id; `service` → the Service
481
+ * Listing's `id` (a `servicelistings` row of `org_id`; `agency_id` null or
482
+ * the org's genuine-mirror agency). The writer verifies membership;
483
+ * `location` is refused until a location directory exists. Team and location
484
+ * ids may be slugs two agencies share, so the subject is always read and
485
+ * keyed together with `agency_id`.
233
486
  *
234
487
  * Every subject except an org-only partner resolves to an agency (canon stamps
235
488
  * `agency_id` on the row: platform-prototype `src/agencyhub.jsx` @ 0fa04c1
236
489
  * L411). An `org` subject carries `agency_id: null`, or its genuine mirror agency.
237
490
  */
238
491
  declare const PocOwnerSchema: z.ZodEffects<z.ZodObject<{
239
- subject_type: z.ZodEnum<["agency", "org", "program", "team", "site", "service"]>;
492
+ subject_type: z.ZodEnum<["agency", "org", "program", "team", "location", "service"]>;
240
493
  subject_id: z.ZodString;
241
494
  agency_id: z.ZodNullable<z.ZodString>;
242
495
  org_id: z.ZodNullable<z.ZodString>;
243
496
  }, "strict", z.ZodTypeAny, {
244
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
497
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
245
498
  subject_id: string;
246
499
  agency_id: string | null;
247
500
  org_id: string | null;
248
501
  }, {
249
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
502
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
250
503
  subject_id: string;
251
504
  agency_id: string | null;
252
505
  org_id: string | null;
253
506
  }>, {
254
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
507
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
255
508
  subject_id: string;
256
509
  agency_id: string | null;
257
510
  org_id: string | null;
258
511
  }, {
259
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
512
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
260
513
  subject_id: string;
261
514
  agency_id: string | null;
262
515
  org_id: string | null;
@@ -266,30 +519,84 @@ declare const PocDetailsSchema: z.ZodObject<{
266
519
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
267
520
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
268
521
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
269
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
270
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
522
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
523
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
524
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
525
+ }, "strict", z.ZodTypeAny, {
526
+ value: string;
527
+ is_preferred?: boolean | undefined;
528
+ }, {
529
+ value?: unknown;
530
+ is_preferred?: boolean | undefined;
531
+ }>, "many">, {
532
+ value: string;
533
+ is_preferred?: boolean | undefined;
534
+ }[], {
535
+ value?: unknown;
536
+ is_preferred?: boolean | undefined;
537
+ }[]>, {
538
+ value: string;
539
+ is_preferred: boolean;
540
+ }[], {
541
+ value?: unknown;
542
+ is_preferred?: boolean | undefined;
543
+ }[]>>;
544
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
545
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
546
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
547
+ }, "strict", z.ZodTypeAny, {
548
+ value: string;
549
+ is_preferred?: boolean | undefined;
550
+ }, {
551
+ value?: unknown;
552
+ is_preferred?: boolean | undefined;
553
+ }>, "many">, {
554
+ value: string;
555
+ is_preferred?: boolean | undefined;
556
+ }[], {
557
+ value?: unknown;
558
+ is_preferred?: boolean | undefined;
559
+ }[]>, {
560
+ value: string;
561
+ is_preferred: boolean;
562
+ }[], {
563
+ value?: unknown;
564
+ is_preferred?: boolean | undefined;
565
+ }[]>>;
271
566
  purposes: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">, ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[], ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[]>>;
272
567
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
273
568
  is_primary: z.ZodOptional<z.ZodBoolean>;
274
569
  is_confidential: z.ZodOptional<z.ZodBoolean>;
275
570
  notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
276
571
  }, "strict", z.ZodTypeAny, {
277
- email?: string | null | undefined;
278
572
  user_id?: string | null | undefined;
279
573
  person_id?: string | null | undefined;
280
574
  display_name?: string | null | undefined;
281
- phone?: string | null | undefined;
575
+ emails?: {
576
+ value: string;
577
+ is_preferred: boolean;
578
+ }[] | undefined;
579
+ phones?: {
580
+ value: string;
581
+ is_preferred: boolean;
582
+ }[] | undefined;
282
583
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
283
584
  urgent_methods?: string[] | undefined;
284
585
  is_primary?: boolean | undefined;
285
586
  is_confidential?: boolean | undefined;
286
587
  notes?: string | null | undefined;
287
588
  }, {
288
- email?: string | null | undefined;
289
589
  user_id?: string | null | undefined;
290
590
  person_id?: string | null | undefined;
291
591
  display_name?: string | null | undefined;
292
- phone?: string | null | undefined;
592
+ emails?: {
593
+ value?: unknown;
594
+ is_preferred?: boolean | undefined;
595
+ }[] | undefined;
596
+ phones?: {
597
+ value?: unknown;
598
+ is_preferred?: boolean | undefined;
599
+ }[] | undefined;
293
600
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
294
601
  urgent_methods?: string[] | undefined;
295
602
  is_primary?: boolean | undefined;
@@ -297,40 +604,146 @@ declare const PocDetailsSchema: z.ZodObject<{
297
604
  notes?: string | null | undefined;
298
605
  }>;
299
606
  type PocDetails = z.infer<typeof PocDetailsSchema>;
607
+ /** What a body builder sends (defaulted and normalized fields optional). */
608
+ type PocDetailsInput = z.input<typeof PocDetailsSchema>;
300
609
  /**
301
610
  * An advocate's in-app add of a partner's contact (pl-bt1; Crysta 2026-10-14
302
- * 23:25): a write-in with a name and an email (the magic-link address), a
303
- * phone if known, tagged Referrals (magic link) unless the body says
304
- * otherwise. No seat or person link, no primary, no confidential flag, no
611
+ * 23:25): a write-in with a name and at least one email (the preferred one is
612
+ * the magic-link address), phones if known, tagged Referrals (magic link) unless
613
+ * the body says otherwise. No seat or person link, no primary, no confidential flag, no
305
614
  * notes: those are the subject's own to set.
306
615
  */
307
616
  declare const PocInAppSchema: z.ZodObject<{
308
617
  display_name: z.ZodString;
309
- email: z.ZodString;
310
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
618
+ emails: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
619
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
620
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
621
+ }, "strict", z.ZodTypeAny, {
622
+ value: string;
623
+ is_preferred?: boolean | undefined;
624
+ }, {
625
+ value?: unknown;
626
+ is_preferred?: boolean | undefined;
627
+ }>, "many">, {
628
+ value: string;
629
+ is_preferred?: boolean | undefined;
630
+ }[], {
631
+ value?: unknown;
632
+ is_preferred?: boolean | undefined;
633
+ }[]>, {
634
+ value: string;
635
+ is_preferred: boolean;
636
+ }[], {
637
+ value?: unknown;
638
+ is_preferred?: boolean | undefined;
639
+ }[]>, {
640
+ value: string;
641
+ is_preferred: boolean;
642
+ }[], {
643
+ value?: unknown;
644
+ is_preferred?: boolean | undefined;
645
+ }[]>;
646
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
647
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
648
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
649
+ }, "strict", z.ZodTypeAny, {
650
+ value: string;
651
+ is_preferred?: boolean | undefined;
652
+ }, {
653
+ value?: unknown;
654
+ is_preferred?: boolean | undefined;
655
+ }>, "many">, {
656
+ value: string;
657
+ is_preferred?: boolean | undefined;
658
+ }[], {
659
+ value?: unknown;
660
+ is_preferred?: boolean | undefined;
661
+ }[]>, {
662
+ value: string;
663
+ is_preferred: boolean;
664
+ }[], {
665
+ value?: unknown;
666
+ is_preferred?: boolean | undefined;
667
+ }[]>>;
311
668
  purposes: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">, ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[], ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[]>>;
312
669
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
313
670
  }, "strict", z.ZodTypeAny, {
314
- email: string;
315
671
  display_name: string;
672
+ emails: {
673
+ value: string;
674
+ is_preferred: boolean;
675
+ }[];
316
676
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
317
- phone?: string | null | undefined;
677
+ phones?: {
678
+ value: string;
679
+ is_preferred: boolean;
680
+ }[] | undefined;
318
681
  urgent_methods?: string[] | undefined;
319
682
  }, {
320
- email: string;
321
683
  display_name: string;
322
- phone?: string | null | undefined;
684
+ emails: {
685
+ value?: unknown;
686
+ is_preferred?: boolean | undefined;
687
+ }[];
688
+ phones?: {
689
+ value?: unknown;
690
+ is_preferred?: boolean | undefined;
691
+ }[] | undefined;
323
692
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
324
693
  urgent_methods?: string[] | undefined;
325
694
  }>;
326
695
  type PocInApp = z.infer<typeof PocInAppSchema>;
696
+ /** The `POST /api/partner-contacts` body a caller sends (`purposes` defaulted). */
697
+ type PocInAppInput = z.input<typeof PocInAppSchema>;
327
698
  /** A seed row: the details plus the sheet's own `poc-*` id. */
328
699
  declare const PocSeedSchema: z.ZodObject<{
329
700
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
330
701
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
331
702
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
332
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
333
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
703
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
704
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
705
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
706
+ }, "strict", z.ZodTypeAny, {
707
+ value: string;
708
+ is_preferred?: boolean | undefined;
709
+ }, {
710
+ value?: unknown;
711
+ is_preferred?: boolean | undefined;
712
+ }>, "many">, {
713
+ value: string;
714
+ is_preferred?: boolean | undefined;
715
+ }[], {
716
+ value?: unknown;
717
+ is_preferred?: boolean | undefined;
718
+ }[]>, {
719
+ value: string;
720
+ is_preferred: boolean;
721
+ }[], {
722
+ value?: unknown;
723
+ is_preferred?: boolean | undefined;
724
+ }[]>>;
725
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
726
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
727
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
728
+ }, "strict", z.ZodTypeAny, {
729
+ value: string;
730
+ is_preferred?: boolean | undefined;
731
+ }, {
732
+ value?: unknown;
733
+ is_preferred?: boolean | undefined;
734
+ }>, "many">, {
735
+ value: string;
736
+ is_preferred?: boolean | undefined;
737
+ }[], {
738
+ value?: unknown;
739
+ is_preferred?: boolean | undefined;
740
+ }[]>, {
741
+ value: string;
742
+ is_preferred: boolean;
743
+ }[], {
744
+ value?: unknown;
745
+ is_preferred?: boolean | undefined;
746
+ }[]>>;
334
747
  purposes: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">, ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[], ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[]>>;
335
748
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
336
749
  is_primary: z.ZodOptional<z.ZodBoolean>;
@@ -340,11 +753,17 @@ declare const PocSeedSchema: z.ZodObject<{
340
753
  id: z.ZodString;
341
754
  }, "strict", z.ZodTypeAny, {
342
755
  id: string;
343
- email?: string | null | undefined;
344
756
  user_id?: string | null | undefined;
345
757
  person_id?: string | null | undefined;
346
758
  display_name?: string | null | undefined;
347
- phone?: string | null | undefined;
759
+ emails?: {
760
+ value: string;
761
+ is_preferred: boolean;
762
+ }[] | undefined;
763
+ phones?: {
764
+ value: string;
765
+ is_preferred: boolean;
766
+ }[] | undefined;
348
767
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
349
768
  urgent_methods?: string[] | undefined;
350
769
  is_primary?: boolean | undefined;
@@ -352,11 +771,17 @@ declare const PocSeedSchema: z.ZodObject<{
352
771
  notes?: string | null | undefined;
353
772
  }, {
354
773
  id: string;
355
- email?: string | null | undefined;
356
774
  user_id?: string | null | undefined;
357
775
  person_id?: string | null | undefined;
358
776
  display_name?: string | null | undefined;
359
- phone?: string | null | undefined;
777
+ emails?: {
778
+ value?: unknown;
779
+ is_preferred?: boolean | undefined;
780
+ }[] | undefined;
781
+ phones?: {
782
+ value?: unknown;
783
+ is_preferred?: boolean | undefined;
784
+ }[] | undefined;
360
785
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
361
786
  urgent_methods?: string[] | undefined;
362
787
  is_primary?: boolean | undefined;
@@ -364,49 +789,116 @@ declare const PocSeedSchema: z.ZodObject<{
364
789
  notes?: string | null | undefined;
365
790
  }>;
366
791
  type PocSeed = z.infer<typeof PocSeedSchema>;
367
- /** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint. */
792
+ type PocSeedInput = z.input<typeof PocSeedSchema>;
793
+ /** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint; a list replaces the stored list. */
368
794
  declare const PocPatchSchema: z.ZodEffects<z.ZodObject<Omit<{
369
795
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
370
796
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
371
797
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
372
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
373
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
798
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
799
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
800
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
801
+ }, "strict", z.ZodTypeAny, {
802
+ value: string;
803
+ is_preferred?: boolean | undefined;
804
+ }, {
805
+ value?: unknown;
806
+ is_preferred?: boolean | undefined;
807
+ }>, "many">, {
808
+ value: string;
809
+ is_preferred?: boolean | undefined;
810
+ }[], {
811
+ value?: unknown;
812
+ is_preferred?: boolean | undefined;
813
+ }[]>, {
814
+ value: string;
815
+ is_preferred: boolean;
816
+ }[], {
817
+ value?: unknown;
818
+ is_preferred?: boolean | undefined;
819
+ }[]>>;
820
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
821
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
822
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
823
+ }, "strict", z.ZodTypeAny, {
824
+ value: string;
825
+ is_preferred?: boolean | undefined;
826
+ }, {
827
+ value?: unknown;
828
+ is_preferred?: boolean | undefined;
829
+ }>, "many">, {
830
+ value: string;
831
+ is_preferred?: boolean | undefined;
832
+ }[], {
833
+ value?: unknown;
834
+ is_preferred?: boolean | undefined;
835
+ }[]>, {
836
+ value: string;
837
+ is_preferred: boolean;
838
+ }[], {
839
+ value?: unknown;
840
+ is_preferred?: boolean | undefined;
841
+ }[]>>;
374
842
  purposes: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">, ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[], ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[]>>;
375
843
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
376
844
  is_primary: z.ZodOptional<z.ZodBoolean>;
377
845
  is_confidential: z.ZodOptional<z.ZodBoolean>;
378
846
  notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
379
847
  }, "user_id" | "person_id">, "strict", z.ZodTypeAny, {
380
- email?: string | null | undefined;
381
848
  display_name?: string | null | undefined;
382
- phone?: string | null | undefined;
849
+ emails?: {
850
+ value: string;
851
+ is_preferred: boolean;
852
+ }[] | undefined;
853
+ phones?: {
854
+ value: string;
855
+ is_preferred: boolean;
856
+ }[] | undefined;
383
857
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
384
858
  urgent_methods?: string[] | undefined;
385
859
  is_primary?: boolean | undefined;
386
860
  is_confidential?: boolean | undefined;
387
861
  notes?: string | null | undefined;
388
862
  }, {
389
- email?: string | null | undefined;
390
863
  display_name?: string | null | undefined;
391
- phone?: string | null | undefined;
864
+ emails?: {
865
+ value?: unknown;
866
+ is_preferred?: boolean | undefined;
867
+ }[] | undefined;
868
+ phones?: {
869
+ value?: unknown;
870
+ is_preferred?: boolean | undefined;
871
+ }[] | undefined;
392
872
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
393
873
  urgent_methods?: string[] | undefined;
394
874
  is_primary?: boolean | undefined;
395
875
  is_confidential?: boolean | undefined;
396
876
  notes?: string | null | undefined;
397
877
  }>, {
398
- email?: string | null | undefined;
399
878
  display_name?: string | null | undefined;
400
- phone?: string | null | undefined;
879
+ emails?: {
880
+ value: string;
881
+ is_preferred: boolean;
882
+ }[] | undefined;
883
+ phones?: {
884
+ value: string;
885
+ is_preferred: boolean;
886
+ }[] | undefined;
401
887
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
402
888
  urgent_methods?: string[] | undefined;
403
889
  is_primary?: boolean | undefined;
404
890
  is_confidential?: boolean | undefined;
405
891
  notes?: string | null | undefined;
406
892
  }, {
407
- email?: string | null | undefined;
408
893
  display_name?: string | null | undefined;
409
- phone?: string | null | undefined;
894
+ emails?: {
895
+ value?: unknown;
896
+ is_preferred?: boolean | undefined;
897
+ }[] | undefined;
898
+ phones?: {
899
+ value?: unknown;
900
+ is_preferred?: boolean | undefined;
901
+ }[] | undefined;
410
902
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
411
903
  urgent_methods?: string[] | undefined;
412
904
  is_primary?: boolean | undefined;
@@ -414,6 +906,7 @@ declare const PocPatchSchema: z.ZodEffects<z.ZodObject<Omit<{
414
906
  notes?: string | null | undefined;
415
907
  }>;
416
908
  type PocPatch = z.infer<typeof PocPatchSchema>;
909
+ type PocPatchInput = z.input<typeof PocPatchSchema>;
417
910
  /**
418
911
  * A parsed patch without its `undefined` values. A key present as
419
912
  * `undefined` means "not edited": written through, the driver would store
@@ -423,16 +916,49 @@ declare function definedPatch<T extends Record<string, unknown>>(p: T): Partial<
423
916
  /** The stored document (Mongo's `_id` stripped). Readers parse every row with it. */
424
917
  declare const PointOfContactDocSchema: z.ZodObject<{
425
918
  id: z.ZodString;
426
- subject_type: z.ZodEnum<["agency", "org", "program", "team", "site", "service"]>;
919
+ subject_type: z.ZodEnum<["agency", "org", "program", "team", "location", "service"]>;
427
920
  subject_id: z.ZodString;
428
921
  agency_id: z.ZodNullable<z.ZodString>;
429
922
  org_id: z.ZodNullable<z.ZodString>;
430
923
  user_id: z.ZodNullable<z.ZodString>;
431
924
  person_id: z.ZodNullable<z.ZodString>;
432
925
  display_name: z.ZodNullable<z.ZodString>;
433
- /** Lowercased. Null on a seat-linked contact (it resolves from the seat). */
434
- email: z.ZodNullable<z.ZodString>;
435
- phone: z.ZodNullable<z.ZodString>;
926
+ /** Lowercased emails, read leniently. Empty on a seat-linked contact (it resolves from the seat). */
927
+ emails: z.ZodEffects<z.ZodArray<z.ZodObject<{
928
+ value: z.ZodString;
929
+ } & {
930
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
931
+ }, "strip", z.ZodTypeAny, {
932
+ value: string;
933
+ is_preferred: boolean;
934
+ }, {
935
+ value: string;
936
+ is_preferred?: boolean | null | undefined;
937
+ }>, "many">, {
938
+ value: string;
939
+ is_preferred: boolean;
940
+ }[], {
941
+ value: string;
942
+ is_preferred?: boolean | null | undefined;
943
+ }[]>;
944
+ /** Read leniently. Empty on a seat-linked contact. */
945
+ phones: z.ZodEffects<z.ZodArray<z.ZodObject<{
946
+ value: z.ZodString;
947
+ } & {
948
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
949
+ }, "strip", z.ZodTypeAny, {
950
+ value: string;
951
+ is_preferred: boolean;
952
+ }, {
953
+ value: string;
954
+ is_preferred?: boolean | null | undefined;
955
+ }>, "many">, {
956
+ value: string;
957
+ is_preferred: boolean;
958
+ }[], {
959
+ value: string;
960
+ is_preferred?: boolean | null | undefined;
961
+ }[]>;
436
962
  purposes: z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">;
437
963
  /** CVC-185 codes. */
438
964
  urgent_methods: z.ZodArray<z.ZodString, "many">;
@@ -444,7 +970,7 @@ declare const PointOfContactDocSchema: z.ZodObject<{
444
970
  status: z.ZodEnum<["pending", "confirmed"]>;
445
971
  origin: z.ZodEnum<["survey", "admin_hub", "in_app", "steward_seed"]>;
446
972
  added_in_app: z.ZodNullable<z.ZodEnum<["pave", "thread", "leads", "platform"]>>;
447
- /** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<email>`, lowercased. */
973
+ /** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<preferred email>`, lowercased. */
448
974
  identity_key: z.ZodString;
449
975
  confirmed_by: z.ZodNullable<z.ZodString>;
450
976
  confirmed_at: z.ZodNullable<z.ZodString>;
@@ -457,16 +983,22 @@ declare const PointOfContactDocSchema: z.ZodObject<{
457
983
  updatedBy: z.ZodNullable<z.ZodString>;
458
984
  updatedAt: z.ZodString;
459
985
  }, "strip", z.ZodTypeAny, {
460
- email: string | null;
461
986
  status: "pending" | "confirmed";
462
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
987
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
463
988
  subject_id: string;
464
989
  agency_id: string | null;
465
990
  org_id: string | null;
466
991
  user_id: string | null;
467
992
  person_id: string | null;
468
993
  display_name: string | null;
469
- phone: string | null;
994
+ emails: {
995
+ value: string;
996
+ is_preferred: boolean;
997
+ }[];
998
+ phones: {
999
+ value: string;
1000
+ is_preferred: boolean;
1001
+ }[];
470
1002
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
471
1003
  urgent_methods: string[];
472
1004
  is_primary: boolean;
@@ -487,16 +1019,22 @@ declare const PointOfContactDocSchema: z.ZodObject<{
487
1019
  updatedBy: string | null;
488
1020
  updatedAt: string;
489
1021
  }, {
490
- email: string | null;
491
1022
  status: "pending" | "confirmed";
492
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
1023
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
493
1024
  subject_id: string;
494
1025
  agency_id: string | null;
495
1026
  org_id: string | null;
496
1027
  user_id: string | null;
497
1028
  person_id: string | null;
498
1029
  display_name: string | null;
499
- phone: string | null;
1030
+ emails: {
1031
+ value: string;
1032
+ is_preferred?: boolean | null | undefined;
1033
+ }[];
1034
+ phones: {
1035
+ value: string;
1036
+ is_preferred?: boolean | null | undefined;
1037
+ }[];
500
1038
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
501
1039
  urgent_methods: string[];
502
1040
  is_primary: boolean;
@@ -519,7 +1057,7 @@ declare const PointOfContactDocSchema: z.ZodObject<{
519
1057
  }>;
520
1058
  type PointOfContactDoc = z.infer<typeof PointOfContactDocSchema>;
521
1059
  /** The fields the whole-contact rules read. */
522
- type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "email" | "phone" | "purposes">;
1060
+ type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails" | "phones" | "purposes">;
523
1061
  interface PocRuleViolation {
524
1062
  reason: "user_id_xor_person_id" | "seat_contact_has_own_reach" | "display_name_required" | "referral_contact_needs_email";
525
1063
  message: string;
@@ -530,8 +1068,13 @@ interface PocRuleViolation {
530
1068
  * read the seat. Returns every violation, empty when the contact is valid.
531
1069
  */
532
1070
  declare function pocRuleViolations(c: PocRuleInput): PocRuleViolation[];
533
- /** The identity a subject's contacts are deduplicated by (canon `hubSavePocs`, platform-prototype `src/agencyhub.jsx` @ 0fa04c1 L382-L384). */
534
- declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "email">): string;
1071
+ /**
1072
+ * The identity a subject's contacts are deduplicated by (canon `hubSavePocs`,
1073
+ * platform-prototype `src/agencyhub.jsx` @ 0fa04c1 L382-L384). A write-in keys
1074
+ * on its name and its PREFERRED email, so changing the preferred email changes
1075
+ * the key: the writer recomputes it on every edit.
1076
+ */
1077
+ declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails">): string;
535
1078
 
536
1079
  /**
537
1080
  * Point of contact read rules (pl-3r8). Pure, no I/O. Every reader (Thread,
@@ -550,7 +1093,14 @@ declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_i
550
1093
  * `Org + Personnel Registry/DIRECTORY_CSV_EDITING_GUIDE.md` @ 6c2db859
551
1094
  * § 0.9 L958; hti-features `PointOfContact.v1.json` `is_confidential`:
552
1095
  * "Never publish this contact"), so it is left out entirely rather
553
- * than masked;
1096
+ * than masked. The network view is unchanged by pl-iza (0.32.0):
1097
+ * confidential rows are absent from every view another organization
1098
+ * sees (this view, `getContact`, `listContactsForSubject`, the
1099
+ * referral `recipients`; only the subject's owner and the steward see
1100
+ * them). A confidential Referrals (magic link) holder still receives
1101
+ * the magic link, but only through the send-only
1102
+ * `resolveMagicLinkRecipients` (`./reader.ts`), which never projects
1103
+ * the row and exposes a count;
554
1104
  * - the seat / person links, `notes`, review stamps, actor ids and the
555
1105
  * identity key are not projected.
556
1106
  * - **Owner view** ({@link toOwnerView}): the subject's own editor (Admin
@@ -562,6 +1112,19 @@ declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_i
562
1112
  * except the identity key, with the seat's reach resolved.
563
1113
  *
564
1114
  * Every view carries `purpose_labels` (hti-features `purpose_labels`, readOnly).
1115
+ *
1116
+ * ## Emails and phones (pl-e98)
1117
+ *
1118
+ * The owner and steward views carry the row's own `emails` / `phones` (what
1119
+ * the editor edits; empty on a seat-linked row) beside the resolved `seat`.
1120
+ * The network view carries the REACHABLE lists: the row's, or for a
1121
+ * seat-linked row the seat's single email and phone as one preferred entry
1122
+ * each. EVERY view also carries read-only `email` / `phone`: the reachable
1123
+ * preferred address (the row's preferred entry, or the seat's for a
1124
+ * seat-linked contact), the projections canon's card keeps of its preferred
1125
+ * entries (platform-prototype `src/agencyhub.jsx` @ 6f428116 L8195-L8202). A
1126
+ * reader that sends to or shows one address reads that projection. Views own
1127
+ * their lists: they are copies, never the row's arrays.
565
1128
  */
566
1129
 
567
1130
  /** A seat's reach, resolved by the reader from platform-db `users`. */
@@ -575,6 +1138,10 @@ interface PointOfContactStewardView extends Omit<PointOfContactDoc, "identity_ke
575
1138
  purpose_labels: string[];
576
1139
  /** The seat's reach for a seat-linked contact (null when unlinked or not found). */
577
1140
  seat: SeatReach | null;
1141
+ /** Read-only: the reachable preferred email (the seat's for a seat-linked contact), or null. */
1142
+ email: string | null;
1143
+ /** Read-only: the reachable preferred phone, or null. */
1144
+ phone: string | null;
578
1145
  }
579
1146
  /** The owner view: unmasked, without other organizations' actor ids. */
580
1147
  type PointOfContactOwnerView = Omit<PointOfContactStewardView, "createdBy" | "updatedBy" | "confirmed_by" | "deactivated_by" | "added_in_app">;
@@ -586,8 +1153,13 @@ interface PointOfContactNetworkView {
586
1153
  agency_id: string | null;
587
1154
  org_id: string | null;
588
1155
  display_name: string | null;
589
- /** The row's email, or the seat's when the contact is seat-linked and a seat resolver was given. */
1156
+ /** The row's emails, or the seat's email as one preferred entry when the contact is seat-linked and a seat resolver was given. */
1157
+ emails: PocContactEntry[];
1158
+ /** The row's phones, or the seat's phone as one preferred entry (the same rules as `emails`). */
1159
+ phones: PocContactEntry[];
1160
+ /** The preferred of `emails` (`preferredEmail(view)`), or null. The magic-link address. */
590
1161
  email: string | null;
1162
+ /** The preferred of `phones` (`preferredPhone(view)`), or null. */
591
1163
  phone: string | null;
592
1164
  purposes: ContactPurposeCode[];
593
1165
  purpose_labels: string[];
@@ -602,10 +1174,10 @@ declare class PointOfContactShapeError extends Error {
602
1174
  constructor(contactId: string | null, issues: string[]);
603
1175
  }
604
1176
  /**
605
- * A stored row → the typed document. Strict: the platform is the only writer
606
- * and writes every field, so a row that does not parse (an unknown origin or
607
- * status, a missing id) is a defect and FAILS LOUDLY rather than being read as
608
- * some default.
1177
+ * A stored row → the typed document. Strict: every writer (the platform's,
1178
+ * and the shared in-app add every app runs, `./writer.ts`) writes every
1179
+ * field, so a row that does not parse (an unknown origin or status, a missing
1180
+ * id) is a defect and FAILS LOUDLY rather than being read as some default.
609
1181
  */
610
1182
  declare function normalizePointOfContact(raw: Record<string, unknown>): PointOfContactDoc;
611
1183
  /** True when other organizations may see or use this contact. */
@@ -620,7 +1192,7 @@ declare function toOwnerView(d: PointOfContactDoc, seat?: SeatReach | null): Poi
620
1192
  * from `seat`.
621
1193
  */
622
1194
  declare function toNetworkView(d: PointOfContactDoc, seat?: SeatReach | null): PointOfContactNetworkView | null;
623
- /** Reading order: the agency / org before its programs, teams and sites, primary first, then name, then id. */
1195
+ /** Reading order: the agency / org before its programs, teams and locations, primary first, then name, then id. */
624
1196
  declare function byContactReadingOrder(a: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">, b: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">): number;
625
1197
 
626
1198
  /**
@@ -641,6 +1213,19 @@ declare function byContactReadingOrder(a: Pick<PointOfContactDoc, "subject_type"
641
1213
  * ObjectId filter for `users._id`; the reader passes a {@link SeatResolver}
642
1214
  * that reads its own `users`. The partner rollup REQUIRES one, so a reader
643
1215
  * cannot silently drop seat-linked referral contacts.
1216
+ *
1217
+ * ## Confidential Referrals (magic link) holders (pl-iza, 0.32.0)
1218
+ *
1219
+ * A confidential holder still receives the magic link; the sender never sees
1220
+ * the address (CVC-338, prototype `data/cvcs/core_contact_purpose.yaml` @
1221
+ * 184893b6 L95; HANDOFF.md @ 184893b6 L569, L575 "POC-PROFILE-ALIGNMENTS"
1222
+ * D(ii)). Confidential rows are absent from every view another organization
1223
+ * sees (only the owner and steward reads carry them). The referral rollup
1224
+ * reads them in a SEPARATE query and hands out only a count
1225
+ * (`confidentialCount`) or, to a send, a {@link ConfidentialReferralRecipients}
1226
+ * whose `deliver` alone touches the addresses (the implementation is not
1227
+ * exported). A confidential row never reaches `unreachable`, and a corrupt
1228
+ * row that may be confidential is counted, never thrown.
644
1229
  */
645
1230
 
646
1231
  /** The slice of a driver `Collection` the reads use. */
@@ -658,7 +1243,7 @@ interface PocDbLike {
658
1243
  type SeatResolver = (userIds: readonly string[]) => Promise<ReadonlyMap<string, SeatReach>>;
659
1244
  /**
660
1245
  * A subject, always read together with its agency where ids can collide.
661
- * Program, team and site ids can be slugs two agencies share, so their reads
1246
+ * Program, team and location ids can be slugs two agencies share, so their reads
662
1247
  * REQUIRE `agency_id`. A service listing's contact names `agency_id` too:
663
1248
  * the listing org's genuine-mirror agency, or `null` for an org-only partner.
664
1249
  * Only agency and org subjects (whose ids are themselves unique) may omit it.
@@ -668,7 +1253,7 @@ type PocSubjectRef = {
668
1253
  subject_id: string;
669
1254
  agency_id?: string | null;
670
1255
  } | {
671
- subject_type: "program" | "team" | "site";
1256
+ subject_type: "program" | "team" | "location";
672
1257
  subject_id: string;
673
1258
  agency_id: string;
674
1259
  } | {
@@ -693,27 +1278,150 @@ interface PocPartnerSelector {
693
1278
  declare function listContactsForSubject(db: PocDbLike, subject: PocSubjectRef, opts?: {
694
1279
  resolveSeats?: SeatResolver;
695
1280
  }): Promise<PointOfContactNetworkView[]>;
696
- /** A referral recipient: a network-visible contact with a resolved email. */
1281
+ /**
1282
+ * A referral recipient: a network-visible contact with a resolved email, or
1283
+ * (only when asked, {@link ReferralContactsOptions.includeOwnPendingFor}) the
1284
+ * asking advocate's OWN pending in-app add, marked `pending: true` so a UI can
1285
+ * label it.
1286
+ */
697
1287
  type ReferralRecipient = PointOfContactNetworkView & {
698
1288
  email: string;
1289
+ pending?: true;
699
1290
  };
1291
+ interface ReferralContactsOptions {
1292
+ resolveSeats: SeatResolver;
1293
+ /**
1294
+ * The asking advocate's Auth0 `sub`, taken server-side from the verified
1295
+ * token (the same pinning as `mintPartnerContact`'s `actor.id`). When set,
1296
+ * the advocate's OWN pending in-app adds on the partner (`status: pending`,
1297
+ * active, `origin: in_app`, `createdBy` = this sub, tagged Referrals (magic
1298
+ * link), not confidential) are returned too, after the confirmed recipients
1299
+ * and marked `pending: true`. Nobody else's pending add is ever returned.
1300
+ */
1301
+ includeOwnPendingFor?: string;
1302
+ }
700
1303
  interface ReferralContactsResult {
701
1304
  /** One per distinct email, in reading order (the agency's own contacts first). */
702
1305
  recipients: ReferralRecipient[];
703
- /** Ids of tagged, visible contacts with no email to send to (a seat whose `users` row has none). */
1306
+ /**
1307
+ * Ids of tagged, VISIBLE contacts with no email to send to (a seat whose
1308
+ * `users` row has none). Never a confidential holder's id.
1309
+ */
704
1310
  unreachable: string[];
1311
+ /**
1312
+ * The number of distinct confidential Referrals (magic link) holder
1313
+ * addresses (pl-iza): active, confirmed, `is_confidential`, tagged, on the
1314
+ * same rollup. Deduped among the confidential holders ONLY, never against
1315
+ * any visible, pending, typed or added address, so no other row or input
1316
+ * moves it. A sender sees this number, never a name, an id or an address
1317
+ * ("+ 1 confidential recipient").
1318
+ */
1319
+ confidentialCount: number;
705
1320
  }
706
1321
  /**
707
1322
  * The partner's Referrals (magic link) contacts: every active, confirmed,
708
1323
  * non-confidential contact tagged `REFERRALS_MAGIC_LINK` on the partner's
709
- * agency AND on its programs, teams and sites (the rollup, via the row's
1324
+ * agency AND on its programs, teams and locations (the rollup, via the row's
710
1325
  * `agency_id`), and on its organization (via `org_id`). A magic link goes to
711
- * every one of them (Crysta 2026-08-23, restated 2026-10-14). The same email
712
- * tagged on two subjects is one recipient.
1326
+ * every one of them (Crysta 2026-08-23, restated 2026-10-14), at its PREFERRED
1327
+ * email (pl-e98; the view's `email`). The same email tagged on two subjects is
1328
+ * one recipient.
1329
+ *
1330
+ * With `includeOwnPendingFor` (Nate 2026-10-15), the advocate also sees their
1331
+ * own pending in-app adds on the partner, so a contact they just added can be
1332
+ * picked before HTI Labs confirms it (pending, marked, after the confirmed
1333
+ * recipients; an email a confirmed recipient already has is not repeated).
1334
+ * Confidential rows stay out of `recipients` and `unreachable`; they are
1335
+ * counted (`confidentialCount`, pl-iza) and reached only through
1336
+ * {@link resolveMagicLinkRecipients}. The partner has a
1337
+ * magic-link holder when `recipients.length + confidentialCount > 0`.
713
1338
  */
714
- declare function listReferralContactsForPartner(db: PocDbLike, partner: PocPartnerSelector, opts: {
715
- resolveSeats: SeatResolver;
716
- }): Promise<ReferralContactsResult>;
1339
+ declare function listReferralContactsForPartner(db: PocDbLike, partner: PocPartnerSelector, opts: ReferralContactsOptions): Promise<ReferralContactsResult>;
1340
+ /** What a send needs: the visible recipients, plus the confidential holders behind a count. */
1341
+ interface MagicLinkSendList {
1342
+ /** As {@link ReferralContactsResult.recipients}. */
1343
+ recipients: ReferralRecipient[];
1344
+ /** As {@link ReferralContactsResult.unreachable}: visible contacts only. */
1345
+ unreachable: string[];
1346
+ /** The confidential holders: a count, and a `deliver` that alone touches their addresses. */
1347
+ confidential: ConfidentialReferralRecipients;
1348
+ /**
1349
+ * SERVER-SIDE diagnostic, never returned to a sender: the confidential
1350
+ * holder rows that cannot be sent to (no email, a seat with none or not
1351
+ * found), plus skipped rows that do not match the contract and may be
1352
+ * confidential (their error would name their id). A count, never an id.
1353
+ */
1354
+ confidentialUnreachableCount: number;
1355
+ }
1356
+ /**
1357
+ * SEND-ONLY (pl-iza). The same read as {@link listReferralContactsForPartner},
1358
+ * with the confidential holders as a {@link ConfidentialReferralRecipients}
1359
+ * instead of a bare count. Call it at send time, server-side, and hand
1360
+ * `confidential.deliver` the mailer; never return the result to a browser
1361
+ * beyond `confidential.count` (its `toJSON` is `{ count }`). This is the only
1362
+ * way to obtain a `ConfidentialReferralRecipients` (the implementation is
1363
+ * not exported).
1364
+ *
1365
+ * Canon: CVC-338 `REFERRALS_MAGIC_LINK` (prototype
1366
+ * `data/cvcs/core_contact_purpose.yaml` @ 184893b6 L95): "A confidential
1367
+ * holder still receives it; the sender never sees the address."
1368
+ */
1369
+ declare function resolveMagicLinkRecipients(db: PocDbLike, partner: PocPartnerSelector, opts: ReferralContactsOptions): Promise<MagicLinkSendList>;
1370
+ /**
1371
+ * Sends one magic link to one address. It must THROW (or reject) on failure;
1372
+ * returning normally counts as delivered. It must not log, persist or return
1373
+ * `address`.
1374
+ */
1375
+ type ConfidentialSendOne = (address: string) => void | Promise<void>;
1376
+ interface ConfidentialDeliverOptions {
1377
+ /** At most this many sends (a non-negative integer); the rest are `overflow`. Unlimited when omitted. */
1378
+ capacity?: number;
1379
+ }
1380
+ /**
1381
+ * A confidential delivery's outcome: numbers and an error class name, never an
1382
+ * address. SERVER-SIDE, for audit only: a sender may see `count`, or one
1383
+ * all-or-nothing status derived from it, never `delivered`, `failed`,
1384
+ * `overflow` or `firstErrorName`.
1385
+ */
1386
+ interface ConfidentialDeliveryResult {
1387
+ /** The holder count (`delivered + failed + overflow`). */
1388
+ count: number;
1389
+ delivered: number;
1390
+ failed: number;
1391
+ /** Holders beyond `capacity`, not sent: `max(0, count - capacity)`. */
1392
+ overflow: number;
1393
+ /** The first failed send's `err.name` (never its message, which can echo the address), or null. */
1394
+ firstErrorName: string | null;
1395
+ }
1396
+ /**
1397
+ * A partner's confidential Referrals (magic link) holders (pl-iza). It carries
1398
+ * their addresses privately and exposes only `count`: `toJSON()` is
1399
+ * `{ count }`, `util.inspect` draws `ConfidentialReferralRecipients(n)`, and
1400
+ * no public member returns an address. Only {@link deliver} touches them,
1401
+ * handing each to the caller's `sendOne`.
1402
+ *
1403
+ * An interface, exported as a type only. The implementation is not
1404
+ * exported: obtain values only via {@link resolveMagicLinkRecipients}.
1405
+ */
1406
+ interface ConfidentialReferralRecipients {
1407
+ readonly count: number;
1408
+ /**
1409
+ * Sends to the first `capacity` holders (all when omitted), one at a time.
1410
+ * The outcome depends only on the holders, `capacity` and each send's
1411
+ * result, never on any address the caller handled: an address the sender
1412
+ * also typed is sent again, so nothing observable moves when one matches.
1413
+ * Never rejects for a failed send: each error is caught and only its `name`
1414
+ * is kept (a provider's message can echo the address). The result is
1415
+ * server-side only (see {@link ConfidentialDeliveryResult}).
1416
+ */
1417
+ deliver(sendOne: ConfidentialSendOne, opts?: ConfidentialDeliverOptions): Promise<ConfidentialDeliveryResult>;
1418
+ /** `{ count }`: what a response, a record or an event may carry. */
1419
+ toJSON(): {
1420
+ count: number;
1421
+ };
1422
+ /** `ConfidentialReferralRecipients(n)`. */
1423
+ toString(): string;
1424
+ }
717
1425
  /** One contact as other organizations see it, or null (absent or not network-visible). */
718
1426
  declare function getContact(db: PocDbLike, id: string, opts?: {
719
1427
  resolveSeats?: SeatResolver;
@@ -732,4 +1440,268 @@ declare function listPendingContacts(db: PocDbLike, opts?: {
732
1440
  resolveSeats?: SeatResolver;
733
1441
  }): Promise<PointOfContactStewardView[]>;
734
1442
 
735
- export { CONTACT_PURPOSES, CONTACT_PURPOSE_CODES, type ContactPurpose, type ContactPurposeCode, POC_ADDED_IN_APPS, POC_IDENTITY_INDEX_FILTER, POC_ID_PATTERN, POC_ORIGINS, POC_PRIMARY_INDEX_FILTER, POC_STATUSES, POC_SUBJECT_TYPES, POC_URGENT_METHODS, POC_URGENT_METHOD_KEYS, POINTS_OF_CONTACT_COLLECTION, POINT_OF_CONTACT_INDEXES, type PocAddedInApp, type PocCollectionLike, type PocDbLike, type PocDetails, PocDetailsSchema, PocEmailSchema, type PocInApp, PocInAppSchema, PocLinkIdSchema, type PocOrigin, type PocOwner, PocOwnerSchema, type PocPartnerSelector, type PocPatch, PocPatchSchema, type PocRuleInput, type PocRuleViolation, type PocSeed, PocSeedSchema, type PocStatus, type PocSubjectRef, type PocSubjectType, type PocUrgentMethod, type PointOfContactDoc, PointOfContactDocSchema, type PointOfContactNetworkView, type PointOfContactOwnerView, PointOfContactShapeError, type PointOfContactStewardView, REFERRALS_MAGIC_LINK_PURPOSE, type ReferralContactsResult, type ReferralRecipient, type SeatReach, type SeatResolver, byContactReadingOrder, contactPurposeLabel, definedPatch, getContact, isContactPurposeCode, isNetworkVisible, isPocUrgentMethodCode, listContactsForSubject, listOwnerContactsForSubject, listPendingContacts, listReferralContactsForPartner, normalizePointOfContact, pocIdentityKey, pocInitialStatus, pocRuleViolations, pocUrgentMethodCode, toNetworkView, toOwnerView, toStewardView };
1443
+ /**
1444
+ * The in-app partner add, shared (pl-bt1, pl-e98): an advocate in Thread, PAVE
1445
+ * or LEADS names a partner on a share and the contact they type lands in
1446
+ * platform-db `pointsofcontact` as a PENDING Point of contact tagged Referrals
1447
+ * (magic link). Every app runs THIS implementation against its own platform-db
1448
+ * handle; there is no HTTP hop. It is the platform's `addPartnerContact`
1449
+ * (platform `lib/points-of-contact/repository.ts`, the store behind
1450
+ * `POST /api/partner-contacts`) and the internals it uses from
1451
+ * `lib/points-of-contact/core.ts` (`resolveOwner` for an agency or org
1452
+ * subject, `insertContact`, the index set, the duplicate-key mapping) and
1453
+ * `lib/sharing-settings/recipient-id.ts` (`resolveRecipientId`), moved here
1454
+ * with the same rules, the same order of checks and the same refusal codes.
1455
+ *
1456
+ * ## What it does, in order
1457
+ *
1458
+ * 1. The actor names the advocate (`actor_required`), the app is one of
1459
+ * {@link POC_PARTNER_ADD_APPS} (`invalid_app`), the contact is a strict
1460
+ * {@link PocInAppSchema} body (`invalid_contact`), always tagged Referrals
1461
+ * (magic link) first.
1462
+ * 2. The partner is a strict {@link PartnerContactSelectorSchema} selector
1463
+ * (`invalid_partner`), resolved to its owner (decision D1): an agency in any
1464
+ * accepted form (`entity_id`, `id`, `_id` in either stored shape, a mapped
1465
+ * `registry_agencies` row) becomes `String(agencies._id)`; an org is
1466
+ * `String(organizations._id)`. An org whose org GENUINELY mirrors an
1467
+ * agency puts the contact on that agency (kickoff D1). Unresolved:
1468
+ * `owner_not_found`; an agency and org that are not one partner:
1469
+ * `owner_mismatch`. A canonical singleton org (`canonical_org`) or a PAVE
1470
+ * 2.0-shape org (`foreign_row_shape`) is refused.
1471
+ * 3. What already exists answers the add, looking only at rows the caller may
1472
+ * know about, matched on the package identity rule ({@link pocIdentityKey}:
1473
+ * `writein:<name>|<preferred email>`), never on a shared email: a visible
1474
+ * tagged contact, else the caller's own pending add (both `created:
1475
+ * false`, no write); the caller's own add that the partner removed is
1476
+ * refused (`contact_deactivated`).
1477
+ * 4. The caller's outstanding pending adds are capped per partner
1478
+ * ({@link POC_IN_APP_PENDING_CAP_PER_PARTNER}) and across the network
1479
+ * ({@link POC_IN_APP_PENDING_CAP_PER_ACTOR}): `too_many_pending_adds`.
1480
+ * 5. The row is inserted `pending`, `origin: in_app`, `added_in_app: <app>`,
1481
+ * version 1, after the whole-contact rules ({@link pocRuleViolations})
1482
+ * and the index check ({@link checkPocIndexes}: the writer never creates
1483
+ * an index; a missing one is `indexes_missing`, 503). A simultaneous
1484
+ * identical add that won the insert (`duplicate_pending_add`) answers with
1485
+ * the winner's row; an add that finds a cap exceeded after its insert
1486
+ * withdraws itself (429).
1487
+ *
1488
+ * ## The caller's part
1489
+ *
1490
+ * The full contract is the package README ("Caller contract"). In short:
1491
+ * `actor.id` is the advocate's Auth0 `sub`, taken server-side from the
1492
+ * verified token, never from a request body; `app` is the caller's own server
1493
+ * constant and the caller checks the advocate's `allowed_apps` for it; the
1494
+ * handle is the deployment's own platform-db, long-lived, reading from the
1495
+ * primary; `now` is never taken from a request. The platform's own write
1496
+ * guard (`read_only_registry`) is not here.
1497
+ *
1498
+ * ## No driver import, no logging
1499
+ *
1500
+ * Like the reads, the handle is typed structurally ({@link PocWriteDbLike}):
1501
+ * a `mongodb` `Db` or a mongoose connection's `.db` fits. The driver's
1502
+ * `ObjectId` class is passed in ({@link PocWriterDriver}): it builds the
1503
+ * ObjectId form of a 24-hex id (production `agencies._id` and
1504
+ * `organizations._id` are ObjectIds) and mints the `poc-<hex>` id. Nothing is
1505
+ * logged: a domain refusal is a returned code, never a throw, and no message
1506
+ * carries a stored value (a contact's email, a driver error's duplicate key).
1507
+ * A read or write ERROR (an outage, a stored row that does not parse,
1508
+ * `PointOfContactShapeError`) propagates.
1509
+ */
1510
+
1511
+ /** The slice of a driver cursor the writer uses. */
1512
+ interface PocWriteCursorLike {
1513
+ toArray(): Promise<unknown[]>;
1514
+ }
1515
+ /** One entry of a driver `indexes()` (`listIndexes`) listing. */
1516
+ interface PocIndexInfoLike {
1517
+ name?: unknown;
1518
+ key?: unknown;
1519
+ unique?: unknown;
1520
+ partialFilterExpression?: unknown;
1521
+ }
1522
+ /** The options the writer passes to `createIndex`. */
1523
+ interface PocCreateIndexOptions {
1524
+ name: string;
1525
+ unique?: boolean;
1526
+ partialFilterExpression?: Record<string, unknown>;
1527
+ }
1528
+ /** The slice of a driver `Collection` the writer uses. */
1529
+ interface PocWriteCollectionLike {
1530
+ find(filter: Record<string, unknown>, options?: Record<string, unknown>): PocWriteCursorLike;
1531
+ findOne(filter: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
1532
+ countDocuments(filter: Record<string, unknown>): Promise<number>;
1533
+ insertOne(doc: Record<string, unknown>): Promise<unknown>;
1534
+ deleteOne(filter: Record<string, unknown>): Promise<unknown>;
1535
+ /** Used by the platform's {@link ensurePocIndexes} only; the writer never creates an index. */
1536
+ createIndex(key: Record<string, 1 | -1>, options: PocCreateIndexOptions): Promise<unknown>;
1537
+ indexes(): Promise<PocIndexInfoLike[]>;
1538
+ }
1539
+ /** The slice of a driver `Db` the writer uses: a platform-db handle the caller may write. */
1540
+ interface PocWriteDbLike {
1541
+ collection(name: string): PocWriteCollectionLike;
1542
+ }
1543
+ /** The driver's ObjectId class (`mongodb`'s `ObjectId`, or `mongoose.Types.ObjectId`). */
1544
+ interface PocObjectIdClass {
1545
+ new (hex?: string): {
1546
+ toHexString(): string;
1547
+ };
1548
+ }
1549
+ /** What the writer needs from the caller's driver. */
1550
+ interface PocWriterDriver {
1551
+ ObjectId: PocObjectIdClass;
1552
+ }
1553
+ /** The apps an in-app add may come from: {@link POC_ADDED_IN_APPS} less `platform`. */
1554
+ type PocPartnerAddApp = Exclude<PocAddedInApp, "platform">;
1555
+ declare const POC_PARTNER_ADD_APPS: readonly PocPartnerAddApp[];
1556
+ /**
1557
+ * The partner the advocate picked or created, in the directory id universe
1558
+ * (D1): `agency_id` = `String(agencies._id)` or any form that resolves to it,
1559
+ * `org_id` = `String(organizations._id)`. One key, or both when they are a
1560
+ * genuine mirror pair. The same keys as `listReferralContactsForPartner`, so
1561
+ * an app writes and reads one partner the same way. Strict: a subject the
1562
+ * body picks is refused.
1563
+ */
1564
+ declare const PartnerContactSelectorSchema: z.ZodEffects<z.ZodObject<{
1565
+ agency_id: z.ZodOptional<z.ZodString>;
1566
+ org_id: z.ZodOptional<z.ZodString>;
1567
+ }, "strict", z.ZodTypeAny, {
1568
+ agency_id?: string | undefined;
1569
+ org_id?: string | undefined;
1570
+ }, {
1571
+ agency_id?: string | undefined;
1572
+ org_id?: string | undefined;
1573
+ }>, {
1574
+ agency_id?: string | undefined;
1575
+ org_id?: string | undefined;
1576
+ }, {
1577
+ agency_id?: string | undefined;
1578
+ org_id?: string | undefined;
1579
+ }>;
1580
+ type PartnerContactSelector = z.infer<typeof PartnerContactSelectorSchema>;
1581
+ type PartnerContactSelectorInput = z.input<typeof PartnerContactSelectorSchema>;
1582
+ /** Outstanding (pending, active) in-app adds one adder may have across the network. */
1583
+ declare const POC_IN_APP_PENDING_CAP_PER_ACTOR = 25;
1584
+ /** Outstanding (pending, active) in-app adds one adder may have on one partner. */
1585
+ declare const POC_IN_APP_PENDING_CAP_PER_PARTNER = 5;
1586
+ /**
1587
+ * One outstanding in-app add per adder, per subject and identity
1588
+ * ({@link POC_IN_APP_PENDING_INDEX_KEY}: the stored `identity_key`, name +
1589
+ * preferred email). Two simultaneous identical first adds race to the insert;
1590
+ * the loser's E11000 maps to `duplicate_pending_add`, which
1591
+ * {@link mintPartnerContact} answers with the winner's row: the index and the
1592
+ * matcher ({@link pocRowsWithIdentity}) use the same key, so the re-read always
1593
+ * finds the winner.
1594
+ *
1595
+ * Not keyed on emails: people share mailboxes (`intake@`), and a
1596
+ * "shares ANY email" rule (an interim 0.30.0 platform build, multikey on
1597
+ * `emails.value`) answered one person's add with another's row and let a
1598
+ * removed row block every later add sharing a secondary mailbox.
1599
+ */
1600
+ declare const POC_IN_APP_PENDING_INDEX: "pointsofcontact_inapp_pending_unique";
1601
+ /** The steward's review queue, paged oldest first (platform `listPendingContacts`). */
1602
+ declare const POC_PENDING_QUEUE_INDEX: "pointsofcontact_pending_queue";
1603
+ /**
1604
+ * FOR THE PLATFORM (its deploy or boot), never an app's writer: Thread and
1605
+ * PAVE hold no index privilege, and {@link mintPartnerContact} only checks
1606
+ * the indexes ({@link checkPocIndexes}). The platform must deploy and run this
1607
+ * before any app writes.
1608
+ *
1609
+ * Create the `pointsofcontact` indexes, the platform's full set: plain
1610
+ * `createIndex` calls, idempotent (memoized per handle, retried after a
1611
+ * failure; a failure propagates). No migration: no data or index existed
1612
+ * before 0.30.0. The partial unique indexes are the store's uniqueness rules:
1613
+ * no twin of one person among a subject's visible rows, at most one visible
1614
+ * primary per subject, and one outstanding in-app add per adder, subject and
1615
+ * identity ({@link POC_IN_APP_PENDING_INDEX}). Pass a long-lived handle: the
1616
+ * memo is keyed on it.
1617
+ */
1618
+ declare function ensurePocIndexes(db: PocWriteDbLike): Promise<void>;
1619
+ /**
1620
+ * Whether the indexes the writer relies on exist, read through `listIndexes`
1621
+ * (the writer never creates one: least privilege; the platform creates them
1622
+ * with {@link ensurePocIndexes}). Each required index must exist with exactly
1623
+ * its key (fields, order, direction), `unique: true` and exactly its partial
1624
+ * filter (under any name): `id` unique, and {@link POC_IN_APP_PENDING_INDEX}
1625
+ * (the race recovery and the dedupe depend on it). A missing collection
1626
+ * (NamespaceNotFound) or index refuses the write, `indexes_missing` (503):
1627
+ * fail closed. A pass is memoized per handle; a refusal is not, so the next
1628
+ * add re-checks. Any other read error propagates.
1629
+ */
1630
+ declare function checkPocIndexes(db: PocWriteDbLike): Promise<PartnerContactFailure | null>;
1631
+ /** Every refusal {@link mintPartnerContact} can return, as the platform route answers them. */
1632
+ declare const PARTNER_CONTACT_FAILURE_REASONS: readonly ["actor_required", "invalid_app", "invalid_contact", "invalid_partner", "owner_not_found", "owner_mismatch", "canonical_org", "foreign_row_shape", "contact_deactivated", "too_many_pending_adds", "duplicate_pending_add", "duplicate_contact", "primary_exists", "duplicate_contact_id", "duplicate_key", "user_id_xor_person_id", "seat_contact_has_own_reach", "display_name_required", "referral_contact_needs_email", "indexes_missing"];
1633
+ type PartnerContactFailureReason = (typeof PARTNER_CONTACT_FAILURE_REASONS)[number];
1634
+ /**
1635
+ * A domain refusal: `status` is the HTTP status the platform route answers it
1636
+ * with, `reason` its code, `message` a fixed human sentence, or for
1637
+ * `invalid_contact` / `invalid_partner` the schema's issue list (paths and
1638
+ * rule messages). Never a stored value.
1639
+ */
1640
+ interface PartnerContactFailure {
1641
+ ok: false;
1642
+ status: 400 | 409 | 429 | 503;
1643
+ reason: PartnerContactFailureReason;
1644
+ message?: string;
1645
+ }
1646
+ /** What an in-app add returns to the app: the contact's id and status, never another org's contact details. */
1647
+ interface PartnerContactReceipt {
1648
+ id: string;
1649
+ status: PocStatus;
1650
+ /** False when an equivalent contact already existed and nothing was written. */
1651
+ created: boolean;
1652
+ /** Where the store put it: the partner's agency when the org has a genuine-mirror agency (kickoff D1), else the org. */
1653
+ subject_type: PocOwner["subject_type"];
1654
+ subject_id: string;
1655
+ agency_id: string | null;
1656
+ org_id: string | null;
1657
+ }
1658
+ type PartnerContactResult = {
1659
+ ok: true;
1660
+ value: PartnerContactReceipt;
1661
+ } | PartnerContactFailure;
1662
+ /**
1663
+ * The rows on the resolved subject with this identity ({@link pocIdentityKey},
1664
+ * as stored in `identity_key`), any status or activity: the same key as
1665
+ * {@link POC_IN_APP_PENDING_INDEX}, so a raced add always finds the row that
1666
+ * won. The index and this matcher must agree, which is why both live here.
1667
+ * A row that does not parse throws.
1668
+ */
1669
+ declare function pocRowsWithIdentity(db: PocDbLike, owner: Pick<PocOwner, "agency_id" | "subject_type" | "subject_id">, identityKey: string): Promise<PointOfContactDoc[]>;
1670
+ /**
1671
+ * A duplicate-key error → the refusal for the index it hit, or null when the
1672
+ * error is not a duplicate key (the caller rethrows). Mapped per index by
1673
+ * name, then by key pattern. The driver's message is never returned: it
1674
+ * echoes the duplicate key, i.e. the contact's email.
1675
+ */
1676
+ declare function pocDuplicateKeyFailure(err: unknown): PartnerContactFailure | null;
1677
+ /** Who is adding: the advocate. Never a steward here. */
1678
+ interface PocInAppActor {
1679
+ /**
1680
+ * The advocate's Auth0 `sub`, taken SERVER-SIDE from the verified token
1681
+ * (as the platform route takes `auth0Sub`), never from a request body or a
1682
+ * client-supplied header. Stored as `createdBy`; the adder's dedupe, caps and
1683
+ * removed-add refusal key on it.
1684
+ */
1685
+ id: string;
1686
+ }
1687
+ interface MintPartnerContactArgs {
1688
+ /** The app the advocate is adding from. */
1689
+ app: PocPartnerAddApp;
1690
+ /** The partner, by directory id ({@link PartnerContactSelectorSchema}). */
1691
+ partner: PartnerContactSelectorInput;
1692
+ /** The contact ({@link PocInAppSchema}: a name and at least one email; phones optional). */
1693
+ contact: PocInAppInput;
1694
+ actor: PocInAppActor;
1695
+ /** The mint time (`createdAt`); defaults to now. Server time only, never from a request. */
1696
+ now?: Date;
1697
+ }
1698
+ /**
1699
+ * The in-app partner add, written straight to platform-db (module comment).
1700
+ * Every argument is validated at run time as well as typed. Returns a
1701
+ * {@link PartnerContactReceipt} (`created: true` for a new pending row,
1702
+ * `false` when an equivalent contact answered and nothing was written) or a
1703
+ * {@link PartnerContactFailure}; never throws a domain refusal.
1704
+ */
1705
+ declare function mintPartnerContact(db: PocWriteDbLike, args: MintPartnerContactArgs, driver: PocWriterDriver): Promise<PartnerContactResult>;
1706
+
1707
+ export { CONTACT_PURPOSES, CONTACT_PURPOSE_CODES, type ConfidentialDeliverOptions, type ConfidentialDeliveryResult, type ConfidentialReferralRecipients, type ConfidentialSendOne, type ContactPurpose, type ContactPurposeCode, type MagicLinkSendList, type MintPartnerContactArgs, PARTNER_CONTACT_FAILURE_REASONS, POC_ADDED_IN_APPS, POC_IDENTITY_INDEX_FILTER, POC_ID_PATTERN, POC_IN_APP_PENDING_CAP_PER_ACTOR, POC_IN_APP_PENDING_CAP_PER_PARTNER, POC_IN_APP_PENDING_INDEX, POC_IN_APP_PENDING_INDEX_FILTER, POC_IN_APP_PENDING_INDEX_KEY, POC_MAX_CONTACT_ENTRIES, POC_ORIGINS, POC_PARTNER_ADD_APPS, POC_PENDING_QUEUE_INDEX, POC_PRIMARY_INDEX_FILTER, POC_STATUSES, POC_SUBJECT_TYPES, POC_SUBJECT_TYPE_LABELS, POC_URGENT_METHODS, POC_URGENT_METHOD_KEYS, POINTS_OF_CONTACT_COLLECTION, POINT_OF_CONTACT_INDEXES, type PartnerContactFailure, type PartnerContactFailureReason, type PartnerContactReceipt, type PartnerContactResult, type PartnerContactSelector, type PartnerContactSelectorInput, PartnerContactSelectorSchema, type PocAddedInApp, type PocCollectionLike, type PocContactEntry, type PocCreateIndexOptions, type PocDbLike, type PocDetails, type PocDetailsInput, PocDetailsSchema, PocEmailListSchema, PocEmailSchema, type PocInApp, type PocInAppActor, type PocInAppInput, PocInAppSchema, type PocIndexInfoLike, PocLinkIdSchema, type PocObjectIdClass, type PocOrigin, type PocOwner, PocOwnerSchema, type PocPartnerAddApp, type PocPartnerSelector, type PocPatch, type PocPatchInput, PocPatchSchema, PocPhoneListSchema, type PocRuleInput, type PocRuleViolation, type PocSeed, type PocSeedInput, PocSeedSchema, type PocStatus, type PocSubjectRef, type PocSubjectType, type PocUrgentMethod, type PocWriteCollectionLike, type PocWriteCursorLike, type PocWriteDbLike, type PocWriterDriver, type PointOfContactDoc, PointOfContactDocSchema, type PointOfContactNetworkView, type PointOfContactOwnerView, PointOfContactShapeError, type PointOfContactStewardView, REFERRALS_MAGIC_LINK_PURPOSE, type ReferralContactsOptions, type ReferralContactsResult, type ReferralRecipient, type SeatReach, type SeatResolver, StoredContactEntrySchema, StoredEmailListSchema, StoredPhoneListSchema, byContactReadingOrder, checkPocIndexes, contactPurposeLabel, definedPatch, ensurePocIndexes, formatPocPhone, getContact, isContactPurposeCode, isNetworkVisible, isPocUrgentMethodCode, listContactsForSubject, listOwnerContactsForSubject, listPendingContacts, listReferralContactsForPartner, mintPartnerContact, normalizePointOfContact, pocDuplicateKeyFailure, pocIdentityKey, pocInitialStatus, pocPhoneDigits, pocRowsWithIdentity, pocRuleViolations, pocSubjectTypeLabel, pocUrgentMethodCode, preferredContactEntry, preferredEmail, preferredPhone, resolveMagicLinkRecipients, toNetworkView, toOwnerView, toStewardView };