@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.
@@ -1,16 +1,23 @@
1
1
  /**
2
2
  * @htilabs/platform-common-models/points-of-contact
3
3
  *
4
- * The Point of contact READ contract (pl-3r8): the platform-db
5
- * `pointsofcontact` collection's vocabularies, Zod schemas, stored and view
6
- * types, read rules (network vs owner view, confidential exclusion, the
7
- * Referrals (magic link) partner rollup) and raw-driver reads. Pure
8
- * TypeScript, no mongoose, no driver import. The platform app is the only
9
- * writer (`platform lib/points-of-contact/`); Thread, PAVE and LEADS read
10
- * through this module. Subpath only (not re-exported from the package root).
4
+ * The Point of contact contract (pl-3r8): the platform-db `pointsofcontact`
5
+ * collection's vocabularies, Zod schemas, stored and view types, read rules
6
+ * (network vs owner view, confidential exclusion, the Referrals (magic link)
7
+ * partner rollup with its confidential-holder count and send-only
8
+ * `resolveMagicLinkRecipients` / `ConfidentialReferralRecipients`, pl-iza)
9
+ * and raw-driver reads, plus the ONE shared writer every app
10
+ * runs: the in-app partner add (`mintPartnerContact`, pl-bt1) and the index
11
+ * set it relies on (`ensurePocIndexes`). Pure TypeScript, no mongoose, no
12
+ * driver import. The platform app owns every other write (its own Admin Hub,
13
+ * survey, edits, confirm, seed: `platform lib/points-of-contact/`); Thread,
14
+ * PAVE and LEADS read through this module and write a pending in-app add
15
+ * through it directly, without an HTTP hop. Subpath only (not re-exported from
16
+ * the package root).
11
17
  */
12
18
 
13
19
  export * from "./vocabulary.js";
14
20
  export * from "./schemas.js";
15
21
  export * from "./readRules.js";
16
22
  export * from "./reader.js";
23
+ export * from "./writer.js";
@@ -15,7 +15,14 @@
15
15
  * `Org + Personnel Registry/DIRECTORY_CSV_EDITING_GUIDE.md` @ 6c2db859
16
16
  * § 0.9 L958; hti-features `PointOfContact.v1.json` `is_confidential`:
17
17
  * "Never publish this contact"), so it is left out entirely rather
18
- * than masked;
18
+ * than masked. The network view is unchanged by pl-iza (0.32.0):
19
+ * confidential rows are absent from every view another organization
20
+ * sees (this view, `getContact`, `listContactsForSubject`, the
21
+ * referral `recipients`; only the subject's owner and the steward see
22
+ * them). A confidential Referrals (magic link) holder still receives
23
+ * the magic link, but only through the send-only
24
+ * `resolveMagicLinkRecipients` (`./reader.ts`), which never projects
25
+ * the row and exposes a count;
19
26
  * - the seat / person links, `notes`, review stamps, actor ids and the
20
27
  * identity key are not projected.
21
28
  * - **Owner view** ({@link toOwnerView}): the subject's own editor (Admin
@@ -27,9 +34,27 @@
27
34
  * except the identity key, with the seat's reach resolved.
28
35
  *
29
36
  * Every view carries `purpose_labels` (hti-features `purpose_labels`, readOnly).
37
+ *
38
+ * ## Emails and phones (pl-e98)
39
+ *
40
+ * The owner and steward views carry the row's own `emails` / `phones` (what
41
+ * the editor edits; empty on a seat-linked row) beside the resolved `seat`.
42
+ * The network view carries the REACHABLE lists: the row's, or for a
43
+ * seat-linked row the seat's single email and phone as one preferred entry
44
+ * each. EVERY view also carries read-only `email` / `phone`: the reachable
45
+ * preferred address (the row's preferred entry, or the seat's for a
46
+ * seat-linked contact), the projections canon's card keeps of its preferred
47
+ * entries (platform-prototype `src/agencyhub.jsx` @ 6f428116 L8195-L8202). A
48
+ * reader that sends to or shows one address reads that projection. Views own
49
+ * their lists: they are copies, never the row's arrays.
30
50
  */
31
51
 
32
- import { PointOfContactDocSchema, type PointOfContactDoc } from "./schemas.js";
52
+ import {
53
+ PointOfContactDocSchema,
54
+ preferredContactEntry,
55
+ type PocContactEntry,
56
+ type PointOfContactDoc,
57
+ } from "./schemas.js";
33
58
  import { contactPurposeLabel, type ContactPurposeCode, type PocSubjectType } from "./vocabulary.js";
34
59
 
35
60
  /** A seat's reach, resolved by the reader from platform-db `users`. */
@@ -44,6 +69,10 @@ export interface PointOfContactStewardView extends Omit<PointOfContactDoc, "iden
44
69
  purpose_labels: string[];
45
70
  /** The seat's reach for a seat-linked contact (null when unlinked or not found). */
46
71
  seat: SeatReach | null;
72
+ /** Read-only: the reachable preferred email (the seat's for a seat-linked contact), or null. */
73
+ email: string | null;
74
+ /** Read-only: the reachable preferred phone, or null. */
75
+ phone: string | null;
47
76
  }
48
77
 
49
78
  /** The owner view: unmasked, without other organizations' actor ids. */
