@htilabs/platform-common-models 0.29.0 → 0.30.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];
@@ -120,8 +142,9 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
120
142
  * Point of contact schemas and stored types (pl-3r8).
121
143
  *
122
144
  * 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,
145
+ * program, team, location (shown "Site"), service listing), for one or more
146
+ * purposes. It is a platform-wide record on platform-db, not something
147
+ * created at first login (Crysta 2026-10-14,
125
148
  * Slack D0811D2R6QN p1792036474007189). Columns follow the prototype directory
126
149
  * (`Org + Personnel Registry/HTI_POINT_OF_CONTACT_DIRECTORY.csv` @ prototype
127
150
  * 6c2db859 L1): `poc_id · subject_type · subject_id · user_id | person_id ·
@@ -129,6 +152,66 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
129
152
  * is_confidential · active · notes`. `poc_id` is stored as `id` (the
130
153
  * hti-features schema's name).
131
154
  *
155
+ * ## Emails and phones are lists (pl-e98, 0.30.0)
156
+ *
157
+ * The sheet's single `email` / `phone` columns became `emails[]` / `phones[]`
158
+ * of {@link PocContactEntry} `{ value, is_preferred }`, Crysta's 2026-08-24
159
+ * multi-entry correction. Canon's Admin Hub ledger keeps "every active email
160
+ * and phone as its own row, one preferred per type" (platform-prototype
161
+ * `src/agencyhub.jsx` @ 6f428116 L8096-L8106) and stores each as `{type,
162
+ * value, preferred}` (`methodsFor` L8107-L8132, the save L8181); on a Point of
163
+ * contact the type is the list the entry sits in. The flag is named after the
164
+ * CONTACT rail's `is_preferred` (prototype
165
+ * `leads-app/server/models/ObjectDirectoryEntry.mjs` @ fa0fd0b0 L52); the
166
+ * contact-level `is_primary` (the subject's primary contact) is unrelated and
167
+ * unchanged. No per-entry use label: CVC-154 `contact_info_use_type` is
168
+ * investigative-only and offered by no Platform, PAVE or Thread picker
169
+ * (prototype `data/cvcs/core_contact_info_use_type.yaml` @ fa0fd0b0 L93-L97).
170
+ *
171
+ * The single fields are GONE from the stored row and from every writer body
172
+ * (no prod data, clean cut; no read shim for stored single fields). Read the
173
+ * preferred address through {@link preferredEmail} / {@link preferredPhone};
174
+ * every view also carries read-only `email` / `phone` projections of the
175
+ * preferred entries, as canon's card does (L8195-L8202).
176
+ *
177
+ * The preferred rule. A WRITER list ({@link PocEmailListSchema} /
178
+ * {@link PocPhoneListSchema}) holds at most one entry marked `is_preferred`
179
+ * and is normalized to exactly one: the marked entry, else the FIRST (canon
180
+ * L8126-L8129). It refuses the same email twice or the same phone line twice
181
+ * (by digits, canon's `phoneDigits`, prototype
182
+ * `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
183
+ * L282-L286), and a phone with no digit. A phone is stored AS TYPED, trimmed,
184
+ * as this object's canon writer, the Admin Hub ledger, stores it
185
+ * (`agencyhub.jsx` @ 6f428116 L8124-L8125, L8173, L8511-L8518). An extension
186
+ * makes a distinct line: `402-677-3902 x5` and `402-677-3902` differ by
187
+ * digits, so both may sit on one contact. {@link formatPocPhone} is a
188
+ * DISPLAY-only helper readers apply (canon calls `formatPhone` "display
189
+ * only", L229-L245). A list in an edit replaces the stored list; `[]` clears
190
+ * it, `null` is refused.
191
+ *
192
+ * A STORED list is READ leniently ({@link PointOfContactDocSchema}): the same
193
+ * normalization repairs it (emails trimmed and lowercased, empty and duplicate
194
+ * entries dropped, a missing or null `is_preferred` read as false, no
195
+ * preferred → the first, several → the first marked), so one row's list
196
+ * never takes down a partner's whole read. Only structurally invalid data
197
+ * (not an array, a non-object entry, a non-string value, a non-boolean flag)
198
+ * throws.
199
+ *
200
+ * ## Known deviations (0.30.0)
201
+ *
202
+ * - A seat-linked contact still reads ONE email and ONE phone from `users`
203
+ * until a person Contact log exists (pl-9h4). Canon's motivating case
204
+ * (Crysta's own seat-linked contact) is therefore not yet met.
205
+ * - An entry is removed, not retired: canon's write-in ledger keeps retired
206
+ * entries stamped `retiredOn` (retire-not-remove, L8181-L8185); this list
207
+ * keeps only the live ones.
208
+ * - The write-in identity key uses the preferred email only
209
+ * ({@link pocIdentityKey}, as canon's `hubSavePocs` L382-L384 uses the card's flat
210
+ * email): changing the preferred email changes `identity_key`, and a
211
+ * secondary email shared with another row is not deduplicated. The writer
212
+ * maps an identity unique-index collision to a domain error (the
213
+ * platform's job).
214
+ *
132
215
  * ## Shapes and trust levels
133
216
  *
134
217
  * - {@link PocOwnerSchema}: WHOSE contact it is. Resolved by the platform
@@ -147,18 +230,25 @@ declare function pocInitialStatus(origin: PocOrigin): PocStatus;
147
230
  * Checked on a mint and on the MERGED document of an edit:
148
231
  * 1. `user_id` XOR `person_id` (prototype generator
149
232
  * `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").
233
+ * 2. A seat-linked contact stores no emails or phones of its own (both
234
+ * lists empty); they resolve from the seat (L2561-L2563; Notion profile
235
+ * § 3 "A contact's phone and email belong to the person").
153
236
  * 3. A contact that is not seat-linked carries a `display_name` (L2571-L2572).
154
237
  * 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.
238
+ * 2026-10-14); the magic link goes to its preferred email. For a
239
+ * seat-linked contact the seat must have one; the writer checks the seat.
157
240
  */
158
241
 
159
- /** The platform-db collection. Platform is its only writer. */
242
+ /**
243
+ * The platform-db collection. The platform writes it; the one exception is the
244
+ * in-app partner add, which every app writes through the shared
245
+ * `mintPartnerContact` (`./writer.ts`).
246
+ */
160
247
  declare const POINTS_OF_CONTACT_COLLECTION = "pointsofcontact";
161
- /** Index names. The platform writer creates them; readers rely on them. */
248
+ /**
249
+ * Index names. `ensurePocIndexes` (`./writer.ts`) creates them, with the
250
+ * in-app pending and review-queue indexes; readers rely on them.
251
+ */
162
252
  declare const POINT_OF_CONTACT_INDEXES: {
163
253
  /** `{id}` unique. */
164
254
  readonly id: "pointsofcontact_id_unique";
@@ -183,6 +273,15 @@ declare const POINT_OF_CONTACT_INDEXES: {
183
273
  * pending add can never hold the slot.
184
274
  */
185
275
  readonly primary: "pointsofcontact_primary_unique";
276
+ /**
277
+ * `{agency_id, subject_type, subject_id, identity_key, createdBy}` unique
278
+ * where {@link POC_IN_APP_PENDING_INDEX_FILTER}: one outstanding in-app add
279
+ * per adder, subject and IDENTITY ({@link pocIdentityKey}: name + preferred
280
+ * email). See `POC_IN_APP_PENDING_INDEX`.
281
+ */
282
+ readonly inAppPending: "pointsofcontact_inapp_pending_unique";
283
+ /** `{status, createdAt, id}`: the steward's review queue, paged oldest first. */
284
+ readonly pendingQueue: "pointsofcontact_pending_queue";
186
285
  };
187
286
  /** The partial filter of {@link POINT_OF_CONTACT_INDEXES.identity}. */
188
287
  declare const POC_IDENTITY_INDEX_FILTER: {
@@ -195,12 +294,163 @@ declare const POC_PRIMARY_INDEX_FILTER: {
195
294
  readonly active: true;
196
295
  readonly status: "confirmed";
197
296
  };
297
+ /** The partial filter of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: an outstanding in-app add. */
298
+ declare const POC_IN_APP_PENDING_INDEX_FILTER: {
299
+ readonly status: "pending";
300
+ readonly origin: "in_app";
301
+ readonly active: true;
302
+ };
303
+ /**
304
+ * The key of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: the stored scalar
305
+ * `identity_key`. Never an email list: two people may share a mailbox
306
+ * (`intake@`), and an email-list key would merge them.
307
+ */
308
+ declare const POC_IN_APP_PENDING_INDEX_KEY: {
309
+ readonly agency_id: 1;
310
+ readonly subject_type: 1;
311
+ readonly subject_id: 1;
312
+ readonly identity_key: 1;
313
+ readonly createdBy: 1;
314
+ };
198
315
  /** A caller-chosen id (seed path only): the hti-features `^poc-[a-z0-9_-]+$` pattern. */
199
316
  declare const POC_ID_PATTERN: RegExp;
200
317
  /** A seat or person id. A 24-hex id is lowercased so one seat has one spelling. */
201
318
  declare const PocLinkIdSchema: z.ZodEffects<z.ZodString, string, string>;
202
319
  /** A lowercased, trimmed email address. */
203
320
  declare const PocEmailSchema: z.ZodString;
321
+ /** At most this many emails, and this many phones, on one contact. */
322
+ declare const POC_MAX_CONTACT_ENTRIES = 10;
323
+ /** One stored email or phone entry. The single source of {@link PocContactEntry}. */
324
+ declare const StoredContactEntrySchema: z.ZodObject<{
325
+ /** An email (lowercased) or a phone as typed (trimmed). */
326
+ value: z.ZodString;
327
+ /** Exactly one entry of a non-empty list is the preferred one. */
328
+ is_preferred: z.ZodBoolean;
329
+ }, "strip", z.ZodTypeAny, {
330
+ value: string;
331
+ is_preferred: boolean;
332
+ }, {
333
+ value: string;
334
+ is_preferred: boolean;
335
+ }>;
336
+ /** One email or phone on a contact (pl-e98). */
337
+ type PocContactEntry = z.infer<typeof StoredContactEntrySchema>;
338
+ /**
339
+ * The line a phone value names: digits only, a leading US country code
340
+ * dropped. Canon's `phoneDigits` (prototype
341
+ * `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
342
+ * L282-L286), verbatim in behaviour.
343
+ */
344
+ declare function pocPhoneDigits(v: string): string;
345
+ /**
346
+ * DISPLAY only: how a reader may draw a stored phone. Canon's `formatPhone`
347
+ * (same file, L246-L256; "This is display only", L244), verbatim in
348
+ * behaviour: every non-digit is dropped, a redundant US `1` is dropped, and
349
+ * the digits are drawn `(AAA) BBB-CCCC`, or `+cc (AAA) BBB-CCCC` past ten
350
+ * digits. Empty when the value has no digit. Never written back: it is lossy
351
+ * (an extension becomes digits of the number, a short number draws oddly), so
352
+ * the store keeps the phone as typed.
353
+ */
354
+ declare function formatPocPhone(s: string): string;
355
+ /** Stored `emails`, read: trimmed, lowercased, empty and repeated entries dropped, one preferred. */
356
+ declare const StoredEmailListSchema: z.ZodEffects<z.ZodArray<z.ZodObject<{
357
+ value: z.ZodString;
358
+ } & {
359
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
360
+ }, "strip", z.ZodTypeAny, {
361
+ value: string;
362
+ is_preferred: boolean;
363
+ }, {
364
+ value: string;
365
+ is_preferred?: boolean | null | undefined;
366
+ }>, "many">, {
367
+ value: string;
368
+ is_preferred: boolean;
369
+ }[], {
370
+ value: string;
371
+ is_preferred?: boolean | null | undefined;
372
+ }[]>;
373
+ /** Stored `phones`, read: trimmed, digitless and repeated lines dropped, one preferred. */
374
+ declare const StoredPhoneListSchema: z.ZodEffects<z.ZodArray<z.ZodObject<{
375
+ value: z.ZodString;
376
+ } & {
377
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
378
+ }, "strip", z.ZodTypeAny, {
379
+ value: string;
380
+ is_preferred: boolean;
381
+ }, {
382
+ value: string;
383
+ is_preferred?: boolean | null | undefined;
384
+ }>, "many">, {
385
+ value: string;
386
+ is_preferred: boolean;
387
+ }[], {
388
+ value: string;
389
+ is_preferred?: boolean | null | undefined;
390
+ }[]>;
391
+ /** A writer's `emails`: lowercased addresses, at most one preferred, the first when none is marked. */
392
+ declare const PocEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
393
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
394
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
395
+ }, "strict", z.ZodTypeAny, {
396
+ value: string;
397
+ is_preferred?: boolean | undefined;
398
+ }, {
399
+ value?: unknown;
400
+ is_preferred?: boolean | undefined;
401
+ }>, "many">, {
402
+ value: string;
403
+ is_preferred?: boolean | undefined;
404
+ }[], {
405
+ value?: unknown;
406
+ is_preferred?: boolean | undefined;
407
+ }[]>, {
408
+ value: string;
409
+ is_preferred: boolean;
410
+ }[], {
411
+ value?: unknown;
412
+ is_preferred?: boolean | undefined;
413
+ }[]>;
414
+ /** A writer's `phones`: as typed, one per line (by digits), at most one preferred, the first when none is marked. */
415
+ declare const PocPhoneListSchema: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
416
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
417
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
418
+ }, "strict", z.ZodTypeAny, {
419
+ value: string;
420
+ is_preferred?: boolean | undefined;
421
+ }, {
422
+ value?: unknown;
423
+ is_preferred?: boolean | undefined;
424
+ }>, "many">, {
425
+ value: string;
426
+ is_preferred?: boolean | undefined;
427
+ }[], {
428
+ value?: unknown;
429
+ is_preferred?: boolean | undefined;
430
+ }[]>, {
431
+ value: string;
432
+ is_preferred: boolean;
433
+ }[], {
434
+ value?: unknown;
435
+ is_preferred?: boolean | undefined;
436
+ }[]>;
437
+ /**
438
+ * The preferred entry of a list: the one marked `is_preferred`, else the
439
+ * first (the first-entry rule), else null for an empty or absent list.
440
+ */
441
+ declare function preferredContactEntry(list: readonly PocContactEntry[] | null | undefined): PocContactEntry | null;
442
+ /**
443
+ * The contact's preferred email from its `emails`, or null. Takes a stored
444
+ * row or any view. On a stored seat-linked row it is null (the email is the
445
+ * seat's); a view's own `email` projection already resolves the seat.
446
+ */
447
+ declare function preferredEmail(c: {
448
+ readonly emails: readonly PocContactEntry[];
449
+ }): string | null;
450
+ /** The contact's preferred phone, or null ({@link preferredEmail}'s rules). */
451
+ declare function preferredPhone(c: {
452
+ readonly phones: readonly PocContactEntry[];
453
+ }): string | null;
204
454
  /**
205
455
  * WHOSE contact this is, resolved by the platform route and normalized by the
206
456
  * platform writer.
@@ -224,39 +474,39 @@ declare const PocEmailSchema: z.ZodString;
224
474
  * - `subject_id`: `agency` → `agency_id`; `org` → `org_id`; `program` →
225
475
  * `organizations.programs[].programId` on the agency's genuine-mirror org;
226
476
  * `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`.
477
+ * that agency); `location` → the site's id; `service` → the Service
478
+ * Listing's `id` (a `servicelistings` row of `org_id`; `agency_id` null or
479
+ * the org's genuine-mirror agency). The writer verifies membership;
480
+ * `location` is refused until a location directory exists. Team and location
481
+ * ids may be slugs two agencies share, so the subject is always read and
482
+ * keyed together with `agency_id`.
233
483
  *
234
484
  * Every subject except an org-only partner resolves to an agency (canon stamps
235
485
  * `agency_id` on the row: platform-prototype `src/agencyhub.jsx` @ 0fa04c1
236
486
  * L411). An `org` subject carries `agency_id: null`, or its genuine mirror agency.
237
487
  */
238
488
  declare const PocOwnerSchema: z.ZodEffects<z.ZodObject<{
239
- subject_type: z.ZodEnum<["agency", "org", "program", "team", "site", "service"]>;
489
+ subject_type: z.ZodEnum<["agency", "org", "program", "team", "location", "service"]>;
240
490
  subject_id: z.ZodString;
241
491
  agency_id: z.ZodNullable<z.ZodString>;
242
492
  org_id: z.ZodNullable<z.ZodString>;
243
493
  }, "strict", z.ZodTypeAny, {
244
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
494
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
245
495
  subject_id: string;
246
496
  agency_id: string | null;
247
497
  org_id: string | null;
248
498
  }, {
249
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
499
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
250
500
  subject_id: string;
251
501
  agency_id: string | null;
252
502
  org_id: string | null;
253
503
  }>, {
254
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
504
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
255
505
  subject_id: string;
256
506
  agency_id: string | null;
257
507
  org_id: string | null;
258
508
  }, {
259
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
509
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
260
510
  subject_id: string;
261
511
  agency_id: string | null;
262
512
  org_id: string | null;
@@ -266,30 +516,84 @@ declare const PocDetailsSchema: z.ZodObject<{
266
516
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
267
517
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
268
518
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
269
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
270
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
519
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
520
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
521
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
522
+ }, "strict", z.ZodTypeAny, {
523
+ value: string;
524
+ is_preferred?: boolean | undefined;
525
+ }, {
526
+ value?: unknown;
527
+ is_preferred?: boolean | undefined;
528
+ }>, "many">, {
529
+ value: string;
530
+ is_preferred?: boolean | undefined;
531
+ }[], {
532
+ value?: unknown;
533
+ is_preferred?: boolean | undefined;
534
+ }[]>, {
535
+ value: string;
536
+ is_preferred: boolean;
537
+ }[], {
538
+ value?: unknown;
539
+ is_preferred?: boolean | undefined;
540
+ }[]>>;
541
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
542
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
543
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
544
+ }, "strict", z.ZodTypeAny, {
545
+ value: string;
546
+ is_preferred?: boolean | undefined;
547
+ }, {
548
+ value?: unknown;
549
+ is_preferred?: boolean | undefined;
550
+ }>, "many">, {
551
+ value: string;
552
+ is_preferred?: boolean | undefined;
553
+ }[], {
554
+ value?: unknown;
555
+ is_preferred?: boolean | undefined;
556
+ }[]>, {
557
+ value: string;
558
+ is_preferred: boolean;
559
+ }[], {
560
+ value?: unknown;
561
+ is_preferred?: boolean | undefined;
562
+ }[]>>;
271
563
  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
564
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
273
565
  is_primary: z.ZodOptional<z.ZodBoolean>;
274
566
  is_confidential: z.ZodOptional<z.ZodBoolean>;
275
567
  notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
276
568
  }, "strict", z.ZodTypeAny, {
277
- email?: string | null | undefined;
278
569
  user_id?: string | null | undefined;
279
570
  person_id?: string | null | undefined;
280
571
  display_name?: string | null | undefined;
281
- phone?: string | null | undefined;
572
+ emails?: {
573
+ value: string;
574
+ is_preferred: boolean;
575
+ }[] | undefined;
576
+ phones?: {
577
+ value: string;
578
+ is_preferred: boolean;
579
+ }[] | undefined;
282
580
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
283
581
  urgent_methods?: string[] | undefined;
284
582
  is_primary?: boolean | undefined;
285
583
  is_confidential?: boolean | undefined;
286
584
  notes?: string | null | undefined;
287
585
  }, {
288
- email?: string | null | undefined;
289
586
  user_id?: string | null | undefined;
290
587
  person_id?: string | null | undefined;
291
588
  display_name?: string | null | undefined;
292
- phone?: string | null | undefined;
589
+ emails?: {
590
+ value?: unknown;
591
+ is_preferred?: boolean | undefined;
592
+ }[] | undefined;
593
+ phones?: {
594
+ value?: unknown;
595
+ is_preferred?: boolean | undefined;
596
+ }[] | undefined;
293
597
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
294
598
  urgent_methods?: string[] | undefined;
295
599
  is_primary?: boolean | undefined;
@@ -297,40 +601,146 @@ declare const PocDetailsSchema: z.ZodObject<{
297
601
  notes?: string | null | undefined;
298
602
  }>;
299
603
  type PocDetails = z.infer<typeof PocDetailsSchema>;
604
+ /** What a body builder sends (defaulted and normalized fields optional). */
605
+ type PocDetailsInput = z.input<typeof PocDetailsSchema>;
300
606
  /**
301
607
  * 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
608
+ * 23:25): a write-in with a name and at least one email (the preferred one is
609
+ * the magic-link address), phones if known, tagged Referrals (magic link) unless
610
+ * the body says otherwise. No seat or person link, no primary, no confidential flag, no
305
611
  * notes: those are the subject's own to set.
306
612
  */
307
613
  declare const PocInAppSchema: z.ZodObject<{
308
614
  display_name: z.ZodString;
309
- email: z.ZodString;
310
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
615
+ emails: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
616
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
617
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
618
+ }, "strict", z.ZodTypeAny, {
619
+ value: string;
620
+ is_preferred?: boolean | undefined;
621
+ }, {
622
+ value?: unknown;
623
+ is_preferred?: boolean | undefined;
624
+ }>, "many">, {
625
+ value: string;
626
+ is_preferred?: boolean | undefined;
627
+ }[], {
628
+ value?: unknown;
629
+ is_preferred?: boolean | undefined;
630
+ }[]>, {
631
+ value: string;
632
+ is_preferred: boolean;
633
+ }[], {
634
+ value?: unknown;
635
+ is_preferred?: boolean | undefined;
636
+ }[]>, {
637
+ value: string;
638
+ is_preferred: boolean;
639
+ }[], {
640
+ value?: unknown;
641
+ is_preferred?: boolean | undefined;
642
+ }[]>;
643
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
644
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
645
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
646
+ }, "strict", z.ZodTypeAny, {
647
+ value: string;
648
+ is_preferred?: boolean | undefined;
649
+ }, {
650
+ value?: unknown;
651
+ is_preferred?: boolean | undefined;
652
+ }>, "many">, {
653
+ value: string;
654
+ is_preferred?: boolean | undefined;
655
+ }[], {
656
+ value?: unknown;
657
+ is_preferred?: boolean | undefined;
658
+ }[]>, {
659
+ value: string;
660
+ is_preferred: boolean;
661
+ }[], {
662
+ value?: unknown;
663
+ is_preferred?: boolean | undefined;
664
+ }[]>>;
311
665
  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
