@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.
@@ -1,16 +1,21 @@
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) and raw-driver reads, plus the ONE shared writer every app
8
+ * runs: the in-app partner add (`mintPartnerContact`, pl-bt1) and the index
9
+ * set it relies on (`ensurePocIndexes`). Pure TypeScript, no mongoose, no
10
+ * driver import. The platform app owns every other write (its own Admin Hub,
11
+ * survey, edits, confirm, seed: `platform lib/points-of-contact/`); Thread,
12
+ * PAVE and LEADS read through this module and write a pending in-app add
13
+ * through it directly, without an HTTP hop. Subpath only (not re-exported from
14
+ * the package root).
11
15
  */
12
16
 
13
17
  export * from "./vocabulary.js";
14
18
  export * from "./schemas.js";
15
19
  export * from "./readRules.js";
16
20
  export * from "./reader.js";
21
+ export * from "./writer.js";
@@ -27,9 +27,27 @@
27
27
  * except the identity key, with the seat's reach resolved.
28
28
  *
29
29
  * Every view carries `purpose_labels` (hti-features `purpose_labels`, readOnly).
30
+ *
31
+ * ## Emails and phones (pl-e98)
32
+ *
33
+ * The owner and steward views carry the row's own `emails` / `phones` (what
34
+ * the editor edits; empty on a seat-linked row) beside the resolved `seat`.
35
+ * The network view carries the REACHABLE lists: the row's, or for a
36
+ * seat-linked row the seat's single email and phone as one preferred entry
37
+ * each. EVERY view also carries read-only `email` / `phone`: the reachable
38
+ * preferred address (the row's preferred entry, or the seat's for a
39
+ * seat-linked contact), the projections canon's card keeps of its preferred
40
+ * entries (platform-prototype `src/agencyhub.jsx` @ 6f428116 L8195-L8202). A
41
+ * reader that sends to or shows one address reads that projection. Views own
42
+ * their lists: they are copies, never the row's arrays.
30
43
  */
31
44
 
32
- import { PointOfContactDocSchema, type PointOfContactDoc } from "./schemas.js";
45
+ import {
46
+ PointOfContactDocSchema,
47
+ preferredContactEntry,
48
+ type PocContactEntry,
49
+ type PointOfContactDoc,
50
+ } from "./schemas.js";
33
51
  import { contactPurposeLabel, type ContactPurposeCode, type PocSubjectType } from "./vocabulary.js";
34
52
 
35
53
  /** A seat's reach, resolved by the reader from platform-db `users`. */
@@ -44,6 +62,10 @@ export interface PointOfContactStewardView extends Omit<PointOfContactDoc, "iden
44
62
  purpose_labels: string[];
45
63
  /** The seat's reach for a seat-linked contact (null when unlinked or not found). */
46
64
  seat: SeatReach | null;
65
+ /** Read-only: the reachable preferred email (the seat's for a seat-linked contact), or null. */
66
+ email: string | null;
67
+ /** Read-only: the reachable preferred phone, or null. */
68
+ phone: string | null;
47
69
  }
48
70
 
49
71
  /** The owner view: unmasked, without other organizations' actor ids. */