@@ -60,8 +89,13 @@ export interface PointOfContactNetworkView {
60
89
  agency_id: string | null;
61
90
  org_id: string | null;
62
91
  display_name: string | null;
63
- /** The row's email, or the seat's when the contact is seat-linked and a seat resolver was given. */
92
+ /** 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. */
93
+ emails: PocContactEntry[];
94
+ /** The row's phones, or the seat's phone as one preferred entry (the same rules as `emails`). */
95
+ phones: PocContactEntry[];
96
+ /** The preferred of `emails` (`preferredEmail(view)`), or null. The magic-link address. */
64
97
  email: string | null;
98
+ /** The preferred of `phones` (`preferredPhone(view)`), or null. */
65
99
  phone: string | null;
66
100
  purposes: ContactPurposeCode[];
67
101
  purpose_labels: string[];
@@ -82,10 +116,10 @@ export class PointOfContactShapeError extends Error {
82
116
  }
83
117
 
84
118
  /**
85
- * A stored row → the typed document. Strict: the platform is the only writer
86
- * and writes every field, so a row that does not parse (an unknown origin or
87
- * status, a missing id) is a defect and FAILS LOUDLY rather than being read as
88
- * some default.
119
+ * A stored row → the typed document. Strict: every writer (the platform's,
120
+ * and the shared in-app add every app runs, `./writer.ts`) writes every
121
+ * field, so a row that does not parse (an unknown origin or status, a missing
122
+ * id) is a defect and FAILS LOUDLY rather than being read as some default.
89
123
  */
90
124
  export function normalizePointOfContact(raw: Record<string, unknown>): PointOfContactDoc {
91
125
  const parsed = PointOfContactDocSchema.safeParse(raw);
@@ -101,16 +135,47 @@ export function isNetworkVisible(d: Pick<PointOfContactDoc, "active" | "status"
101
135
  return d.active && d.status === "confirmed" && !d.is_confidential;
102
136
  }
103
137
 
138
+ const copyEntries = (list: readonly PocContactEntry[]): PocContactEntry[] =>
139
+ list.map((e) => ({ ...e }));
140
+
141
+ /**
142
+ * Where the contact is reached: the row's own lists, or for a seat-linked row
143
+ * the seat's email (trimmed, lowercased) and phone as one preferred entry
144
+ * each. Always fresh arrays.
145
+ */
146
+ function reachOf(
147
+ d: PointOfContactDoc,
148
+ seat: SeatReach | null | undefined,
149
+ ): { emails: PocContactEntry[]; phones: PocContactEntry[] } {
150
+ if (!d.user_id) return { emails: copyEntries(d.emails), phones: copyEntries(d.phones) };
151
+ const one = (v: string | null | undefined): PocContactEntry[] =>
152
+ v ? [{ value: v, is_preferred: true }] : [];
153
+ return {
154
+ emails: one(seat?.email?.trim().toLowerCase()),
155
+ phones: one(seat?.phone?.trim()),
156
+ };
157
+ }
158
+
159
+ const preferredValue = (list: readonly PocContactEntry[]): string | null =>
160
+ preferredContactEntry(list)?.value ?? null;
161
+
104
162
  /** The steward view. */
105
163
  export function toStewardView(
106
164
  d: PointOfContactDoc,
107
165
  seat?: SeatReach | null,
108
166
  ): PointOfContactStewardView {
109
167
  const { identity_key: _internal, ...rest } = d;
168
+ const reach = reachOf(d, seat);
110
169
  return {
111
170
  ...rest,
171
+ emails: copyEntries(d.emails),
172
+ phones: copyEntries(d.phones),
173
+ purposes: [...d.purposes],
174
+ urgent_methods: [...d.urgent_methods],
112
175
  purpose_labels: d.purposes.map(contactPurposeLabel),
113
176
  seat: d.user_id ? (seat ?? null) : null,
177
+ email: preferredValue(reach.emails),
178
+ phone: preferredValue(reach.phones),
114
179
  };
115
180
  }
116
181
 
@@ -141,6 +206,7 @@ export function toNetworkView(
141
206
  ): PointOfContactNetworkView | null {
142
207
  if (!isNetworkVisible(d)) return null;
143
208
  const seatLinked = !!d.user_id;
209
+ const { emails, phones } = reachOf(d, seat);
144
210
  return {
145
211
  id: d.id,
146
212
  subject_type: d.subject_type,
@@ -148,11 +214,13 @@ export function toNetworkView(
148
214
  agency_id: d.agency_id,
149
215
  org_id: d.org_id,
150
216
  display_name: d.display_name ?? (seatLinked ? (seat?.name ?? null) : null),
151
- email: seatLinked ? (seat?.email ? seat.email.toLowerCase() : null) : d.email,
152
- phone: seatLinked ? (seat?.phone ?? null) : d.phone,
153
- purposes: d.purposes,
217
+ emails,
218
+ phones,
219
+ email: preferredValue(emails),
220
+ phone: preferredValue(phones),
221
+ purposes: [...d.purposes],
154
222
  purpose_labels: d.purposes.map(contactPurposeLabel),
155
- urgent_methods: d.urgent_methods,
223
+ urgent_methods: [...d.urgent_methods],
156
224
  is_primary: d.is_primary,
157
225
  updatedAt: d.updatedAt,
158
226
  };
@@ -163,11 +231,11 @@ const SUBJECT_ORDER: Record<PocSubjectType, number> = {
163
231
  org: 1,
164
232
  program: 2,
165
233
  team: 3,
166
- site: 4,
234
+ location: 4,
167
235
  service: 5,
168
236
  };
169
237
 
170
- /** Reading order: the agency / org before its programs, teams and sites, primary first, then name, then id. */
238
+ /** Reading order: the agency / org before its programs, teams and locations, primary first, then name, then id. */
171
239
  export function byContactReadingOrder(
172
240
  a: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">,
173
241
  b: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">,