666
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
313
667
  }, "strict", z.ZodTypeAny, {
314
- email: string;
315
668
  display_name: string;
669
+ emails: {
670
+ value: string;
671
+ is_preferred: boolean;
672
+ }[];
316
673
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
317
- phone?: string | null | undefined;
674
+ phones?: {
675
+ value: string;
676
+ is_preferred: boolean;
677
+ }[] | undefined;
318
678
  urgent_methods?: string[] | undefined;
319
679
  }, {
320
- email: string;
321
680
  display_name: string;
322
- phone?: string | null | undefined;
681
+ emails: {
682
+ value?: unknown;
683
+ is_preferred?: boolean | undefined;
684
+ }[];
685
+ phones?: {
686
+ value?: unknown;
687
+ is_preferred?: boolean | undefined;
688
+ }[] | undefined;
323
689
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
324
690
  urgent_methods?: string[] | undefined;
325
691
  }>;
326
692
  type PocInApp = z.infer<typeof PocInAppSchema>;
693
+ /** The `POST /api/partner-contacts` body a caller sends (`purposes` defaulted). */
694
+ type PocInAppInput = z.input<typeof PocInAppSchema>;
327
695
  /** A seed row: the details plus the sheet's own `poc-*` id. */
328
696
  declare const PocSeedSchema: z.ZodObject<{
329
697
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
330
698
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
331
699
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
332
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
333
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
700
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
701
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
702
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
703
+ }, "strict", z.ZodTypeAny, {
704
+ value: string;
705
+ is_preferred?: boolean | undefined;
706
+ }, {
707
+ value?: unknown;
708
+ is_preferred?: boolean | undefined;
709
+ }>, "many">, {
710
+ value: string;
711
+ is_preferred?: boolean | undefined;
712
+ }[], {
713
+ value?: unknown;
714
+ is_preferred?: boolean | undefined;
715
+ }[]>, {
716
+ value: string;
717
+ is_preferred: boolean;
718
+ }[], {
719
+ value?: unknown;
720
+ is_preferred?: boolean | undefined;
721
+ }[]>>;
722
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
723
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
724
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
725
+ }, "strict", z.ZodTypeAny, {
726
+ value: string;
727
+ is_preferred?: boolean | undefined;
728
+ }, {
729
+ value?: unknown;
730
+ is_preferred?: boolean | undefined;
731
+ }>, "many">, {
732
+ value: string;
733
+ is_preferred?: boolean | undefined;
734
+ }[], {
735
+ value?: unknown;
736
+ is_preferred?: boolean | undefined;
737
+ }[]>, {
738
+ value: string;
739
+ is_preferred: boolean;
740
+ }[], {
741
+ value?: unknown;
742
+ is_preferred?: boolean | undefined;
743
+ }[]>>;
334
744
  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
