@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.
@@ -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, site), for one or more purposes. It is a platform-wide record
6
- * on platform-db, not something created at first login (Crysta 2026-10-14,
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 email or phone of its own; they resolve
33
- * from the seat (L2561-L2563; Notion profile § 3 "A contact's phone and
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). For a seat-linked contact the seat must have one; the
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
- /** The platform-db collection. Platform is its only writer. */
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
- /** Index names. The platform writer creates them; readers rely on them. */
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); `site` → the site's id; `service` → the Service Listing's
144
- * `id` (a `servicelistings` row of `org_id`; `agency_id` null or the org's
145
- * genuine-mirror agency). The writer verifies membership;
146
- * `site` is refused until a site directory exists. Team and site ids may
147
- * be slugs two agencies share, so the subject is always read and keyed
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 === "site") && !o.agency_id) {
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
- email: PocEmailSchema.nullable().optional(),
186
- phone: text(40).nullable().optional(),
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 an email (the magic-link address), a
199
- * phone if known, tagged Referrals (magic link) unless the body says
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
- email: PocEmailSchema,
207
- phone: text(40).nullable().optional(),
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. Null on a seat-linked contact (it resolves from the seat). */
252
- email: nullableString,
253
- phone: nullableString,
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" | "email" | "phone" | "purposes">;
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.email || c.phone)) {
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) && !c.email) {
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
- /** The identity a subject's contacts are deduplicated by (canon `hubSavePocs`, platform-prototype `src/agencyhub.jsx` @ 0fa04c1 L382-L384). */
318
- export function pocIdentityKey(c: Pick<PointOfContactDoc, "user_id" | "person_id" | "display_name" | "email">): string {
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.email)}`;
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). The hti-features schema
47
- * (`udd-schemas/pointOfContact/PointOfContact.v1.json`) and the prototype CSV
48
- * spell `site` as `location`; the ruling's word is stored. `account` is not
49
- * accepted.
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", "site", "service"] as const;
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). */