@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.
- package/README.md +374 -1
- package/dist/points-of-contact/index.cjs +954 -30
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.d.cts +1062 -90
- package/dist/points-of-contact/index.d.ts +1062 -90
- package/dist/points-of-contact/index.js +926 -30
- package/dist/points-of-contact/index.js.map +1 -1
- package/package.json +1 -1
- package/src/pointsOfContact/__tests__/mongoDouble.ts +194 -0
- package/src/pointsOfContact/__tests__/pointsOfContact.test.ts +826 -26
- package/src/pointsOfContact/__tests__/reader.mongo.test.ts +211 -0
- package/src/pointsOfContact/__tests__/writer.mongo.test.ts +190 -0
- package/src/pointsOfContact/__tests__/writer.test.ts +782 -0
- package/src/pointsOfContact/index.ts +14 -7
- package/src/pointsOfContact/readRules.ts +81 -13
- package/src/pointsOfContact/reader.ts +409 -27
- package/src/pointsOfContact/schemas.ts +304 -34
- package/src/pointsOfContact/vocabulary.ts +44 -6
- package/src/pointsOfContact/writer.ts +967 -0
|
@@ -1,16 +1,23 @@
|
|
|
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 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 {
|
|
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
|
|
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:
|
|
86
|
-
* and
|
|
87
|
-
*
|
|
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
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
234
|
+
location: 4,
|
|
167
235
|
service: 5,
|
|
168
236
|
};
|
|
169
237
|
|
|
170
|
-
/** Reading order: the agency / org before its programs, teams and
|
|
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">,
|