@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.
- package/README.md +268 -1
- package/dist/{index-Dr6GBCoY.d.ts → index-ClTjjJ_S.d.ts} +1 -1
- package/dist/{index-BTqHP4DM.d.cts → index-Pt82NxQg.d.cts} +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/points-of-contact/index.cjs +826 -21
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.d.cts +936 -87
- package/dist/points-of-contact/index.d.ts +936 -87
- package/dist/points-of-contact/index.js +799 -21
- package/dist/points-of-contact/index.js.map +1 -1
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/package.json +1 -1
- package/src/pointsOfContact/__tests__/mongoDouble.ts +194 -0
- package/src/pointsOfContact/__tests__/pointsOfContact.test.ts +379 -26
- package/src/pointsOfContact/__tests__/writer.mongo.test.ts +190 -0
- package/src/pointsOfContact/__tests__/writer.test.ts +782 -0
- package/src/pointsOfContact/index.ts +12 -7
- package/src/pointsOfContact/readRules.ts +73 -12
- package/src/pointsOfContact/reader.ts +75 -9
- package/src/pointsOfContact/schemas.ts +304 -34
- package/src/pointsOfContact/vocabulary.ts +40 -5
- package/src/pointsOfContact/writer.ts +967 -0
- package/dist/{cvcEntry-BqAGctqK.d.cts → cvcEntry-Asg7mxjB.d.cts} +8 -8
- package/dist/{cvcEntry-BqAGctqK.d.ts → cvcEntry-Asg7mxjB.d.ts} +8 -8
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
* Point of contact schemas and stored types (pl-3r8).
|
|
3
3
|
*
|
|
4
4
|
* A **Point of contact** is a reachable person FOR a subject (agency, org,
|
|
5
|
-
* program, team,
|
|
6
|
-
* on platform-db, not something
|
|
5
|
+
* program, team, location (shown "Site"), service listing), for one or more
|
|
6
|
+
* purposes. It is a platform-wide record on platform-db, not something
|
|
7
|
+
* created at first login (Crysta 2026-10-14,
|
|
7
8
|
* Slack D0811D2R6QN p1792036474007189). Columns follow the prototype directory
|
|
8
9
|
* (`Org + Personnel Registry/HTI_POINT_OF_CONTACT_DIRECTORY.csv` @ prototype
|
|
9
10
|
* 6c2db859 L1): `poc_id · subject_type · subject_id · user_id | person_id ·
|
|
@@ -11,6 +12,66 @@
|
|
|
11
12
|
* is_confidential · active · notes`. `poc_id` is stored as `id` (the
|
|
12
13
|
* hti-features schema's name).
|
|
13
14
|
*
|
|
15
|
+
* ## Emails and phones are lists (pl-e98, 0.30.0)
|
|
16
|
+
*
|
|
17
|
+
* The sheet's single `email` / `phone` columns became `emails[]` / `phones[]`
|
|
18
|
+
* of {@link PocContactEntry} `{ value, is_preferred }`, Crysta's 2026-08-24
|
|
19
|
+
* multi-entry correction. Canon's Admin Hub ledger keeps "every active email
|
|
20
|
+
* and phone as its own row, one preferred per type" (platform-prototype
|
|
21
|
+
* `src/agencyhub.jsx` @ 6f428116 L8096-L8106) and stores each as `{type,
|
|
22
|
+
* value, preferred}` (`methodsFor` L8107-L8132, the save L8181); on a Point of
|
|
23
|
+
* contact the type is the list the entry sits in. The flag is named after the
|
|
24
|
+
* CONTACT rail's `is_preferred` (prototype
|
|
25
|
+
* `leads-app/server/models/ObjectDirectoryEntry.mjs` @ fa0fd0b0 L52); the
|
|
26
|
+
* contact-level `is_primary` (the subject's primary contact) is unrelated and
|
|
27
|
+
* unchanged. No per-entry use label: CVC-154 `contact_info_use_type` is
|
|
28
|
+
* investigative-only and offered by no Platform, PAVE or Thread picker
|
|
29
|
+
* (prototype `data/cvcs/core_contact_info_use_type.yaml` @ fa0fd0b0 L93-L97).
|
|
30
|
+
*
|
|
31
|
+
* The single fields are GONE from the stored row and from every writer body
|
|
32
|
+
* (no prod data, clean cut; no read shim for stored single fields). Read the
|
|
33
|
+
* preferred address through {@link preferredEmail} / {@link preferredPhone};
|
|
34
|
+
* every view also carries read-only `email` / `phone` projections of the
|
|
35
|
+
* preferred entries, as canon's card does (L8195-L8202).
|
|
36
|
+
*
|
|
37
|
+
* The preferred rule. A WRITER list ({@link PocEmailListSchema} /
|
|
38
|
+
* {@link PocPhoneListSchema}) holds at most one entry marked `is_preferred`
|
|
39
|
+
* and is normalized to exactly one: the marked entry, else the FIRST (canon
|
|
40
|
+
* L8126-L8129). It refuses the same email twice or the same phone line twice
|
|
41
|
+
* (by digits, canon's `phoneDigits`, prototype
|
|
42
|
+
* `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
|
|
43
|
+
* L282-L286), and a phone with no digit. A phone is stored AS TYPED, trimmed,
|
|
44
|
+
* as this object's canon writer, the Admin Hub ledger, stores it
|
|
45
|
+
* (`agencyhub.jsx` @ 6f428116 L8124-L8125, L8173, L8511-L8518). An extension
|
|
46
|
+
* makes a distinct line: `402-677-3902 x5` and `402-677-3902` differ by
|
|
47
|
+
* digits, so both may sit on one contact. {@link formatPocPhone} is a
|
|
48
|
+
* DISPLAY-only helper readers apply (canon calls `formatPhone` "display
|
|
49
|
+
* only", L229-L245). A list in an edit replaces the stored list; `[]` clears
|
|
50
|
+
* it, `null` is refused.
|
|
51
|
+
*
|
|
52
|
+
* A STORED list is READ leniently ({@link PointOfContactDocSchema}): the same
|
|
53
|
+
* normalization repairs it (emails trimmed and lowercased, empty and duplicate
|
|
54
|
+
* entries dropped, a missing or null `is_preferred` read as false, no
|
|
55
|
+
* preferred → the first, several → the first marked), so one row's list
|
|
56
|
+
* never takes down a partner's whole read. Only structurally invalid data
|
|
57
|
+
* (not an array, a non-object entry, a non-string value, a non-boolean flag)
|
|
58
|
+
* throws.
|
|
59
|
+
*
|
|
60
|
+
* ## Known deviations (0.30.0)
|
|
61
|
+
*
|
|
62
|
+
* - A seat-linked contact still reads ONE email and ONE phone from `users`
|
|
63
|
+
* until a person Contact log exists (pl-9h4). Canon's motivating case
|
|
64
|
+
* (Crysta's own seat-linked contact) is therefore not yet met.
|
|
65
|
+
* - An entry is removed, not retired: canon's write-in ledger keeps retired
|
|
66
|
+
* entries stamped `retiredOn` (retire-not-remove, L8181-L8185); this list
|
|
67
|
+
* keeps only the live ones.
|
|
68
|
+
* - The write-in identity key uses the preferred email only
|
|
69
|
+
* ({@link pocIdentityKey}, as canon's `hubSavePocs` L382-L384 uses the card's flat
|
|
70
|
+
* email): changing the preferred email changes `identity_key`, and a
|
|
71
|
+
* secondary email shared with another row is not deduplicated. The writer
|
|
72
|
+
* maps an identity unique-index collision to a domain error (the
|
|
73
|
+
* platform's job).
|
|
74
|
+
*
|
|
14
75
|
* ## Shapes and trust levels
|
|
15
76
|
*
|
|
16
77
|
* - {@link PocOwnerSchema}: WHOSE contact it is. Resolved by the platform
|
|
@@ -29,13 +90,13 @@
|
|
|
29
90
|
* Checked on a mint and on the MERGED document of an edit:
|
|
30
91
|
* 1. `user_id` XOR `person_id` (prototype generator
|
|
31
92
|
* `tools/build_platform_directory.py` @ 6c2db859 L2556-L2557).
|
|
32
|
-
* 2. A seat-linked contact stores no
|
|
33
|
-
* from the seat (L2561-L2563; Notion profile
|
|
34
|
-
* email belong to the person").
|
|
93
|
+
* 2. A seat-linked contact stores no emails or phones of its own (both
|
|
94
|
+
* lists empty); they resolve from the seat (L2561-L2563; Notion profile
|
|
95
|
+
* § 3 "A contact's phone and email belong to the person").
|
|
35
96
|
* 3. A contact that is not seat-linked carries a `display_name` (L2571-L2572).
|
|
36
97
|
* 4. A contact tagged Referrals (magic link) has an email (Crysta
|
|
37
|
-
* 2026-10-14)
|
|
38
|
-
* writer checks the seat.
|
|
98
|
+
* 2026-10-14); the magic link goes to its preferred email. For a
|
|
99
|
+
* seat-linked contact the seat must have one; the writer checks the seat.
|
|
39
100
|
*/
|
|
40
101
|
|
|
41
102
|
import { z } from "zod";
|
|
@@ -50,10 +111,17 @@ import {
|
|
|
50
111
|
isPocUrgentMethodCode,
|
|
51
112
|
} from "./vocabulary.js";
|
|
52
113
|
|
|
53
|
-
/**
|
|
114
|
+
/**
|
|
115
|
+
* The platform-db collection. The platform writes it; the one exception is the
|
|
116
|
+
* in-app partner add, which every app writes through the shared
|
|
117
|
+
* `mintPartnerContact` (`./writer.ts`).
|
|
118
|
+
*/
|
|
54
119
|
export const POINTS_OF_CONTACT_COLLECTION = "pointsofcontact";
|
|
55
120
|
|
|
56
|
-
/**
|
|
121
|
+
/**
|
|
122
|
+
* Index names. `ensurePocIndexes` (`./writer.ts`) creates them, with the
|
|
123
|
+
* in-app pending and review-queue indexes; readers rely on them.
|
|
124
|
+
*/
|
|
57
125
|
export const POINT_OF_CONTACT_INDEXES = {
|
|
58
126
|
/** `{id}` unique. */
|
|
59
127
|
id: "pointsofcontact_id_unique",
|
|
@@ -78,6 +146,15 @@ export const POINT_OF_CONTACT_INDEXES = {
|
|
|
78
146
|
* pending add can never hold the slot.
|
|
79
147
|
*/
|
|
80
148
|
primary: "pointsofcontact_primary_unique",
|
|
149
|
+
/**
|
|
150
|
+
* `{agency_id, subject_type, subject_id, identity_key, createdBy}` unique
|
|
151
|
+
* where {@link POC_IN_APP_PENDING_INDEX_FILTER}: one outstanding in-app add
|
|
152
|
+
* per adder, subject and IDENTITY ({@link pocIdentityKey}: name + preferred
|
|
153
|
+
* email). See `POC_IN_APP_PENDING_INDEX`.
|
|
154
|
+
*/
|
|
155
|
+
inAppPending: "pointsofcontact_inapp_pending_unique",
|
|
156
|
+
/** `{status, createdAt, id}`: the steward's review queue, paged oldest first. */
|
|
157
|
+
pendingQueue: "pointsofcontact_pending_queue",
|
|
81
158
|
} as const;
|
|
82
159
|
|
|
83
160
|
/** The partial filter of {@link POINT_OF_CONTACT_INDEXES.identity}. */
|
|
@@ -86,6 +163,22 @@ export const POC_IDENTITY_INDEX_FILTER = { active: true, status: "confirmed" } a
|
|
|
86
163
|
/** The partial filter of {@link POINT_OF_CONTACT_INDEXES.primary}. */
|
|
87
164
|
export const POC_PRIMARY_INDEX_FILTER = { is_primary: true, active: true, status: "confirmed" } as const;
|
|
88
165
|
|
|
166
|
+
/** The partial filter of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: an outstanding in-app add. */
|
|
167
|
+
export const POC_IN_APP_PENDING_INDEX_FILTER = { status: "pending", origin: "in_app", active: true } as const;
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* The key of {@link POINT_OF_CONTACT_INDEXES.inAppPending}: the stored scalar
|
|
171
|
+
* `identity_key`. Never an email list: two people may share a mailbox
|
|
172
|
+
* (`intake@`), and an email-list key would merge them.
|
|
173
|
+
*/
|
|
174
|
+
export const POC_IN_APP_PENDING_INDEX_KEY = {
|
|
175
|
+
agency_id: 1,
|
|
176
|
+
subject_type: 1,
|
|
177
|
+
subject_id: 1,
|
|
178
|
+
identity_key: 1,
|
|
179
|
+
createdBy: 1,
|
|
180
|
+
} as const;
|
|
181
|
+
|
|
89
182
|
/** A caller-chosen id (seed path only): the hti-features `^poc-[a-z0-9_-]+$` pattern. */
|
|
90
183
|
export const POC_ID_PATTERN = /^poc-[a-z0-9_-]+$/;
|
|
91
184
|
|
|
@@ -115,6 +208,171 @@ const UrgentMethodsSchema = z
|
|
|
115
208
|
.max(3)
|
|
116
209
|
.transform((list) => [...new Set(list)]);
|
|
117
210
|
|
|
211
|
+
// ─── Email / phone entries ───────────────────────────────────────────
|
|
212
|
+
|
|
213
|
+
/** At most this many emails, and this many phones, on one contact. */
|
|
214
|
+
export const POC_MAX_CONTACT_ENTRIES = 10;
|
|
215
|
+
|
|
216
|
+
/** One stored email or phone entry. The single source of {@link PocContactEntry}. */
|
|
217
|
+
export const StoredContactEntrySchema = z.object({
|
|
218
|
+
/** An email (lowercased) or a phone as typed (trimmed). */
|
|
219
|
+
value: z.string(),
|
|
220
|
+
/** Exactly one entry of a non-empty list is the preferred one. */
|
|
221
|
+
is_preferred: z.boolean(),
|
|
222
|
+
});
|
|
223
|
+
/** One email or phone on a contact (pl-e98). */
|
|
224
|
+
export type PocContactEntry = z.infer<typeof StoredContactEntrySchema>;
|
|
225
|
+
|
|
226
|
+
/** An entry as READ: a missing or null flag is false (the first-entry rule then applies). */
|
|
227
|
+
const ReadContactEntrySchema = StoredContactEntrySchema.extend({
|
|
228
|
+
is_preferred: z
|
|
229
|
+
.boolean()
|
|
230
|
+
.nullish()
|
|
231
|
+
.transform((v) => v === true),
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* The line a phone value names: digits only, a leading US country code
|
|
236
|
+
* dropped. Canon's `phoneDigits` (prototype
|
|
237
|
+
* `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
|
|
238
|
+
* L282-L286), verbatim in behaviour.
|
|
239
|
+
*/
|
|
240
|
+
export function pocPhoneDigits(v: string): string {
|
|
241
|
+
const d = v.replace(/\D/g, "");
|
|
242
|
+
return d.length === 11 && d.charAt(0) === "1" ? d.slice(1) : d;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* DISPLAY only: how a reader may draw a stored phone. Canon's `formatPhone`
|
|
247
|
+
* (same file, L246-L256; "This is display only", L244), verbatim in
|
|
248
|
+
* behaviour: every non-digit is dropped, a redundant US `1` is dropped, and
|
|
249
|
+
* the digits are drawn `(AAA) BBB-CCCC`, or `+cc (AAA) BBB-CCCC` past ten
|
|
250
|
+
* digits. Empty when the value has no digit. Never written back: it is lossy
|
|
251
|
+
* (an extension becomes digits of the number, a short number draws oddly), so
|
|
252
|
+
* the store keeps the phone as typed.
|
|
253
|
+
*/
|
|
254
|
+
export function formatPocPhone(s: string): string {
|
|
255
|
+
let d = s.replace(/\D/g, "");
|
|
256
|
+
if (!d) return "";
|
|
257
|
+
if (d.length === 11 && d.charAt(0) === "1") d = d.slice(1);
|
|
258
|
+
if (d.length <= 3) return `(${d}`;
|
|
259
|
+
if (d.length <= 6) return `(${d.slice(0, 3)}) ${d.slice(3)}`;
|
|
260
|
+
if (d.length <= 10) return `(${d.slice(0, 3)}) ${d.slice(3, 6)}-${d.slice(6)}`;
|
|
261
|
+
const cc = d.slice(0, d.length - 10);
|
|
262
|
+
const r = d.slice(d.length - 10);
|
|
263
|
+
return `+${cc} (${r.slice(0, 3)}) ${r.slice(3, 6)}-${r.slice(6)}`;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
const emailKey = (v: string) => v.trim().toLowerCase();
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* The preferred rule on an already-clean list: exactly one preferred when
|
|
270
|
+
* non-empty, the first marked one, else the first entry.
|
|
271
|
+
*/
|
|
272
|
+
function settlePreferred(list: readonly PocContactEntry[]): PocContactEntry[] {
|
|
273
|
+
const at = list.findIndex((e) => e.is_preferred);
|
|
274
|
+
const keep = at < 0 ? 0 : at;
|
|
275
|
+
return list.map((e, i) => ({ value: e.value, is_preferred: i === keep }));
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** A stored list as READ: repaired, never refused (module comment). */
|
|
279
|
+
function readEntries(
|
|
280
|
+
list: readonly PocContactEntry[],
|
|
281
|
+
clean: (v: string) => string,
|
|
282
|
+
keyOf: (v: string) => string,
|
|
283
|
+
): PocContactEntry[] {
|
|
284
|
+
const seen = new Set<string>();
|
|
285
|
+
const out: PocContactEntry[] = [];
|
|
286
|
+
for (const e of list) {
|
|
287
|
+
const value = clean(e.value);
|
|
288
|
+
const k = value ? keyOf(value) : "";
|
|
289
|
+
if (!k || seen.has(k)) continue;
|
|
290
|
+
seen.add(k);
|
|
291
|
+
out.push({ value, is_preferred: e.is_preferred });
|
|
292
|
+
}
|
|
293
|
+
return settlePreferred(out);
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** Stored `emails`, read: trimmed, lowercased, empty and repeated entries dropped, one preferred. */
|
|
297
|
+
export const StoredEmailListSchema = z
|
|
298
|
+
.array(ReadContactEntrySchema)
|
|
299
|
+
.transform((l) => readEntries(l, emailKey, (v) => v));
|
|
300
|
+
|
|
301
|
+
/** Stored `phones`, read: trimmed, digitless and repeated lines dropped, one preferred. */
|
|
302
|
+
export const StoredPhoneListSchema = z
|
|
303
|
+
.array(ReadContactEntrySchema)
|
|
304
|
+
.transform((l) => readEntries(l, (v) => v.trim(), pocPhoneDigits));
|
|
305
|
+
|
|
306
|
+
/**
|
|
307
|
+
* A writer's list: at most one preferred, no repeated value; normalized so a
|
|
308
|
+
* non-empty list has exactly one preferred (the marked one, else the first).
|
|
309
|
+
*/
|
|
310
|
+
function entryListSchema(
|
|
311
|
+
value: z.ZodType<string, z.ZodTypeDef, unknown>,
|
|
312
|
+
keyOf: (v: string) => string,
|
|
313
|
+
noun: "email" | "phone",
|
|
314
|
+
) {
|
|
315
|
+
return z
|
|
316
|
+
.array(z.object({ value, is_preferred: z.boolean().optional() }).strict())
|
|
317
|
+
.max(POC_MAX_CONTACT_ENTRIES)
|
|
318
|
+
.superRefine((list, ctx) => {
|
|
319
|
+
if (list.filter((e) => e.is_preferred === true).length > 1) {
|
|
320
|
+
ctx.addIssue({ code: "custom", message: `A contact has at most one preferred ${noun}.` });
|
|
321
|
+
}
|
|
322
|
+
const seen = new Set<string>();
|
|
323
|
+
list.forEach((e, i) => {
|
|
324
|
+
const k = keyOf(e.value);
|
|
325
|
+
if (seen.has(k)) {
|
|
326
|
+
ctx.addIssue({
|
|
327
|
+
code: "custom",
|
|
328
|
+
path: [i, "value"],
|
|
329
|
+
message: `The same ${noun} appears twice on one contact.`,
|
|
330
|
+
});
|
|
331
|
+
}
|
|
332
|
+
seen.add(k);
|
|
333
|
+
});
|
|
334
|
+
})
|
|
335
|
+
.transform((list): PocContactEntry[] =>
|
|
336
|
+
settlePreferred(list.map((e) => ({ value: e.value, is_preferred: e.is_preferred === true }))),
|
|
337
|
+
);
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/** A writer's `emails`: lowercased addresses, at most one preferred, the first when none is marked. */
|
|
341
|
+
export const PocEmailListSchema = entryListSchema(PocEmailSchema, (v) => v, "email");
|
|
342
|
+
|
|
343
|
+
/** A phone as a writer sends it: trimmed, at least one digit, stored as typed. */
|
|
344
|
+
const PocPhoneValueSchema = text(40).refine((v) => /\d/.test(v), {
|
|
345
|
+
message: "A phone number has at least one digit.",
|
|
346
|
+
});
|
|
347
|
+
|
|
348
|
+
/** A writer's `phones`: as typed, one per line (by digits), at most one preferred, the first when none is marked. */
|
|
349
|
+
export const PocPhoneListSchema = entryListSchema(PocPhoneValueSchema, pocPhoneDigits, "phone");
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* The preferred entry of a list: the one marked `is_preferred`, else the
|
|
353
|
+
* first (the first-entry rule), else null for an empty or absent list.
|
|
354
|
+
*/
|
|
355
|
+
export function preferredContactEntry(
|
|
356
|
+
list: readonly PocContactEntry[] | null | undefined,
|
|
357
|
+
): PocContactEntry | null {
|
|
358
|
+
if (!list || list.length === 0) return null;
|
|
359
|
+
return list.find((e) => e.is_preferred) ?? list[0] ?? null;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* The contact's preferred email from its `emails`, or null. Takes a stored
|
|
364
|
+
* row or any view. On a stored seat-linked row it is null (the email is the
|
|
365
|
+
* seat's); a view's own `email` projection already resolves the seat.
|
|
366
|
+
*/
|
|
367
|
+
export function preferredEmail(c: { readonly emails: readonly PocContactEntry[] }): string | null {
|
|
368
|
+
return preferredContactEntry(c.emails)?.value ?? null;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** The contact's preferred phone, or null ({@link preferredEmail}'s rules). */
|
|
372
|
+
export function preferredPhone(c: { readonly phones: readonly PocContactEntry[] }): string | null {
|
|
373
|
+
return preferredContactEntry(c.phones)?.value ?? null;
|
|
374
|
+
}
|
|
375
|
+
|
|
118
376
|
// ─── Owner ───────────────────────────────────────────────────────────
|
|
119
377
|
|
|
120
378
|
/**
|
|
@@ -140,12 +398,12 @@ const UrgentMethodsSchema = z
|
|
|
140
398
|
* - `subject_id`: `agency` → `agency_id`; `org` → `org_id`; `program` →
|
|
141
399
|
* `organizations.programs[].programId` on the agency's genuine-mirror org;
|
|
142
400
|
* `team` → the team's `entity_id ?? id ?? String(_id)` (a `teams` row of
|
|
143
|
-
* that agency); `
|
|
144
|
-
* `id` (a `servicelistings` row of `org_id`; `agency_id` null or
|
|
145
|
-
* genuine-mirror agency). The writer verifies membership;
|
|
146
|
-
* `
|
|
147
|
-
* be slugs two agencies share, so the subject is always read and
|
|
148
|
-
* together with `agency_id`.
|
|
401
|
+
* that agency); `location` → the site's id; `service` → the Service
|
|
402
|
+
* Listing's `id` (a `servicelistings` row of `org_id`; `agency_id` null or
|
|
403
|
+
* the org's genuine-mirror agency). The writer verifies membership;
|
|
404
|
+
* `location` is refused until a location directory exists. Team and location
|
|
405
|
+
* ids may be slugs two agencies share, so the subject is always read and
|
|
406
|
+
* keyed together with `agency_id`.
|
|
149
407
|
*
|
|
150
408
|
* Every subject except an org-only partner resolves to an agency (canon stamps
|
|
151
409
|
* `agency_id` on the row: platform-prototype `src/agencyhub.jsx` @ 0fa04c1
|
|
@@ -166,7 +424,7 @@ export const PocOwnerSchema = z
|
|
|
166
424
|
if (o.subject_type === "org" && o.subject_id !== o.org_id) {
|
|
167
425
|
ctx.addIssue({ code: "custom", path: ["subject_id"], message: "An org's own contact names that org: subject_id must equal org_id." });
|
|
168
426
|
}
|
|
169
|
-
if ((o.subject_type === "program" || o.subject_type === "team" || o.subject_type === "
|
|
427
|
+
if ((o.subject_type === "program" || o.subject_type === "team" || o.subject_type === "location") && !o.agency_id) {
|
|
170
428
|
ctx.addIssue({ code: "custom", path: ["agency_id"], message: `A ${o.subject_type} contact names the agency it belongs to.` });
|
|
171
429
|
}
|
|
172
430
|
if (o.subject_type === "service" && !o.org_id) {
|
|
@@ -182,8 +440,8 @@ export const PocDetailsSchema = z
|
|
|
182
440
|
user_id: PocLinkIdSchema.nullable().optional(),
|
|
183
441
|
person_id: PocLinkIdSchema.nullable().optional(),
|
|
184
442
|
display_name: text(200).nullable().optional(),
|
|
185
|
-
|
|
186
|
-
|
|
443
|
+
emails: PocEmailListSchema.optional(),
|
|
444
|
+
phones: PocPhoneListSchema.optional(),
|
|
187
445
|
purposes: PurposesSchema.optional(),
|
|
188
446
|
urgent_methods: UrgentMethodsSchema.optional(),
|
|
189
447
|
is_primary: z.boolean().optional(),
|
|
@@ -192,38 +450,44 @@ export const PocDetailsSchema = z
|
|
|
192
450
|
})
|
|
193
451
|
.strict();
|
|
194
452
|
export type PocDetails = z.infer<typeof PocDetailsSchema>;
|
|
453
|
+
/** What a body builder sends (defaulted and normalized fields optional). */
|
|
454
|
+
export type PocDetailsInput = z.input<typeof PocDetailsSchema>;
|
|
195
455
|
|
|
196
456
|
/**
|
|
197
457
|
* An advocate's in-app add of a partner's contact (pl-bt1; Crysta 2026-10-14
|
|
198
|
-
* 23:25): a write-in with a name and
|
|
199
|
-
*
|
|
200
|
-
* otherwise. No seat or person link, no primary, no confidential flag, no
|
|
458
|
+
* 23:25): a write-in with a name and at least one email (the preferred one is
|
|
459
|
+
* the magic-link address), phones if known, tagged Referrals (magic link) unless
|
|
460
|
+
* the body says otherwise. No seat or person link, no primary, no confidential flag, no
|
|
201
461
|
* notes: those are the subject's own to set.
|
|
202
462
|
*/
|
|
203
463
|
export const PocInAppSchema = z
|
|
204
464
|
.object({
|
|
205
465
|
display_name: text(200),
|
|
206
|
-
|
|
207
|
-
|
|
466
|
+
emails: PocEmailListSchema.refine((l) => l.length > 0, { message: "An in-app add names at least one email." }),
|
|
467
|
+
phones: PocPhoneListSchema.optional(),
|
|
208
468
|
purposes: PurposesSchema.default([REFERRALS_MAGIC_LINK_PURPOSE]),
|
|
209
469
|
urgent_methods: UrgentMethodsSchema.optional(),
|
|
210
470
|
})
|
|
211
471
|
.strict();
|
|
212
472
|
export type PocInApp = z.infer<typeof PocInAppSchema>;
|
|
473
|
+
/** The `POST /api/partner-contacts` body a caller sends (`purposes` defaulted). */
|
|
474
|
+
export type PocInAppInput = z.input<typeof PocInAppSchema>;
|
|
213
475
|
|
|
214
476
|
/** A seed row: the details plus the sheet's own `poc-*` id. */
|
|
215
477
|
export const PocSeedSchema = PocDetailsSchema.extend({
|
|
216
478
|
id: z.string().trim().regex(POC_ID_PATTERN, "A seeded contact id is poc-<lowercase letters, digits, '_' or '-'>."),
|
|
217
479
|
}).strict();
|
|
218
480
|
export type PocSeed = z.infer<typeof PocSeedSchema>;
|
|
481
|
+
export type PocSeedInput = z.input<typeof PocSeedSchema>;
|
|
219
482
|
|
|
220
|
-
/** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint. */
|
|
483
|
+
/** An edit: at least one field; identity (`user_id`, `person_id`) is fixed at mint; a list replaces the stored list. */
|
|
221
484
|
export const PocPatchSchema = PocDetailsSchema.omit({ user_id: true, person_id: true })
|
|
222
485
|
.strict()
|
|
223
486
|
.refine((b) => Object.values(b).some((v) => v !== undefined), {
|
|
224
487
|
message: "A contact edit must name at least one field.",
|
|
225
488
|
});
|
|
226
489
|
export type PocPatch = z.infer<typeof PocPatchSchema>;
|
|
490
|
+
export type PocPatchInput = z.input<typeof PocPatchSchema>;
|
|
227
491
|
|
|
228
492
|
/**
|
|
229
493
|
* A parsed patch without its `undefined` values. A key present as
|
|
@@ -248,9 +512,10 @@ export const PointOfContactDocSchema = z.object({
|
|
|
248
512
|
user_id: nullableString,
|
|
249
513
|
person_id: nullableString,
|
|
250
514
|
display_name: nullableString,
|
|
251
|
-
/** Lowercased.
|
|
252
|
-
|
|
253
|
-
|
|
515
|
+
/** Lowercased emails, read leniently. Empty on a seat-linked contact (it resolves from the seat). */
|
|
516
|
+
emails: StoredEmailListSchema,
|
|
517
|
+
/** Read leniently. Empty on a seat-linked contact. */
|
|
518
|
+
phones: StoredPhoneListSchema,
|
|
254
519
|
purposes: z.array(z.enum(CONTACT_PURPOSE_CODES)),
|
|
255
520
|
/** CVC-185 codes. */
|
|
256
521
|
urgent_methods: z.array(z.string()),
|
|
@@ -262,7 +527,7 @@ export const PointOfContactDocSchema = z.object({
|
|
|
262
527
|
status: z.enum(POC_STATUSES),
|
|
263
528
|
origin: z.enum(POC_ORIGINS),
|
|
264
529
|
added_in_app: z.enum(POC_ADDED_IN_APPS).nullable(),
|
|
265
|
-
/** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<email>`, lowercased. */
|
|
530
|
+
/** `seat:<user_id>` · `person:<person_id>` · `writein:<name>|<preferred email>`, lowercased. */
|
|
266
531
|
identity_key: z.string().min(1),
|
|
267
532
|
confirmed_by: nullableString,
|
|
268
533
|
confirmed_at: nullableString,
|
|
@@ -278,7 +543,7 @@ export const PointOfContactDocSchema = z.object({
|
|
|
278
543
|
export type PointOfContactDoc = z.infer<typeof PointOfContactDocSchema>;
|
|
279
544
|
|
|
280
545
|
/** The fields the whole-contact rules read. */
|
|
281
|
-
export type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "
|
|
546
|
+
export type PocRuleInput = Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails" | "phones" | "purposes">;
|
|
282
547
|
|
|
283
548
|
export interface PocRuleViolation {
|
|
284
549
|
reason: "user_id_xor_person_id" | "seat_contact_has_own_reach" | "display_name_required" | "referral_contact_needs_email";
|
|
@@ -296,7 +561,7 @@ export function pocRuleViolations(c: PocRuleInput): PocRuleViolation[] {
|
|
|
296
561
|
if (c.user_id && c.person_id) {
|
|
297
562
|
out.push({ reason: "user_id_xor_person_id", message: "A contact points at a seat (user_id) or a person (person_id), never both." });
|
|
298
563
|
}
|
|
299
|
-
if (seat && (c.
|
|
564
|
+
if (seat && (c.emails.length > 0 || c.phones.length > 0)) {
|
|
300
565
|
out.push({
|
|
301
566
|
reason: "seat_contact_has_own_reach",
|
|
302
567
|
message: "A seat-linked contact stores no email or phone of its own; they resolve from the seat.",
|
|
@@ -305,7 +570,7 @@ export function pocRuleViolations(c: PocRuleInput): PocRuleViolation[] {
|
|
|
305
570
|
if (!seat && !c.display_name) {
|
|
306
571
|
out.push({ reason: "display_name_required", message: "A contact that holds no seat needs a display_name." });
|
|
307
572
|
}
|
|
308
|
-
if (!seat && c.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE) &&
|
|
573
|
+
if (!seat && c.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE) && c.emails.length === 0) {
|
|
309
574
|
out.push({
|
|
310
575
|
reason: "referral_contact_needs_email",
|
|
311
576
|
message: "A contact tagged Referrals (magic link) must have an email.",
|
|
@@ -314,10 +579,15 @@ export function pocRuleViolations(c: PocRuleInput): PocRuleViolation[] {
|
|
|
314
579
|
return out;
|
|
315
580
|
}
|
|
316
581
|
|
|
317
|
-
/**
|
|
318
|
-
|
|
582
|
+
/**
|
|
583
|
+
* The identity a subject's contacts are deduplicated by (canon `hubSavePocs`,
|
|
584
|
+
* platform-prototype `src/agencyhub.jsx` @ 0fa04c1 L382-L384). A write-in keys
|
|
585
|
+
* on its name and its PREFERRED email, so changing the preferred email changes
|
|
586
|
+
* the key: the writer recomputes it on every edit.
|
|
587
|
+
*/
|
|
588
|
+
export function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "emails">): string {
|
|
319
589
|
const norm = (v: string | null) => (v ?? "").trim().toLowerCase();
|
|
320
590
|
if (c.user_id) return `seat:${norm(c.user_id)}`;
|
|
321
591
|
if (c.person_id) return `person:${norm(c.person_id)}`;
|
|
322
|
-
return `writein:${norm(c.display_name)}|${norm(c
|
|
592
|
+
return `writein:${norm(c.display_name)}|${norm(preferredEmail(c))}`;
|
|
323
593
|
}
|
|
@@ -43,10 +43,22 @@ import type { PreferredContactMethodKey } from "../generated/cvc-enums.js";
|
|
|
43
43
|
* in-app add "creates the organization and a contact", canon `hubSavePocs`
|
|
44
44
|
* stamping an empty `agency_id` when it has none (platform-prototype
|
|
45
45
|
* `src/agencyhub.jsx` @ 0fa04c1 L411), and the Notion draft's proposed `org`
|
|
46
|
-
* subject (§ 5).
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
46
|
+
* subject (§ 5). `account` is not accepted.
|
|
47
|
+
*
|
|
48
|
+
* ## `location` is stored; "Site" is displayed (pl-f4c, 0.30.0)
|
|
49
|
+
*
|
|
50
|
+
* The UDD names the object Site (since 2026-10-04), but its stored names, ids
|
|
51
|
+
* and columns stay `location`: the schema of record is hti-features
|
|
52
|
+
* `udd-schemas/location/Location.v1.json`, and the POC draft enum is
|
|
53
|
+
* `agency | program | location | team`. Canon stores `location` everywhere:
|
|
54
|
+
* the POC directory columns (prototype
|
|
55
|
+
* `docs/leads-platform/ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 L236,
|
|
56
|
+
* "subject_type (agency · program · location · team)"), the registry kind
|
|
57
|
+
* (`leads-app/server/models/RegistryEntities.mjs` @ fa0fd0b0 L105-L117) and
|
|
58
|
+
* the object-log subject enum (`leads-app/server/models/ObjectDirectoryEntry.mjs`
|
|
59
|
+
* @ fa0fd0b0 L51). So the stored value is `location` and the display word is
|
|
60
|
+
* {@link pocSubjectTypeLabel}'s "Site". 0.28.0 stored `site`; there is no prod
|
|
61
|
+
* data, so `site` is simply refused (no legacy acceptance, no migration).
|
|
50
62
|
*
|
|
51
63
|
* `service` is a Service Listing's contact (Crysta's kickoff D4, prototype
|
|
52
64
|
* `KICKOFF_SERVICE_LISTING_AND_PARTNER_CONTACT_BUILD_2026-10-14.md` @ c6380f73
|
|
@@ -58,9 +70,32 @@ import type { PreferredContactMethodKey } from "../generated/cvc-enums.js";
|
|
|
58
70
|
* else the org"); the platform writer rewrites an `org` subject whose org
|
|
59
71
|
* genuinely mirrors an agency to that agency.
|
|
60
72
|
*/
|
|
61
|
-
export const POC_SUBJECT_TYPES = ["agency", "org", "program", "team", "
|
|
73
|
+
export const POC_SUBJECT_TYPES = ["agency", "org", "program", "team", "location", "service"] as const;
|
|
62
74
|
export type PocSubjectType = (typeof POC_SUBJECT_TYPES)[number];
|
|
63
75
|
|
|
76
|
+
/**
|
|
77
|
+
* The display word for each subject type: the object names of prototype
|
|
78
|
+
* `docs/leads-platform/ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 § 1
|
|
79
|
+
* (L60-L68: Org · Agency · Program / department · Team · Service listing),
|
|
80
|
+
* with `location` shown as "Site", the UDD's object name since 2026-10-04
|
|
81
|
+
* (pl-f4c). Store the code, render the label.
|
|
82
|
+
*/
|
|
83
|
+
export const POC_SUBJECT_TYPE_LABELS: Readonly<Record<PocSubjectType, string>> = {
|
|
84
|
+
agency: "Agency",
|
|
85
|
+
org: "Org",
|
|
86
|
+
program: "Program",
|
|
87
|
+
team: "Team",
|
|
88
|
+
location: "Site",
|
|
89
|
+
service: "Service listing",
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
/** The display word of a subject type; an unknown type reads as itself. */
|
|
93
|
+
export function pocSubjectTypeLabel(type: string): string {
|
|
94
|
+
return Object.hasOwn(POC_SUBJECT_TYPE_LABELS, type)
|
|
95
|
+
? POC_SUBJECT_TYPE_LABELS[type as PocSubjectType]
|
|
96
|
+
: type;
|
|
97
|
+
}
|
|
98
|
+
|
|
64
99
|
// ─── Purposes ────────────────────────────────────────────────────────
|
|
65
100
|
|
|
66
101
|
/** The declared purpose codes (prototype `data/contact_purposes.yaml` @ 6c2db859 L11-L33). */
|