@@ -60,8 +82,13 @@ export interface PointOfContactNetworkView {
60
82
  agency_id: string | null;
61
83
  org_id: string | null;
62
84
  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. */
85
+ /** 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. */
86
+ emails: PocContactEntry[];
87
+ /** The row's phones, or the seat's phone as one preferred entry (the same rules as `emails`). */
88
+ phones: PocContactEntry[];
89
+ /** The preferred of `emails` (`preferredEmail(view)`), or null. The magic-link address. */
64
90
  email: string | null;
91
+ /** The preferred of `phones` (`preferredPhone(view)`), or null. */
65
92
  phone: string | null;
66
93
  purposes: ContactPurposeCode[];
67
94
  purpose_labels: string[];
@@ -82,10 +109,10 @@ export class PointOfContactShapeError extends Error {
82
109
  }
83
110
 
84
111
  /**
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.
112
+ * A stored row → the typed document. Strict: every writer (the platform's,
113
+ * and the shared in-app add every app runs, `./writer.ts`) writes every
114
+ * field, so a row that does not parse (an unknown origin or status, a missing
115
+ * id) is a defect and FAILS LOUDLY rather than being read as some default.
89
116
  */
90
117
  export function normalizePointOfContact(raw: Record<string, unknown>): PointOfContactDoc {
91
118
  const parsed = PointOfContactDocSchema.safeParse(raw);
@@ -101,16 +128,47 @@ export function isNetworkVisible(d: Pick<PointOfContactDoc, "active" | "status"
101
128
  return d.active && d.status === "confirmed" && !d.is_confidential;
102
129
  }
103
130
 
131
+ const copyEntries = (list: readonly PocContactEntry[]): PocContactEntry[] =>
132
+ list.map((e) => ({ ...e }));
133
+
134
+ /**
135
+ * Where the contact is reached: the row's own lists, or for a seat-linked row
136
+ * the seat's email (trimmed, lowercased) and phone as one preferred entry
137
+ * each. Always fresh arrays.
138
+ */
139
+ function reachOf(
140
+ d: PointOfContactDoc,
141
+ seat: SeatReach | null | undefined,
142
+ ): { emails: PocContactEntry[]; phones: PocContactEntry[] } {
143
+ if (!d.user_id) return { emails: copyEntries(d.emails), phones: copyEntries(d.phones) };
144
+ const one = (v: string | null | undefined): PocContactEntry[] =>
145
+ v ? [{ value: v, is_preferred: true }] : [];
146
+ return {
147
+ emails: one(seat?.email?.trim().toLowerCase()),
148
+ phones: one(seat?.phone?.trim()),
149
+ };
150
+ }
151
+
152
+ const preferredValue = (list: readonly PocContactEntry[]): string | null =>
153
+ preferredContactEntry(list)?.value ?? null;
154
+
104
155
  /** The steward view. */
105
156
  export function toStewardView(
106
157
  d: PointOfContactDoc,
107
158
  seat?: SeatReach | null,
108
159
  ): PointOfContactStewardView {
109
160
  const { identity_key: _internal, ...rest } = d;
161
+ const reach = reachOf(d, seat);
110
162
  return {
111
163
  ...rest,
164
+ emails: copyEntries(d.emails),
165
+ phones: copyEntries(d.phones),
166
+ purposes: [...d.purposes],
167
+ urgent_methods: [...d.urgent_methods],
112
168
  purpose_labels: d.purposes.map(contactPurposeLabel),
113
169
  seat: d.user_id ? (seat ?? null) : null,
170
+ email: preferredValue(reach.emails),
171
+ phone: preferredValue(reach.phones),
114
172
  };
115
173
  }
116
174
 
@@ -141,6 +199,7 @@ export function toNetworkView(
141
199
  ): PointOfContactNetworkView | null {
142
200
  if (!isNetworkVisible(d)) return null;
143
201
  const seatLinked = !!d.user_id;
202
+ const { emails, phones } = reachOf(d, seat);
144
203
  return {
145
204
  id: d.id,
146
205
  subject_type: d.subject_type,
@@ -148,11 +207,13 @@ export function toNetworkView(
148
207
  agency_id: d.agency_id,
149
208
  org_id: d.org_id,
150
209
  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,
210
+ emails,
211
+ phones,
212
+ email: preferredValue(emails),
213
+ phone: preferredValue(phones),
214
+ purposes: [...d.purposes],
154
215
  purpose_labels: d.purposes.map(contactPurposeLabel),
155
- urgent_methods: d.urgent_methods,
216
+ urgent_methods: [...d.urgent_methods],
156
217
  is_primary: d.is_primary,
157
218
  updatedAt: d.updatedAt,
158
219
  };
@@ -163,11 +224,11 @@ const SUBJECT_ORDER: Record<PocSubjectType, number> = {
163
224
  org: 1,
164
225
  program: 2,
165
226
  team: 3,
166
- site: 4,
227
+ location: 4,
167
228
  service: 5,
168
229
  };
169
230
 
170
- /** Reading order: the agency / org before its programs, teams and sites, primary first, then name, then id. */
231
+ /** Reading order: the agency / org before its programs, teams and locations, primary first, then name, then id. */
171
232
  export function byContactReadingOrder(
172
233
  a: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">,
173
234
  b: Pick<PointOfContactDoc, "subject_type" | "subject_id" | "is_primary" | "display_name" | "id">,
@@ -48,21 +48,21 @@ export type SeatResolver = (userIds: readonly string[]) => Promise<ReadonlyMap<s
48
48
 
49
49
  /**
50
50
  * A subject, always read together with its agency where ids can collide.
51
- * Program, team and site ids can be slugs two agencies share, so their reads
51
+ * Program, team and location ids can be slugs two agencies share, so their reads
52
52
  * REQUIRE `agency_id`. A service listing's contact names `agency_id` too:
53
53
  * the listing org's genuine-mirror agency, or `null` for an org-only partner.
54
54
  * Only agency and org subjects (whose ids are themselves unique) may omit it.
55
55
  */
56
56
  export type PocSubjectRef =
57
57
  | { subject_type: "agency" | "org"; subject_id: string; agency_id?: string | null }
58
- | { subject_type: "program" | "team" | "site"; subject_id: string; agency_id: string }
58
+ | { subject_type: "program" | "team" | "location"; subject_id: string; agency_id: string }
59
59
  | { subject_type: "service"; subject_id: string; agency_id: string | null };
60
60
 
61
61
  function subjectFilter(subject: PocSubjectRef): Record<string, unknown> {
62
62
  const type = requireId("subject_type", subject.subject_type) as PocSubjectType;
63
63
  const base = { subject_type: type, subject_id: requireId("subject_id", subject.subject_id) };
64
64
  const agency = subject.agency_id;
65
- if (type === "program" || type === "team" || type === "site") {
65
+ if (type === "program" || type === "team" || type === "location") {
66
66
  return { ...base, agency_id: requireId("agency_id", agency) };
67
67
  }
68
68
  if (type === "service" && agency === undefined) {
@@ -141,8 +141,26 @@ export async function listContactsForSubject(
141
141
  return networkViews(docs, await seatsFor(docs, opts.resolveSeats));
142
142
  }
143
143
 
144
- /** A referral recipient: a network-visible contact with a resolved email. */
145
- export type ReferralRecipient = PointOfContactNetworkView & { email: string };
144
+ /**
145
+ * A referral recipient: a network-visible contact with a resolved email, or
146
+ * (only when asked, {@link ReferralContactsOptions.includeOwnPendingFor}) the
147
+ * asking advocate's OWN pending in-app add, marked `pending: true` so a UI can
148
+ * label it.
149
+ */
150
+ export type ReferralRecipient = PointOfContactNetworkView & { email: string; pending?: true };
151
+
152
+ export interface ReferralContactsOptions {
153
+ resolveSeats: SeatResolver;
154
+ /**
155
+ * The asking advocate's Auth0 `sub`, taken server-side from the verified
156
+ * token (the same pinning as `mintPartnerContact`'s `actor.id`). When set,
157
+ * the advocate's OWN pending in-app adds on the partner (`status: pending`,
158
+ * active, `origin: in_app`, `createdBy` = this sub, tagged Referrals (magic
159
+ * link), not confidential) are returned too, after the confirmed recipients
160
+ * and marked `pending: true`. Nobody else's pending add is ever returned.
161
+ */
162
+ includeOwnPendingFor?: string;
163
+ }
146
164
 
147
165
  export interface ReferralContactsResult {
148
166
  /** One per distinct email, in reading order (the agency's own contacts first). */
@@ -154,15 +172,22 @@ export interface ReferralContactsResult {
154
172
  /**
155
173
  * The partner's Referrals (magic link) contacts: every active, confirmed,
156
174
  * non-confidential contact tagged `REFERRALS_MAGIC_LINK` on the partner's
157
- * agency AND on its programs, teams and sites (the rollup, via the row's
175
+ * agency AND on its programs, teams and locations (the rollup, via the row's
158
176
  * `agency_id`), and on its organization (via `org_id`). A magic link goes to
159
- * every one of them (Crysta 2026-08-23, restated 2026-10-14). The same email
160
- * tagged on two subjects is one recipient.
177
+ * every one of them (Crysta 2026-08-23, restated 2026-10-14), at its PREFERRED
178
+ * email (pl-e98; the view's `email`). The same email tagged on two subjects is
179
+ * one recipient.
180
+ *
181
+ * With `includeOwnPendingFor` (Nate 2026-10-15), the advocate also sees their
182
+ * own pending in-app adds on the partner, so a contact they just added can be
183
+ * picked before HTI Labs confirms it (pending, marked, after the confirmed
184
+ * recipients; an email a confirmed recipient already has is not repeated).
185
+ * Confidential rows stay excluded.
161
186
  */
162
187
  export async function listReferralContactsForPartner(
163
188
  db: PocDbLike,
164
189
  partner: PocPartnerSelector,
165
- opts: { resolveSeats: SeatResolver },
190
+ opts: ReferralContactsOptions,
166
191
  ): Promise<ReferralContactsResult> {
167
192
  const keys: Record<string, string>[] = [];
168
193
  if (partner.agency_id !== undefined && partner.agency_id !== null) {
@@ -172,6 +197,10 @@ export async function listReferralContactsForPartner(
172
197
  keys.push({ org_id: requireId("org_id", partner.org_id) });
173
198
  }
174
199
  if (keys.length === 0) throw new TypeError("points-of-contact: select a partner by agency_id, org_id or both");
200
+ const pendingFor =
201
+ opts.includeOwnPendingFor === undefined
202
+ ? null
203
+ : requireId("includeOwnPendingFor", opts.includeOwnPendingFor);
175
204
  const docs = await findDocs(db, {
176
205
  $or: keys,
177
206
  purposes: REFERRALS_MAGIC_LINK_PURPOSE,
@@ -193,9 +222,46 @@ export async function listReferralContactsForPartner(
193
222
  seen.add(email);
194
223
  recipients.push({ ...v, email });
195
224
  }
225
+
226
+ if (pendingFor !== null) {
227
+ const pending = await findDocs(db, {
228
+ $or: keys,
229
+ purposes: REFERRALS_MAGIC_LINK_PURPOSE,
230
+ ...OWN_PENDING_IN_APP,
231
+ createdBy: pendingFor,
232
+ });
233
+ for (const d of pending) {
234
+ // The same filter again, on the parsed row: a reader never widens it.
235
+ if (!isOwnPendingInApp(d, pendingFor)) continue;
236
+ // An in-app add is a write-in (never seat-linked): its view is its own row's,
237
+ // drawn as the network view would draw it once confirmed.
238
+ const v = toNetworkView({ ...d, status: "confirmed" });
239
+ const email = v?.email;
240
+ if (!v || !email || seen.has(email)) continue;
241
+ seen.add(email);
242
+ recipients.push({ ...v, email, pending: true });
243
+ }
244
+ }
196
245
  return { recipients, unreachable };
197
246
  }
198
247
 
248
+ /** An outstanding in-app add, visible to its own adder only (and never when confidential). */
249
+ const OWN_PENDING_IN_APP = {
250
+ active: true,
251
+ status: "pending",
252
+ origin: "in_app",
253
+ is_confidential: { $ne: true },
254
+ } as const;
255
+
256
+ const isOwnPendingInApp = (d: PointOfContactDoc, sub: string) =>
257
+ d.active &&
258
+ d.status === "pending" &&
259
+ d.origin === "in_app" &&
260
+ !d.is_confidential &&
261
+ !d.user_id &&
262
+ d.createdBy === sub &&
263
+ d.purposes.includes(REFERRALS_MAGIC_LINK_PURPOSE);
264
+
199
265
  /** One contact as other organizations see it, or null (absent or not network-visible). */
200
266
  export async function getContact(
201
267
  db: PocDbLike,