@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.
- package/README.md +374 -1
- package/dist/points-of-contact/index.cjs +954 -30
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.d.cts +1062 -90
- package/dist/points-of-contact/index.d.ts +1062 -90
- package/dist/points-of-contact/index.js +926 -30
- package/dist/points-of-contact/index.js.map +1 -1
- package/package.json +1 -1
- package/src/pointsOfContact/__tests__/mongoDouble.ts +194 -0
- package/src/pointsOfContact/__tests__/pointsOfContact.test.ts +826 -26
- package/src/pointsOfContact/__tests__/reader.mongo.test.ts +211 -0
- package/src/pointsOfContact/__tests__/writer.mongo.test.ts +190 -0
- package/src/pointsOfContact/__tests__/writer.test.ts +782 -0
- package/src/pointsOfContact/index.ts +14 -7
- package/src/pointsOfContact/readRules.ts +81 -13
- package/src/pointsOfContact/reader.ts +409 -27
- package/src/pointsOfContact/schemas.ts +304 -34
- package/src/pointsOfContact/vocabulary.ts +44 -6
- package/src/pointsOfContact/writer.ts +967 -0
|
@@ -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).
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
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", "
|
|
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,
|
|
124
|
-
* on platform-db, not something
|
|
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
|
|
151
|
-
* from the seat (L2561-L2563; Notion profile
|
|
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)
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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); `
|
|
228
|
-
* `id` (a `servicelistings` row of `org_id`; `agency_id` null or
|
|
229
|
-
* genuine-mirror agency). The writer verifies membership;
|
|
230
|
-
* `
|
|
231
|
-
* be slugs two agencies share, so the subject is always read and
|
|
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", "
|
|
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" | "
|
|
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" | "
|
|
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" | "
|
|
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" | "
|
|
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
|
-
|
|
270
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
303
|
-
*
|
|
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
|
-
|
|
310
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
333
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
373
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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", "
|
|
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.
|
|
434
|
-
|
|
435
|
-
|
|
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" | "
|
|
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
|
-
|
|
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" | "
|
|
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
|
-
|
|
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" | "
|
|
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
|
-
/**
|
|
534
|
-
|
|
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
|
|
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:
|
|
606
|
-
* and
|
|
607
|
-
*
|
|
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
|
|
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
|
|
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" | "
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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)
|
|
712
|
-
* tagged on two subjects is
|
|
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
|
-
|
|
716
|
-
|
|
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
|
-
|
|
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 };
|