@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
|
@@ -1,16 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @htilabs/platform-common-models/points-of-contact
|
|
3
3
|
*
|
|
4
|
-
* The Point of contact
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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 {
|
|
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
|
|
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:
|
|
86
|
-
* and
|
|
87
|
-
*
|
|
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
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
227
|
+
location: 4,
|
|
167
228
|
service: 5,
|
|
168
229
|
};
|
|
169
230
|
|
|
170
|
-
/** Reading order: the agency / org before its programs, teams and
|
|
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
|
|
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" | "
|
|
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 === "
|
|
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
|
-
/**
|
|
145
|
-
|
|
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
|
|
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)
|
|
160
|
-
* tagged on two subjects is
|
|
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:
|
|
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,
|