745
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
336
746
  is_primary: z.ZodOptional<z.ZodBoolean>;
@@ -340,11 +750,17 @@ declare const PocSeedSchema: z.ZodObject<{
340
750
  id: z.ZodString;
341
751
  }, "strict", z.ZodTypeAny, {
342
752
  id: string;
343
- email?: string | null | undefined;
344
753
  user_id?: string | null | undefined;
345
754
  person_id?: string | null | undefined;
346
755
  display_name?: string | null | undefined;
347
- phone?: string | null | undefined;
756
+ emails?: {
757
+ value: string;
758
+ is_preferred: boolean;
759
+ }[] | undefined;
760
+ phones?: {
761
+ value: string;
762
+ is_preferred: boolean;
763
+ }[] | undefined;
348
764
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
349
765
  urgent_methods?: string[] | undefined;
350
766
  is_primary?: boolean | undefined;
@@ -352,11 +768,17 @@ declare const PocSeedSchema: z.ZodObject<{
352
768
  notes?: string | null | undefined;
353
769
  }, {
354
770
  id: string;
355
- email?: string | null | undefined;
356
771
  user_id?: string | null | undefined;
357
772
  person_id?: string | null | undefined;
358
773
  display_name?: string | null | undefined;
359
- phone?: string | null | undefined;
774
+ emails?: {
775
+ value?: unknown;
776
+ is_preferred?: boolean | undefined;
777
+ }[] | undefined;
778
+ phones?: {
779
+ value?: unknown;
780
+ is_preferred?: boolean | undefined;
781
+ }[] | undefined;
360
782
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
361
783
  urgent_methods?: string[] | undefined;
362
784
  is_primary?: boolean | undefined;
@@ -364,49 +786,116 @@ declare const PocSeedSchema: z.ZodObject<{
364
786
  notes?: string | null | undefined;
365
787
  }>;
366
788
  type PocSeed = z.infer<typeof PocSeedSchema>;
367
- /** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint. */
789
+ type PocSeedInput = z.input<typeof PocSeedSchema>;
790
+ /** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint; a list replaces the stored list. */
368
791
  declare const PocPatchSchema: z.ZodEffects<z.ZodObject<Omit<{
369
792
  user_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
370
793
  person_id: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
371
794
  display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
372
- email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
373
- phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
795
+ emails: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
796
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
797
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
798
+ }, "strict", z.ZodTypeAny, {
799
+ value: string;
800
+ is_preferred?: boolean | undefined;
801
+ }, {
802
+ value?: unknown;
803
+ is_preferred?: boolean | undefined;
804
+ }>, "many">, {
805
+ value: string;
806
+ is_preferred?: boolean | undefined;
807
+ }[], {
808
+ value?: unknown;
809
+ is_preferred?: boolean | undefined;
810
+ }[]>, {
811
+ value: string;
812
+ is_preferred: boolean;
813
+ }[], {
814
+ value?: unknown;
815
+ is_preferred?: boolean | undefined;
816
+ }[]>>;
817
+ phones: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
818
+ value: z.ZodType<string, z.ZodTypeDef, unknown>;
819
+ is_preferred: z.ZodOptional<z.ZodBoolean>;
820
+ }, "strict", z.ZodTypeAny, {
821
+ value: string;
822
+ is_preferred?: boolean | undefined;
823
+ }, {
824
+ value?: unknown;
825
+ is_preferred?: boolean | undefined;
826
+ }>, "many">, {
827
+ value: string;
828
+ is_preferred?: boolean | undefined;
829
+ }[], {
830
+ value?: unknown;
831
+ is_preferred?: boolean | undefined;
832
+ }[]>, {
833
+ value: string;
834
+ is_preferred: boolean;
835
+ }[], {
836
+ value?: unknown;
837
+ is_preferred?: boolean | undefined;
838
+ }[]>>;
374
839
  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
840
  urgent_methods: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
376
841
  is_primary: z.ZodOptional<z.ZodBoolean>;
377
842
  is_confidential: z.ZodOptional<z.ZodBoolean>;
378
843
  notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
379
844
  }, "user_id" | "person_id">, "strict", z.ZodTypeAny, {
380
- email?: string | null | undefined;
381
845
  display_name?: string | null | undefined;
382
- phone?: string | null | undefined;
846
+ emails?: {
847
+ value: string;
848
+ is_preferred: boolean;
849
+ }[] | undefined;
850
+ phones?: {
851
+ value: string;
852
+ is_preferred: boolean;
853
+ }[] | undefined;
383
854
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
384
855
  urgent_methods?: string[] | undefined;
385
856
  is_primary?: boolean | undefined;
386
857
  is_confidential?: boolean | undefined;
387
858
  notes?: string | null | undefined;
388
859
  }, {
389
- email?: string | null | undefined;
390
860
  display_name?: string | null | undefined;
391
- phone?: string | null | undefined;
861
+ emails?: {
862
+ value?: unknown;
863
+ is_preferred?: boolean | undefined;
864
+ }[] | undefined;
865
+ phones?: {
866
+ value?: unknown;
867
+ is_preferred?: boolean | undefined;
868
+ }[] | undefined;
392
869
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
393
870
  urgent_methods?: string[] | undefined;
394
871
  is_primary?: boolean | undefined;
395
872
  is_confidential?: boolean | undefined;
396
873
  notes?: string | null | undefined;
397
874
  }>, {
398
- email?: string | null | undefined;
399
875
  display_name?: string | null | undefined;
400
- phone?: string | null | undefined;
876
+ emails?: {
877
+ value: string;
878
+ is_preferred: boolean;
879
+ }[] | undefined;
880
+ phones?: {
881
+ value: string;
882
+ is_preferred: boolean;
883
+ }[] | undefined;
401
884
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
402
885
  urgent_methods?: string[] | undefined;
403
886
  is_primary?: boolean | undefined;
404
887
  is_confidential?: boolean | undefined;
405
888
  notes?: string | null | undefined;
406
889
  }, {
407
- email?: string | null | undefined;
408
890
  display_name?: string | null | undefined;
409
- phone?: string | null | undefined;
891
+ emails?: {
892
+ value?: unknown;
893
+ is_preferred?: boolean | undefined;
894
+ }[] | undefined;
895
+ phones?: {
896
+ value?: unknown;
897
+ is_preferred?: boolean | undefined;
898
+ }[] | undefined;
410
899
  purposes?: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[] | undefined;
411
900
  urgent_methods?: string[] | undefined;
412
901
  is_primary?: boolean | undefined;
@@ -414,6 +903,7 @@ declare const PocPatchSchema: z.ZodEffects<z.ZodObject<Omit<{
414
903
  notes?: string | null | undefined;
415
904
  }>;
416
905
  type PocPatch = z.infer<typeof PocPatchSchema>;
906
+ type PocPatchInput = z.input<typeof PocPatchSchema>;
417
907
  /**
418
908
  * A parsed patch without its `undefined` values. A key present as
419
909
  * `undefined` means "not edited": written through, the driver would store
@@ -423,16 +913,49 @@ declare function definedPatch<T extends Record<string, unknown>>(p: T): Partial<
423
913
  /** The stored document (Mongo's `_id` stripped). Readers parse every row with it. */
424
914
  declare const PointOfContactDocSchema: z.ZodObject<{
425
915
  id: z.ZodString;
426
- subject_type: z.ZodEnum<["agency", "org", "program", "team", "site", "service"]>;
916
+ subject_type: z.ZodEnum<["agency", "org", "program", "team", "location", "service"]>;
427
917
  subject_id: z.ZodString;
428
918
  agency_id: z.ZodNullable<z.ZodString>;
429
919
  org_id: z.ZodNullable<z.ZodString>;
430
920
  user_id: z.ZodNullable<z.ZodString>;
431
921
  person_id: z.ZodNullable<z.ZodString>;
432
922
  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>;
923
+ /** Lowercased emails, read leniently. Empty on a seat-linked contact (it resolves from the seat). */
924
+ emails: z.ZodEffects<z.ZodArray<z.ZodObject<{
925
+ value: z.ZodString;
926
+ } & {
927
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
928
+ }, "strip", z.ZodTypeAny, {
929
+ value: string;
930
+ is_preferred: boolean;
931
+ }, {
932
+ value: string;
933
+ is_preferred?: boolean | null | undefined;
934
+ }>, "many">, {
935
+ value: string;
936
+ is_preferred: boolean;
937
+ }[], {
938
+ value: string;
939
+ is_preferred?: boolean | null | undefined;
940
+ }[]>;
941
+ /** Read leniently. Empty on a seat-linked contact. */
942
+ phones: z.ZodEffects<z.ZodArray<z.ZodObject<{
943
+ value: z.ZodString;
944
+ } & {
945
+ is_preferred: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>, boolean, boolean | null | undefined>;
946
+ }, "strip", z.ZodTypeAny, {
947
+ value: string;
948
+ is_preferred: boolean;
949
+ }, {
950
+ value: string;
951
+ is_preferred?: boolean | null | undefined;
952
+ }>, "many">, {
953
+ value: string;
954
+ is_preferred: boolean;
955
+ }[], {
956
+ value: string;
957
+ is_preferred?: boolean | null | undefined;
958
+ }[]>;
436
959
  purposes: z.ZodArray<z.ZodEnum<["COMPLIANCE", "TRAINING", "REFERRALS_MAGIC_LINK", "BILLING", "DATA_REPORTING", "PROGRAM_CONTACT", "REFERRAL_CONTACT", "DIRECTOR"]>, "many">;
437
960
  /** CVC-185 codes. */
438
961
  urgent_methods: z.ZodArray<z.ZodString, "many">;
@@ -444,7 +967,7 @@ declare const PointOfContactDocSchema: z.ZodObject<{
444
967
  status: z.ZodEnum<["pending", "confirmed"]>;
445
968
  origin: z.ZodEnum<["survey", "admin_hub", "in_app", "steward_seed"]>;
446
969
  added_in_app: z.ZodNullable<z.ZodEnum<["pave", "thread", "leads", "platform"]>>;
447
- /** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<email>`, lowercased. */
970
+ /** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<preferred email>`, lowercased. */
448
971
  identity_key: z.ZodString;
449
972
  confirmed_by: z.ZodNullable<z.ZodString>;
450
973
  confirmed_at: z.ZodNullable<z.ZodString>;
@@ -457,16 +980,22 @@ declare const PointOfContactDocSchema: z.ZodObject<{
457
980
  updatedBy: z.ZodNullable<z.ZodString>;
458
981
  updatedAt: z.ZodString;
459
982
  }, "strip", z.ZodTypeAny, {
460
- email: string | null;
461
983
  status: "pending" | "confirmed";
462
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
984
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
463
985
  subject_id: string;
464
986
  agency_id: string | null;
465
987
  org_id: string | null;
466
988
  user_id: string | null;
467
989
  person_id: string | null;
468
990
  display_name: string | null;
469
- phone: string | null;
991
+ emails: {
992
+ value: string;
993
+ is_preferred: boolean;
994
+ }[];
995
+ phones: {
996
+ value: string;
997
+ is_preferred: boolean;
998
+ }[];
470
999
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
471
1000
  urgent_methods: string[];
472
1001
  is_primary: boolean;
@@ -487,16 +1016,22 @@ declare const PointOfContactDocSchema: z.ZodObject<{
487
1016
  updatedBy: string | null;
488
1017
  updatedAt: string;
489
1018
  }, {
490
- email: string | null;
491
1019
  status: "pending" | "confirmed";
492
- subject_type: "agency" | "org" | "program" | "team" | "site" | "service";
1020
+ subject_type: "agency" | "org" | "program" | "team" | "location" | "service";
493
1021
  subject_id: string;
494
1022
  agency_id: string | null;
495
1023
  org_id: string | null;
496
1024
  user_id: string | null;
497
1025
  person_id: string | null;
498
1026
  display_name: string | null;
499
- phone: string | null;
1027
+ emails: {
1028
+ value: string;
1029
+ is_preferred?: boolean | null | undefined;
1030
+ }[];
1031
+ phones: {
1032
+ value: string;
1033
+ is_preferred?: boolean | null | undefined;
1034
+ }[];
500
1035
  purposes: ("COMPLIANCE" | "TRAINING" | "REFERRALS_MAGIC_LINK" | "BILLING" | "DATA_REPORTING" | "PROGRAM_CONTACT" | "REFERRAL_CONTACT" | "DIRECTOR")[];
501
1036
  urgent_methods: string[];
502
1037
  is_primary: boolean;
@@ -519,7 +1054,7 @@ declare const PointOfContactDocSchema: z.ZodObject<{
519
1054
  }>;
520
1055
  type PointOfContactDoc = z.infer<typeof PointOfContactDocSchema>;
521
1056
  /** The fields the whole-contact rules read. */
522
- type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "email" | "phone" | "purposes">;
1057
+ type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails" | "phones" | "purposes">;
523
1058
  interface PocRuleViolation {
524
1059
  reason: "user_id_xor_person_id" | "seat_contact_has_own_reach" | "display_name_required" | "referral_contact_needs_email";
525
1060
  message: string;
@@ -530,8 +1065,13 @@ interface PocRuleViolation {
530
1065
  * read the seat. Returns every violation, empty when the contact is valid.
531
1066
  */
532
1067
  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;
1068
+ /**
1069
+ * The identity a subject's contacts are deduplicated by (canon `hubSavePocs`,
1070
+ * platform-prototype `src/agencyhub.jsx` @ 0fa04c1 L382-L384). A write-in keys
1071
+ * on its name and its PREFERRED email, so changing the preferred email changes
1072
+ * the key: the writer recomputes it on every edit.
1073
+ */
1074
+ declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails">): string;
535
1075
 
536
1076
  /**
537
1077
  * Point of contact read rules (pl-3r8). Pure, no I/O. Every reader (Thread,
@@ -562,6 +1102,19 @@ declare function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_i
562
1102
  * except the identity key, with the seat's reach resolved.
563
1103
  *
564
1104
  * Every view carries `purpose_labels` (hti-features `purpose_labels`, readOnly).
1105
+ *
1106
+ * ## Emails and phones (pl-e98)
1107
+ *
1108
+ * The owner and steward views carry the row's own `emails` / `phones` (what
1109
+ * the editor edits; empty on a seat-linked row) beside the resolved `seat`.
1110
+ * The network view carries the REACHABLE lists: the row's, or for a
1111
+ * seat-linked row the seat's single email and phone as one preferred entry
1112
+ * each. EVERY view also carries read-only `email` / `phone`: the reachable
1113
+ * preferred address (the row's preferred entry, or the seat's for a
1114
+ * seat-linked contact), the projections canon's card keeps of its preferred
1115
+ * entries (platform-prototype `src/agencyhub.jsx` @ 6f428116 L8195-L8202). A
1116
+ * reader that sends to or shows one address reads that projection. Views own
1117
+ * their lists: they are copies, never the row's arrays.
565
1118
  */
566
1119
 
567
1120
  /** A seat's reach, resolved by the reader from platform-db `users`. */
@@ -575,6 +1128,10 @@ interface PointOfContactStewardView extends Omit<PointOfContactDoc, "identity_ke
575
1128
  purpose_labels: string[];
576
1129
  /** The seat's reach for a seat-linked contact (null when unlinked or not found). */
577
1130
  seat: SeatReach | null;
1131
+ /** Read-only: the reachable preferred email (the seat's for a seat-linked contact), or null. */
1132
+ email: string | null;
1133
+ /** Read-only: the reachable preferred phone, or null. */
1134
+ phone: string | null;
578
1135
  }
579
1136
  /** The owner view: unmasked, without other organizations' actor ids. */
580
1137
  type PointOfContactOwnerView = Omit<PointOfContactStewardView, "createdBy" | "updatedBy" | "confirmed_by" | "deactivated_by" | "added_in_app">;
@@ -586,8 +1143,13 @@ interface PointOfContactNetworkView {
586
1143
  agency_id: string | null;
587
1144
  org_id: string | null;
588
1145
  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. */
1146
+ /** 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. */
1147
+ emails: PocContactEntry[];
1148
+ /** The row's phones, or the seat's phone as one preferred entry (the same rules as `emails`). */
1149
+ phones: PocContactEntry[];
1150
+ /** The preferred of `emails` (`preferredEmail(view)`), or null. The magic-link address. */
590
1151
  email: string | null;
1152
+ /** The preferred of `phones` (`preferredPhone(view)`), or null. */
591
1153
  phone: string | null;
592
1154
  purposes: ContactPurposeCode[];
593
1155
  purpose_labels: string[];
@@ -602,10 +1164,10 @@ declare class PointOfContactShapeError extends Error {
602
1164
  constructor(contactId: string | null, issues: string[]);
603
1165
  }
604
1166
  /**
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.
1167
+ * A stored row → the typed document. Strict: every writer (the platform's,
1168
+ * and the shared in-app add every app runs, `./writer.ts`) writes every
1169
+ * field, so a row that does not parse (an unknown origin or status, a missing
1170
+ * id) is a defect and FAILS LOUDLY rather than being read as some default.
609
1171
  */
610
1172
  declare function normalizePointOfContact(raw: Record<string, unknown>): PointOfContactDoc;
611
1173
  /** True when other organizations may see or use this contact. */
@@ -620,7 +1182,7 @@ declare function toOwnerView(d: PointOfContactDoc, seat?: SeatReach | null): Poi
620
1182
  * from `seat`.
621
1183
  */
622
1184
  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. */
1185
+ /** Reading order: the agency / org before its programs, teams and locations, primary first, then name, then id. */
624
1186
  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
1187
 
626
1188
  /**
@@ -658,7 +1220,7 @@ interface PocDbLike {
658
1220
  type SeatResolver = (userIds: readonly string[]) => Promise<ReadonlyMap<string, SeatReach>>;
659
1221
  /**
660
1222
  * 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
1223
+ * Program, team and location ids can be slugs two agencies share, so their reads
662
1224
  * REQUIRE `agency_id`. A service listing's contact names `agency_id` too:
663
1225
  * the listing org's genuine-mirror agency, or `null` for an org-only partner.
664
1226
  * Only agency and org subjects (whose ids are themselves unique) may omit it.
@@ -668,7 +1230,7 @@ type PocSubjectRef = {
668
1230
  subject_id: string;
669
1231
  agency_id?: string | null;
670
1232
  } | {
671
- subject_type: "program" | "team" | "site";
1233
+ subject_type: "program" | "team" | "location";
672
1234
  subject_id: string;
673
1235
  agency_id: string;
674
1236
  } | {
@@ -693,10 +1255,28 @@ interface PocPartnerSelector {
693
1255
  declare function listContactsForSubject(db: PocDbLike, subject: PocSubjectRef, opts?: {
694
1256
  resolveSeats?: SeatResolver;
695
1257
  }): Promise<PointOfContactNetworkView[]>;
696
- /** A referral recipient: a network-visible contact with a resolved email. */
1258
+ /**
1259
+ * A referral recipient: a network-visible contact with a resolved email, or
1260
+ * (only when asked, {@link ReferralContactsOptions.includeOwnPendingFor}) the
1261
+ * asking advocate's OWN pending in-app add, marked `pending: true` so a UI can
1262
+ * label it.
1263
+ */
697
1264
  type ReferralRecipient = PointOfContactNetworkView & {
698
1265
  email: string;
1266
+ pending?: true;
699
1267
  };
1268
+ interface ReferralContactsOptions {
1269
+ resolveSeats: SeatResolver;
1270
+ /**
1271
+ * The asking advocate's Auth0 `sub`, taken server-side from the verified
1272
+ * token (the same pinning as `mintPartnerContact`'s `actor.id`). When set,
1273
+ * the advocate's OWN pending in-app adds on the partner (`status: pending`,
1274
+ * active, `origin: in_app`, `createdBy` = this sub, tagged Referrals (magic
1275
+ * link), not confidential) are returned too, after the confirmed recipients
1276
+ * and marked `pending: true`. Nobody else's pending add is ever returned.
1277
+ */
1278
+ includeOwnPendingFor?: string;
1279
+ }
700
1280
  interface ReferralContactsResult {
701
1281
  /** One per distinct email, in reading order (the agency's own contacts first). */
702
1282
  recipients: ReferralRecipient[];
@@ -706,14 +1286,19 @@ interface ReferralContactsResult {
706
1286
  /**
707
1287
  * The partner's Referrals (magic link) contacts: every active, confirmed,
708
1288
  * 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
1289
+ * agency AND on its programs, teams and locations (the rollup, via the row's
710
1290
  * `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.
1291
+ * every one of them (Crysta 2026-08-23, restated 2026-10-14), at its PREFERRED
1292
+ * email (pl-e98; the view's `email`). The same email tagged on two subjects is
1293
+ * one recipient.
1294
+ *
1295
+ * With `includeOwnPendingFor` (Nate 2026-10-15), the advocate also sees their
1296
+ * own pending in-app adds on the partner, so a contact they just added can be
1297
+ * picked before HTI Labs confirms it (pending, marked, after the confirmed
1298
+ * recipients; an email a confirmed recipient already has is not repeated).
1299
+ * Confidential rows stay excluded.
713
1300
  */
714
- declare function listReferralContactsForPartner(db: PocDbLike, partner: PocPartnerSelector, opts: {
715
- resolveSeats: SeatResolver;
716
- }): Promise<ReferralContactsResult>;
1301
+ declare function listReferralContactsForPartner(db: PocDbLike, partner: PocPartnerSelector, opts: ReferralContactsOptions): Promise<ReferralContactsResult>;
717
1302
  /** One contact as other organizations see it, or null (absent or not network-visible). */
718
1303
  declare function getContact(db: PocDbLike, id: string, opts?: {
719
1304
  resolveSeats?: SeatResolver;
@@ -732,4 +1317,268 @@ declare function listPendingContacts(db: PocDbLike, opts?: {
732
1317
  resolveSeats?: SeatResolver;
733
1318
  }): Promise<PointOfContactStewardView[]>;
734
1319
 
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 };
1320
+ /**
1321
+ * The in-app partner add, shared (pl-bt1, pl-e98): an advocate in Thread, PAVE
1322
+ * or LEADS names a partner on a share and the contact they type lands in
1323
+ * platform-db `pointsofcontact` as a PENDING Point of contact tagged Referrals
1324
+ * (magic link). Every app runs THIS implementation against its own platform-db
1325
+ * handle; there is no HTTP hop. It is the platform's `addPartnerContact`
1326
+ * (platform `lib/points-of-contact/repository.ts`, the store behind
1327
+ * `POST /api/partner-contacts`) and the internals it uses from
1328
+ * `lib/points-of-contact/core.ts` (`resolveOwner` for an agency or org
1329
+ * subject, `insertContact`, the index set, the duplicate-key mapping) and
1330
+ * `lib/sharing-settings/recipient-id.ts` (`resolveRecipientId`), moved here
1331
+ * with the same rules, the same order of checks and the same refusal codes.
1332
+ *
1333
+ * ## What it does, in order
1334
+ *
1335
+ * 1. The actor names the advocate (`actor_required`), the app is one of
1336
+ * {@link POC_PARTNER_ADD_APPS} (`invalid_app`), the contact is a strict
1337
+ * {@link PocInAppSchema} body (`invalid_contact`), always tagged Referrals
1338
+ * (magic link) first.
1339
+ * 2. The partner is a strict {@link PartnerContactSelectorSchema} selector
1340
+ * (`invalid_partner`), resolved to its owner (decision D1): an agency in any
1341
+ * accepted form (`entity_id`, `id`, `_id` in either stored shape, a mapped
1342
+ * `registry_agencies` row) becomes `String(agencies._id)`; an org is
1343
+ * `String(organizations._id)`. An org whose org GENUINELY mirrors an
1344
+ * agency puts the contact on that agency (kickoff D1). Unresolved:
1345
+ * `owner_not_found`; an agency and org that are not one partner:
1346
+ * `owner_mismatch`. A canonical singleton org (`canonical_org`) or a PAVE
1347
+ * 2.0-shape org (`foreign_row_shape`) is refused.
1348
+ * 3. What already exists answers the add, looking only at rows the caller may
1349
+ * know about, matched on the package identity rule ({@link pocIdentityKey}:
1350
+ * `writein:<name>|<preferred email>`), never on a shared email: a visible
1351
+ * tagged contact, else the caller's own pending add (both `created:
1352
+ * false`, no write); the caller's own add that the partner removed is
1353
+ * refused (`contact_deactivated`).
1354
+ * 4. The caller's outstanding pending adds are capped per partner
1355
+ * ({@link POC_IN_APP_PENDING_CAP_PER_PARTNER}) and across the network
1356
+ * ({@link POC_IN_APP_PENDING_CAP_PER_ACTOR}): `too_many_pending_adds`.
1357
+ * 5. The row is inserted `pending`, `origin: in_app`, `added_in_app: <app>`,
1358
+ * version 1, after the whole-contact rules ({@link pocRuleViolations})
1359
+ * and the index check ({@link checkPocIndexes}: the writer never creates
1360
+ * an index; a missing one is `indexes_missing`, 503). A simultaneous
1361
+ * identical add that won the insert (`duplicate_pending_add`) answers with
1362
+ * the winner's row; an add that finds a cap exceeded after its insert
1363
+ * withdraws itself (429).
1364
+ *
1365
+ * ## The caller's part
1366
+ *
1367
+ * The full contract is the package README ("Caller contract"). In short:
1368
+ * `actor.id` is the advocate's Auth0 `sub`, taken server-side from the
1369
+ * verified token, never from a request body; `app` is the caller's own server
1370
+ * constant and the caller checks the advocate's `allowed_apps` for it; the
1371
+ * handle is the deployment's own platform-db, long-lived, reading from the
1372
+ * primary; `now` is never taken from a request. The platform's own write
1373
+ * guard (`read_only_registry`) is not here.
1374
+ *
1375
+ * ## No driver import, no logging
1376
+ *
1377
+ * Like the reads, the handle is typed structurally ({@link PocWriteDbLike}):
1378
+ * a `mongodb` `Db` or a mongoose connection's `.db` fits. The driver's
1379
+ * `ObjectId` class is passed in ({@link PocWriterDriver}): it builds the
1380
+ * ObjectId form of a 24-hex id (production `agencies._id` and
1381
+ * `organizations._id` are ObjectIds) and mints the `poc-<hex>` id. Nothing is
1382
+ * logged: a domain refusal is a returned code, never a throw, and no message
1383
+ * carries a stored value (a contact's email, a driver error's duplicate key).
1384
+ * A read or write ERROR (an outage, a stored row that does not parse,
1385
+ * `PointOfContactShapeError`) propagates.
1386
+ */
1387
+
1388
+ /** The slice of a driver cursor the writer uses. */
1389
+ interface PocWriteCursorLike {
1390
+ toArray(): Promise<unknown[]>;
1391
+ }
1392
+ /** One entry of a driver `indexes()` (`listIndexes`) listing. */
1393
+ interface PocIndexInfoLike {
1394
+ name?: unknown;
1395
+ key?: unknown;
1396
+ unique?: unknown;
1397
+ partialFilterExpression?: unknown;
1398
+ }
1399
+ /** The options the writer passes to `createIndex`. */
1400
+ interface PocCreateIndexOptions {
1401
+ name: string;
1402
+ unique?: boolean;
1403
+ partialFilterExpression?: Record<string, unknown>;
1404
+ }
1405
+ /** The slice of a driver `Collection` the writer uses. */
1406
+ interface PocWriteCollectionLike {
1407
+ find(filter: Record<string, unknown>, options?: Record<string, unknown>): PocWriteCursorLike;
1408
+ findOne(filter: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
1409
+ countDocuments(filter: Record<string, unknown>): Promise<number>;
1410
+ insertOne(doc: Record<string, unknown>): Promise<unknown>;
1411
+ deleteOne(filter: Record<string, unknown>): Promise<unknown>;
1412
+ /** Used by the platform's {@link ensurePocIndexes} only; the writer never creates an index. */
1413
+ createIndex(key: Record<string, 1 | -1>, options: PocCreateIndexOptions): Promise<unknown>;
1414
+ indexes(): Promise<PocIndexInfoLike[]>;
1415
+ }
1416
+ /** The slice of a driver `Db` the writer uses: a platform-db handle the caller may write. */
1417
+ interface PocWriteDbLike {
1418
+ collection(name: string): PocWriteCollectionLike;
1419
+ }
1420
+ /** The driver's ObjectId class (`mongodb`'s `ObjectId`, or `mongoose.Types.ObjectId`). */
1421
+ interface PocObjectIdClass {
1422
+ new (hex?: string): {
1423
+ toHexString(): string;
1424
+ };
1425
+ }
1426
+ /** What the writer needs from the caller's driver. */
1427
+ interface PocWriterDriver {
1428
+ ObjectId: PocObjectIdClass;
1429
+ }
1430
+ /** The apps an in-app add may come from: {@link POC_ADDED_IN_APPS} less `platform`. */
1431
+ type PocPartnerAddApp = Exclude<PocAddedInApp, "platform">;
1432
+ declare const POC_PARTNER_ADD_APPS: readonly PocPartnerAddApp[];
1433
+ /**
1434
+ * The partner the advocate picked or created, in the directory id universe
1435
+ * (D1): `agency_id` = `String(agencies._id)` or any form that resolves to it,
1436
+ * `org_id` = `String(organizations._id)`. One key, or both when they are a
1437
+ * genuine mirror pair. The same keys as `listReferralContactsForPartner`, so
1438
+ * an app writes and reads one partner the same way. Strict: a subject the
1439
+ * body picks is refused.
1440
+ */
1441
+ declare const PartnerContactSelectorSchema: z.ZodEffects<z.ZodObject<{
1442
+ agency_id: z.ZodOptional<z.ZodString>;
1443
+ org_id: z.ZodOptional<z.ZodString>;
1444
+ }, "strict", z.ZodTypeAny, {
1445
+ agency_id?: string | undefined;
1446
+ org_id?: string | undefined;
1447
+ }, {
1448
+ agency_id?: string | undefined;
1449
+ org_id?: string | undefined;
1450
+ }>, {
1451
+ agency_id?: string | undefined;
1452
+ org_id?: string | undefined;
1453
+ }, {
1454
+ agency_id?: string | undefined;
1455
+ org_id?: string | undefined;
1456
+ }>;
1457
+ type PartnerContactSelector = z.infer<typeof PartnerContactSelectorSchema>;
1458
+ type PartnerContactSelectorInput = z.input<typeof PartnerContactSelectorSchema>;
1459
+ /** Outstanding (pending, active) in-app adds one adder may have across the network. */
1460
+ declare const POC_IN_APP_PENDING_CAP_PER_ACTOR = 25;
1461
+ /** Outstanding (pending, active) in-app adds one adder may have on one partner. */
1462
+ declare const POC_IN_APP_PENDING_CAP_PER_PARTNER = 5;
1463
+ /**
1464
+ * One outstanding in-app add per adder, per subject and identity
1465
+ * ({@link POC_IN_APP_PENDING_INDEX_KEY}: the stored `identity_key`, name +
1466
+ * preferred email). Two simultaneous identical first adds race to the insert;
1467
+ * the loser's E11000 maps to `duplicate_pending_add`, which
1468
+ * {@link mintPartnerContact} answers with the winner's row: the index and the
1469
+ * matcher ({@link pocRowsWithIdentity}) use the same key, so the re-read always
1470
+ * finds the winner.
1471
+ *
1472
+ * Not keyed on emails: people share mailboxes (`intake@`), and a
1473
+ * "shares ANY email" rule (an interim 0.30.0 platform build, multikey on
1474
+ * `emails.value`) answered one person's add with another's row and let a
1475
+ * removed row block every later add sharing a secondary mailbox.
1476
+ */
1477
+ declare const POC_IN_APP_PENDING_INDEX: "pointsofcontact_inapp_pending_unique";
1478
+ /** The steward's review queue, paged oldest first (platform `listPendingContacts`). */
1479
+ declare const POC_PENDING_QUEUE_INDEX: "pointsofcontact_pending_queue";
1480
+ /**
1481
+ * FOR THE PLATFORM (its deploy or boot), never an app's writer: Thread and
1482
+ * PAVE hold no index privilege, and {@link mintPartnerContact} only checks
1483
+ * the indexes ({@link checkPocIndexes}). The platform must deploy and run this
1484
+ * before any app writes.
1485
+ *
1486
+ * Create the `pointsofcontact` indexes, the platform's full set: plain
1487
+ * `createIndex` calls, idempotent (memoized per handle, retried after a
1488
+ * failure; a failure propagates). No migration: no data or index existed
1489
+ * before 0.30.0. The partial unique indexes are the store's uniqueness rules:
1490
+ * no twin of one person among a subject's visible rows, at most one visible
1491
+ * primary per subject, and one outstanding in-app add per adder, subject and
1492
+ * identity ({@link POC_IN_APP_PENDING_INDEX}). Pass a long-lived handle: the
1493
+ * memo is keyed on it.
1494
+ */
1495
+ declare function ensurePocIndexes(db: PocWriteDbLike): Promise<void>;
1496
+ /**
1497
+ * Whether the indexes the writer relies on exist, read through `listIndexes`
1498
+ * (the writer never creates one: least privilege; the platform creates them
1499
+ * with {@link ensurePocIndexes}). Each required index must exist with exactly
1500
+ * its key (fields, order, direction), `unique: true` and exactly its partial
1501
+ * filter (under any name): `id` unique, and {@link POC_IN_APP_PENDING_INDEX}
1502
+ * (the race recovery and the dedupe depend on it). A missing collection
1503
+ * (NamespaceNotFound) or index refuses the write, `indexes_missing` (503):
1504
+ * fail closed. A pass is memoized per handle; a refusal is not, so the next
1505
+ * add re-checks. Any other read error propagates.
1506
+ */
1507
+ declare function checkPocIndexes(db: PocWriteDbLike): Promise<PartnerContactFailure | null>;
1508
+ /** Every refusal {@link mintPartnerContact} can return, as the platform route answers them. */
1509
+ 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"];
1510
+ type PartnerContactFailureReason = (typeof PARTNER_CONTACT_FAILURE_REASONS)[number];
1511
+ /**
1512
+ * A domain refusal: `status` is the HTTP status the platform route answers it
1513
+ * with, `reason` its code, `message` a fixed human sentence, or for
1514
+ * `invalid_contact` / `invalid_partner` the schema's issue list (paths and
1515
+ * rule messages). Never a stored value.
1516
+ */
1517
+ interface PartnerContactFailure {
1518
+ ok: false;
1519
+ status: 400 | 409 | 429 | 503;
1520
+ reason: PartnerContactFailureReason;
1521
+ message?: string;
1522
+ }
1523
+ /** What an in-app add returns to the app: the contact's id and status, never another org's contact details. */
1524
+ interface PartnerContactReceipt {
1525
+ id: string;
1526
+ status: PocStatus;
1527
+ /** False when an equivalent contact already existed and nothing was written. */
1528
+ created: boolean;
1529
+ /** Where the store put it: the partner's agency when the org has a genuine-mirror agency (kickoff D1), else the org. */
1530
+ subject_type: PocOwner["subject_type"];
1531
+ subject_id: string;
1532
+ agency_id: string | null;
1533
+ org_id: string | null;
1534
+ }
1535
+ type PartnerContactResult = {
1536
+ ok: true;
1537
+ value: PartnerContactReceipt;
1538
+ } | PartnerContactFailure;
1539
+ /**
1540
+ * The rows on the resolved subject with this identity ({@link pocIdentityKey},
1541
+ * as stored in `identity_key`), any status or activity: the same key as
1542
+ * {@link POC_IN_APP_PENDING_INDEX}, so a raced add always finds the row that
1543
+ * won. The index and this matcher must agree, which is why both live here.
1544
+ * A row that does not parse throws.
1545
+ */
1546
+ declare function pocRowsWithIdentity(db: PocDbLike, owner: Pick<PocOwner, "agency_id" | "subject_type" | "subject_id">, identityKey: string): Promise<PointOfContactDoc[]>;
1547
+ /**
1548
+ * A duplicate-key error → the refusal for the index it hit, or null when the
1549
+ * error is not a duplicate key (the caller rethrows). Mapped per index by
1550
+ * name, then by key pattern. The driver's message is never returned: it
1551
+ * echoes the duplicate key, i.e. the contact's email.
1552
+ */
1553
+ declare function pocDuplicateKeyFailure(err: unknown): PartnerContactFailure | null;
1554
+ /** Who is adding: the advocate. Never a steward here. */
1555
+ interface PocInAppActor {
1556
+ /**
1557
+ * The advocate's Auth0 `sub`, taken SERVER-SIDE from the verified token
1558
+ * (as the platform route takes `auth0Sub`), never from a request body or a
1559
+ * client-supplied header. Stored as `createdBy`; the adder's dedupe, caps and
1560
+ * removed-add refusal key on it.
1561
+ */
1562
+ id: string;
1563
+ }
1564
+ interface MintPartnerContactArgs {
1565
+ /** The app the advocate is adding from. */
1566
+ app: PocPartnerAddApp;
1567
+ /** The partner, by directory id ({@link PartnerContactSelectorSchema}). */
1568
+ partner: PartnerContactSelectorInput;
1569
+ /** The contact ({@link PocInAppSchema}: a name and at least one email; phones optional). */
1570
+ contact: PocInAppInput;
1571
+ actor: PocInAppActor;
1572
+ /** The mint time (`createdAt`); defaults to now. Server time only, never from a request. */
1573
+ now?: Date;
1574
+ }
1575
+ /**
1576
+ * The in-app partner add, written straight to platform-db (module comment).
1577
+ * Every argument is validated at run time as well as typed. Returns a
1578
+ * {@link PartnerContactReceipt} (`created: true` for a new pending row,
1579
+ * `false` when an equivalent contact answered and nothing was written) or a
1580
+ * {@link PartnerContactFailure}; never throws a domain refusal.
1581
+ */
1582
+ declare function mintPartnerContact(db: PocWriteDbLike, args: MintPartnerContactArgs, driver: PocWriterDriver): Promise<PartnerContactResult>;
1583
+
1584
+ export { CONTACT_PURPOSES, CONTACT_PURPOSE_CODES, type ContactPurpose, type ContactPurposeCode, 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, toNetworkView, toOwnerView, toStewardView };