@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
package/README.md
CHANGED
|
@@ -16,6 +16,378 @@ Package exports are organized into a public root API and a small number of
|
|
|
16
16
|
dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
|
|
17
17
|
authoritative `exports` map.
|
|
18
18
|
|
|
19
|
+
## points-of-contact / 0.32.0
|
|
20
|
+
|
|
21
|
+
0.32.0 (pl-iza) is additive: confidential Referrals (magic link) holders
|
|
22
|
+
receive magic links, and the sender sees only how many. Canon: CVC-338
|
|
23
|
+
`REFERRALS_MAGIC_LINK` (prototype `data/cvcs/core_contact_purpose.yaml` @
|
|
24
|
+
184893b6 L95), "A confidential holder still receives it; the sender never
|
|
25
|
+
sees the address."; HANDOFF.md @ 184893b6 L569, L575 (POC-PROFILE-ALIGNMENTS
|
|
26
|
+
D(ii)). Ruling: Nate, 2026-10-15. (0.31.0 is claimed by PR #219.)
|
|
27
|
+
|
|
28
|
+
- **The network view is unchanged.** A confidential row is still absent from
|
|
29
|
+
every view another organization sees (`toNetworkView`, `getContact`,
|
|
30
|
+
`listContactsForSubject`, the referral `recipients` and `unreachable`).
|
|
31
|
+
- **`listReferralContactsForPartner`** keeps its signature. Its result gains
|
|
32
|
+
`confidentialCount: number`, the number of distinct confidential holder
|
|
33
|
+
addresses, for the sender's "+ 1 confidential recipient" / "N confidential
|
|
34
|
+
recipients" line. `unreachable` is unchanged: ids of VISIBLE contacts only,
|
|
35
|
+
safe to show a sender.
|
|
36
|
+
- **`resolveMagicLinkRecipients(db, partner, opts)`** (send-only, same
|
|
37
|
+
options) returns `MagicLinkSendList`: `{ recipients, unreachable,
|
|
38
|
+
confidential, confidentialUnreachableCount }`, where `confidential` is a
|
|
39
|
+
`ConfidentialReferralRecipients` (an interface, exported as a type only).
|
|
40
|
+
The implementation is not exported: obtain values only via
|
|
41
|
+
`resolveMagicLinkRecipients`. `confidentialUnreachableCount` is a
|
|
42
|
+
SERVER-SIDE diagnostic, never returned to a sender: confidential holder rows
|
|
43
|
+
that cannot be sent to (no email, a seat with none or not found), plus
|
|
44
|
+
skipped rows that do not match the contract and may be confidential.
|
|
45
|
+
- **`ConfidentialReferralRecipients`**: its implementation carries the
|
|
46
|
+
addresses in a private field. Public: `count`; `toJSON()` → `{ count }`;
|
|
47
|
+
`util.inspect` →
|
|
48
|
+
`ConfidentialReferralRecipients(n)`; and `deliver(sendOne, { capacity? })`
|
|
49
|
+
→ `{ count, delivered, failed, overflow, firstErrorName }`. `deliver` sends
|
|
50
|
+
to the first `capacity` holders (all when omitted), one at a time;
|
|
51
|
+
`overflow` is `max(0, count - capacity)`. It catches every `sendOne` error,
|
|
52
|
+
keeping only its `name` ("Error" when the name is not a plain identifier or
|
|
53
|
+
cannot be read), and never rejects for a failed send. `sendOne` is
|
|
54
|
+
`(address: string) => void | Promise<void>` and must THROW (or reject) on
|
|
55
|
+
failure: returning normally counts as delivered.
|
|
56
|
+
- **What a sender may see.** Only `count` (or `confidentialCount`), or one
|
|
57
|
+
all-or-nothing status. `delivered`, `failed`, `overflow` and
|
|
58
|
+
`firstErrorName` are server-side, for audit only.
|
|
59
|
+
- **Has a holder.** A partner has a magic-link holder when
|
|
60
|
+
`recipients.length + confidentialCount > 0`. Canon D(ii): a confidential
|
|
61
|
+
holder is a holder, so the listing-contact fallback does not fire over it,
|
|
62
|
+
and the send must not refuse a partner whose only holders are confidential.
|
|
63
|
+
- **Which rows count.** Active, `confirmed`, `is_confidential: true`, tagged
|
|
64
|
+
Referrals (magic link), on the same rollup (the partner's agency and its
|
|
65
|
+
programs, teams and locations, its service listings, and its org), at the
|
|
66
|
+
preferred email (the seat's for a seat-linked holder). A separate query; the
|
|
67
|
+
visible and own-pending queries are unchanged, and no index changes. Seats
|
|
68
|
+
are resolved once per read, over the visible and confidential rows
|
|
69
|
+
together. A pending confidential row is not routed until it is confirmed;
|
|
70
|
+
an inactive or untagged one never is. A row that does not match the
|
|
71
|
+
contract and may be confidential (in the confidential query, or a visible
|
|
72
|
+
or pending row whose stored `is_confidential` is malformed, e.g. `"true"`
|
|
73
|
+
or `1`, which matches `{ $ne: true }`) is skipped and counted in
|
|
74
|
+
`confidentialUnreachableCount`, never thrown (its error would name its id),
|
|
75
|
+
so it never blocks the visible sends. Any other corrupt row still throws.
|
|
76
|
+
- **De-duplication is oracle-safe.** Confidential addresses are deduped
|
|
77
|
+
among THEMSELVES only: `confidentialCount` is the number of distinct
|
|
78
|
+
confidential addresses, and no visible, pending, typed or added address
|
|
79
|
+
moves it. `deliver` takes no caller addresses at all. Otherwise an advocate
|
|
80
|
+
could learn an address by watching a number change: adding or typing it,
|
|
81
|
+
or seeing their pending add confirmed by a steward or a visible seat's
|
|
82
|
+
email edited to match. An overlap with any other recipient is simply sent
|
|
83
|
+
twice: the holder gets a duplicate link, which the advocate cannot observe.
|
|
84
|
+
- **Store counts only.** A share, receipt, event or log carries
|
|
85
|
+
`confidential.count` (or `confidentialCount`), never an id or an address.
|
|
86
|
+
- **The transport must not log `to`.** Every address `sendOne` receives is a
|
|
87
|
+
confidential one. Thread's SES dev transport logs the recipient
|
|
88
|
+
(`apps/api/src/services/ses/client.ts` @ 029d91a95 L122-L140, `to:
|
|
89
|
+
args.to` at L128): a confidential send must not go through it as is.
|
|
90
|
+
- **Lower tiers.** On a lower-tier deployment, confidential holders redirect
|
|
91
|
+
to the advocate like every other recipient (the caller's existing redirect
|
|
92
|
+
applies to the address `sendOne` receives). A redirected message must not
|
|
93
|
+
name the address it was meant for: a redirect banner or header that lists
|
|
94
|
+
the original recipients shows "1 confidential recipient" instead.
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import { resolveMagicLinkRecipients } from "@htilabs/platform-common-models/points-of-contact";
|
|
98
|
+
|
|
99
|
+
const send = await resolveMagicLinkRecipients(platformDb, partner, {
|
|
100
|
+
resolveSeats,
|
|
101
|
+
includeOwnPendingFor: verifiedToken.sub, // the advocate's own pending adds, marked `pending`
|
|
102
|
+
});
|
|
103
|
+
if (send.recipients.length + send.confidential.count === 0) {
|
|
104
|
+
// no magic-link holder: the listing-contact fallback applies
|
|
105
|
+
}
|
|
106
|
+
// The visible picks (pre-filled, own-pending, typed), deduped among themselves.
|
|
107
|
+
const visible = [...new Set([...pickedRecipients.map((r) => r.email), ...typedAddresses])];
|
|
108
|
+
for (const to of visible) await mailer.sendMagicLink(to); // throws on failure
|
|
109
|
+
// The confidential holders: the same mailer, which must throw on failure and never log `to`.
|
|
110
|
+
const audit = await send.confidential.deliver((to) => mailer.sendMagicLink(to), {
|
|
111
|
+
capacity: Math.max(0, MAX_SENDS - visible.length),
|
|
112
|
+
});
|
|
113
|
+
share.magic_link_confidential = send.confidential.count; // a count, never an address
|
|
114
|
+
log.info(
|
|
115
|
+
{ confidential: audit, confidentialUnreachable: send.confidentialUnreachableCount },
|
|
116
|
+
"magic link sent",
|
|
117
|
+
); // server-side audit numbers only, never returned to the sender
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## points-of-contact / 0.30.0 (BREAKING)
|
|
121
|
+
|
|
122
|
+
0.30.0 (pl-e98, pl-f4c) reshapes the Point of contact contract. There is no
|
|
123
|
+
prod data, so it is a clean cut: no legacy acceptance, no read shim for the
|
|
124
|
+
stored single fields, no migration (Nate, 2026-10-15). Every consumer
|
|
125
|
+
(platform writer and editor, Thread, PAVE) changes in its own lane.
|
|
126
|
+
|
|
127
|
+
**pl-f4c: a site is stored `location`, displayed "Site".** The UDD names the
|
|
128
|
+
object Site, but its stored names, ids and columns stay `location` (schema of
|
|
129
|
+
record hti-features `udd-schemas/location/Location.v1.json`; canon
|
|
130
|
+
`ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 L236). `POC_SUBJECT_TYPES`
|
|
131
|
+
is now `agency · org · program · team · location · service`. **`site` is now
|
|
132
|
+
refused** everywhere: owner schema, stored row (reads throw) and
|
|
133
|
+
`PocSubjectRef`. New: `POC_SUBJECT_TYPE_LABELS` / `pocSubjectTypeLabel`
|
|
134
|
+
(`location` → "Site").
|
|
135
|
+
|
|
136
|
+
**pl-e98: a contact holds `emails[]` and `phones[]`.** Crysta's 2026-08-24
|
|
137
|
+
multi-entry correction. Canon's Admin Hub ledger stores each address as
|
|
138
|
+
`{type, value, preferred}` (platform-prototype `src/agencyhub.jsx` @ 6f428116
|
|
139
|
+
`methodsFor` L8107-L8132, the save L8181); here the type is the list.
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
// StoredContactEntrySchema; PocContactEntry = z.infer<typeof StoredContactEntrySchema>
|
|
143
|
+
interface PocContactEntry {
|
|
144
|
+
value: string; // email (lowercased) or phone as typed (trimmed)
|
|
145
|
+
is_preferred: boolean; // the CONTACT rail's flag (ObjectDirectoryEntry.mjs @ fa0fd0b0 L52)
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The contact-level `is_primary` (the subject's primary contact) is unrelated
|
|
150
|
+
and unchanged. There is no per-entry use label: CVC-154
|
|
151
|
+
`contact_info_use_type` is investigative-only, and canon's pickers give PAVE
|
|
152
|
+
and Thread no codes and the Platform no picker at all
|
|
153
|
+
(`data/cvcs/core_contact_info_use_type.yaml` @ fa0fd0b0 L93-L97).
|
|
154
|
+
|
|
155
|
+
- **The preferred rule (writers).** `PocEmailListSchema` / `PocPhoneListSchema`
|
|
156
|
+
accept `{ value, is_preferred? }` entries: at most one marked preferred, and
|
|
157
|
+
the list is normalized to exactly one (the marked entry, else the first:
|
|
158
|
+
canon L8126-L8129). The same email twice, the same phone line twice (by
|
|
159
|
+
digits, canon's `phoneDigits`), or a phone with no digit is refused. At most
|
|
160
|
+
`POC_MAX_CONTACT_ENTRIES` (10) per list. A list in an edit replaces the
|
|
161
|
+
stored list; **clearing is `emails: []`, `null` is refused**.
|
|
162
|
+
- **Phones are stored as typed, trimmed**, as this object's canon writer, the
|
|
163
|
+
Admin Hub ledger, stores them (`agencyhub.jsx` @ 6f428116 L8124-L8125,
|
|
164
|
+
L8173, L8511-L8518). `pocPhoneDigits` (canon's `phoneDigits`,
|
|
165
|
+
`leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
|
|
166
|
+
L282-L286) is the duplicate key only. **Accepted: an extension makes a
|
|
167
|
+
distinct line** (`402-677-3902 x5` and `402-677-3902` differ by digits, so
|
|
168
|
+
both may sit on one contact). `formatPocPhone` mirrors canon's `formatPhone`
|
|
169
|
+
(L246-L256) as a **display-only** helper readers apply; canon calls it
|
|
170
|
+
"display only" (L229-L245). It is lossy and is never written back.
|
|
171
|
+
- **Stored lists are read leniently.** `PointOfContactDocSchema` repairs a
|
|
172
|
+
stored list the same way (emails trimmed and lowercased, empty and repeated
|
|
173
|
+
entries dropped, a missing or null `is_preferred` read as false, no
|
|
174
|
+
preferred → the first, several → the first marked), so one row never takes
|
|
175
|
+
down a partner's read. Only structurally invalid data (not an array, a
|
|
176
|
+
non-object entry, a non-string value, a non-boolean flag) throws.
|
|
177
|
+
- **Read helpers:** `preferredContactEntry(list)`, `preferredEmail(contact)`,
|
|
178
|
+
`preferredPhone(contact)`, over a stored row or any view. Every view also
|
|
179
|
+
carries read-only `email` / `phone`: the reachable preferred address (the
|
|
180
|
+
seat's for a seat-linked contact). Views hold copies, never the row's arrays.
|
|
181
|
+
- `pocIdentityKey` keys a write-in on its name and its **preferred** email.
|
|
182
|
+
- `listReferralContactsForPartner` sends to each tagged contact's
|
|
183
|
+
**preferred** email (the view's `email`), deduped on it. A seat's email is
|
|
184
|
+
trimmed and lowercased first.
|
|
185
|
+
- **Body-builder types:** `PocDetailsInput`, `PocInAppInput`, `PocSeedInput`,
|
|
186
|
+
`PocPatchInput` (`z.input` of the schemas: defaulted fields optional).
|
|
187
|
+
|
|
188
|
+
**Upgrading the platform to 0.30.0:**
|
|
189
|
+
|
|
190
|
+
- **No data existed before 0.30.0; no migration.** No platform database has
|
|
191
|
+
a `pointsofcontact` collection (platform-prod, -db, -dev, -test and -train
|
|
192
|
+
checked 2026-10-15), so there are no 0.28.0 rows and no old indexes to
|
|
193
|
+
drop. `ensurePocIndexes` (below) only creates indexes.
|
|
194
|
+
- **HTTP wire change.** `PocInAppSchema` is the body of
|
|
195
|
+
`POST /api/partner-contacts`. A caller sends `emails: [{ value }]` (at
|
|
196
|
+
least one) and optional `phones`, never `email` / `phone`. Thread and PAVE
|
|
197
|
+
write through `mintPartnerContact` (below) instead of calling it.
|
|
198
|
+
- **The writer maps an identity unique-index collision to a domain error**
|
|
199
|
+
(platform's job).
|
|
200
|
+
|
|
201
|
+
**Thread and PAVE write pending in-app contacts directly via
|
|
202
|
+
`mintPartnerContact`; no HTTP** (pl-bt1, pl-e98). The in-app partner add is
|
|
203
|
+
the platform's `addPartnerContact` (the store behind
|
|
204
|
+
`POST /api/partner-contacts`), moved into this subpath so all three apps run
|
|
205
|
+
one implementation against their own platform-db handle:
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
import { ObjectId } from "mongodb"; // or mongoose.Types.ObjectId
|
|
209
|
+
import { mintPartnerContact } from "@htilabs/platform-common-models/points-of-contact";
|
|
210
|
+
|
|
211
|
+
const r = await mintPartnerContact(
|
|
212
|
+
platformDb, // the deployment's own, long-lived, primary reads
|
|
213
|
+
{
|
|
214
|
+
app: "thread", // a server constant: pave · thread · leads
|
|
215
|
+
partner: { org_id }, // and/or agency_id, from the recipient picker
|
|
216
|
+
contact: { display_name, emails: [{ value }], phones }, // PocInAppInput
|
|
217
|
+
actor: { id: verifiedToken.sub }, // Auth0 `sub`, server-side from the verified token
|
|
218
|
+
},
|
|
219
|
+
{ ObjectId },
|
|
220
|
+
);
|
|
221
|
+
if (r.ok) r.value; // PartnerContactReceipt: { id, status, created, subject_type, subject_id, agency_id, org_id }
|
|
222
|
+
else r.reason; // PartnerContactFailureReason; r.status is the HTTP status the platform route answers
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- **Same rules, same order, same codes as the platform store.** Actor
|
|
226
|
+
(`actor_required`), app (`invalid_app`), strict `PocInAppSchema` body
|
|
227
|
+
(`invalid_contact`; Referrals (magic link) always added first), strict
|
|
228
|
+
`PartnerContactSelectorSchema` (`invalid_partner`); the partner resolved to
|
|
229
|
+
`String(agencies._id)` / `String(organizations._id)` in any accepted form,
|
|
230
|
+
a mapped `registry_agencies` row included, an org with a genuine-mirror
|
|
231
|
+
agency rewritten onto the agency (`owner_not_found`, `owner_mismatch`); a
|
|
232
|
+
canonical singleton or PAVE 2.0-shape org refused (`canonical_org`,
|
|
233
|
+
`foreign_row_shape`). Then the existing rows answer, matched on the
|
|
234
|
+
package identity rule (`pocIdentityKey`: `writein:<name>|<preferred
|
|
235
|
+
email>`, trimmed and lowercased): a visible tagged contact, or the caller's
|
|
236
|
+
own pending add (`created: false`, nothing written); the caller's own
|
|
237
|
+
removed add is `contact_deactivated`. The caller's outstanding pending adds are capped at
|
|
238
|
+
`POC_IN_APP_PENDING_CAP_PER_PARTNER` (5) per partner and
|
|
239
|
+
`POC_IN_APP_PENDING_CAP_PER_ACTOR` (25) overall (`too_many_pending_adds`,
|
|
240
|
+
429). The writer then checks the indexes it relies on
|
|
241
|
+
(`checkPocIndexes`: refuses `indexes_missing`, 503) and the row lands
|
|
242
|
+
`pending`, `origin: in_app`, `added_in_app: <app>`, version 1. A raced
|
|
243
|
+
identical add (`duplicate_pending_add` on
|
|
244
|
+
`POC_IN_APP_PENDING_INDEX`) answers with the winner's row. Every code is in
|
|
245
|
+
`PARTNER_CONTACT_FAILURE_REASONS`.
|
|
246
|
+
- **Returns, never throws, a domain refusal; logs nothing.** No message
|
|
247
|
+
carries a stored value (a driver's duplicate-key message echoes the email,
|
|
248
|
+
so it is never returned). A read or write error, or a stored row that does
|
|
249
|
+
not parse (`PointOfContactShapeError`), propagates.
|
|
250
|
+
- **Dedupe is by identity, never by a shared mailbox** (ruling 2026-10-15).
|
|
251
|
+
The interim platform rule "shares ANY email" (matcher `$in` on
|
|
252
|
+
`emails.value`, multikey pending index) is a defect, reproduced on a real
|
|
253
|
+
MongoDB: with Bob `[bob★, intake@]` listed, an add of Jane `[jane★,
|
|
254
|
+
intake@]` returned Bob's id and Jane was never stored; an adder's pending
|
|
255
|
+
add blocked their next add sharing the mailbox (Dan); and a removed row
|
|
256
|
+
sharing a secondary mailbox refused every later add with a false
|
|
257
|
+
`contact_deactivated` (Eve). Now the matcher and the pending unique index
|
|
258
|
+
both key on the stored scalar `identity_key`, so Jane, Dan and Eve each
|
|
259
|
+
land, while the same name with the same preferred email (whatever its
|
|
260
|
+
other emails) is one person: a retry answers with the first row, and a race
|
|
261
|
+
of the two recovers through `duplicate_pending_add` to the winner.
|
|
262
|
+
- **The pieces the platform store imports** (so the index and the matcher can
|
|
263
|
+
never disagree, which the race recovery depends on):
|
|
264
|
+
`POINT_OF_CONTACT_INDEXES.inAppPending` / `.pendingQueue` (aliased
|
|
265
|
+
`POC_IN_APP_PENDING_INDEX` / `POC_PENDING_QUEUE_INDEX`),
|
|
266
|
+
`POC_IN_APP_PENDING_INDEX_KEY` (`agency_id, subject_type, subject_id,
|
|
267
|
+
identity_key, createdBy`), `POC_IN_APP_PENDING_INDEX_FILTER`,
|
|
268
|
+
`pocRowsWithIdentity(db, subject, identityKey)` (the matcher) and
|
|
269
|
+
`pocDuplicateKeyFailure(err)`
|
|
270
|
+
(E11000 → `duplicate_pending_add` · `primary_exists` · `duplicate_contact`
|
|
271
|
+
· `duplicate_contact_id` · `duplicate_key`, by index name then key pattern;
|
|
272
|
+
null for any other error).
|
|
273
|
+
- **The writer never creates an index (least privilege; fail closed).**
|
|
274
|
+
Before its insert it reads `listIndexes` once per handle
|
|
275
|
+
(`checkPocIndexes`, exported for a readiness probe): the `id` index must be
|
|
276
|
+
unique, and `POC_IN_APP_PENDING_INDEX` must exist with exactly
|
|
277
|
+
`POC_IN_APP_PENDING_INDEX_KEY` (fields, order, direction), `unique: true`
|
|
278
|
+
and exactly `POC_IN_APP_PENDING_INDEX_FILTER`, under any name. A missing
|
|
279
|
+
collection (NamespaceNotFound) or index is `indexes_missing` (503); a pass
|
|
280
|
+
is memoized per handle, a refusal is not.
|
|
281
|
+
- **`ensurePocIndexes(db)` is the PLATFORM's.** It creates the full
|
|
282
|
+
`pointsofcontact` index set (every `POINT_OF_CONTACT_INDEXES` entry,
|
|
283
|
+
`inAppPending` and `pendingQueue` included) with plain `createIndex` calls:
|
|
284
|
+
idempotent, memoized per handle, retried after a failure, a server refusal
|
|
285
|
+
propagated. No migration and no drop. The platform must deploy and run it
|
|
286
|
+
before any Thread or PAVE caller writes; until then every app add is
|
|
287
|
+
`indexes_missing`.
|
|
288
|
+
- **The caps bound a burst.** After its insert each add counts the adder's
|
|
289
|
+
pending rows (per partner, then overall); over the cap it deletes its own
|
|
290
|
+
row and is `too_many_pending_adds`. No more than the cap ever survive (the
|
|
291
|
+
survivor that counted last counted every survivor), on a real server too;
|
|
292
|
+
the price is a spurious 429 under contention (a burst may withdraw rows
|
|
293
|
+
that would have fit; a retry lands). The platform's earlier rank-based
|
|
294
|
+
check let a burst of 12 leave 7-10 rows against a cap of 5. The bound
|
|
295
|
+
needs every count to read the primary (see the caller contract).
|
|
296
|
+
|
|
297
|
+
**Caller contract** (Thread, PAVE, LEADS: everything the package cannot
|
|
298
|
+
check for you):
|
|
299
|
+
|
|
300
|
+
- **Accepted risk: direct writes (Nate, 2026-10-15).** Thread and PAVE write
|
|
301
|
+
pending in-app contacts straight to platform-db through
|
|
302
|
+
`mintPartnerContact`, not through the platform's HTTP route. This widens
|
|
303
|
+
the trust boundary: their database credential needs `insert` and `remove`
|
|
304
|
+
on `pointsofcontact`, and MongoDB privileges cannot scope a write by
|
|
305
|
+
`status`, so a compromised app credential could write any row shape. That
|
|
306
|
+
wider boundary is accepted. The writer itself always writes `status:
|
|
307
|
+
"pending"`, `origin: "in_app"` (no argument names a status, origin or
|
|
308
|
+
owner), and only the platform (its steward confirm, or the partner's own
|
|
309
|
+
editor) ever makes a row `confirmed`.
|
|
310
|
+
- **Actor.** `actor.id` is the advocate's Auth0 `sub`, taken server-side from
|
|
311
|
+
the verified token, as the platform route takes `auth0Sub`. Never a request
|
|
312
|
+
body value, a client header or a `users._id`. `createdBy`, the adder's
|
|
313
|
+
dedupe, caps and removed-add refusal all key on it.
|
|
314
|
+
- **App.** `app` is the caller's own server constant (`"thread"`, `"pave"`),
|
|
315
|
+
never a request value. The caller checks the advocate's token
|
|
316
|
+
`allowed_apps` holds that app, by the deployment's keys: the exact app key,
|
|
317
|
+
plus `<app>_train` only on a training deployment (the platform's
|
|
318
|
+
`PARTNER_ADD_<APP>_APP_KEYS` rule). A training deployment never holds a
|
|
319
|
+
write handle to a production platform-db.
|
|
320
|
+
- **Handle.** The deployment's own platform-db (`mongodb` `Db` or a mongoose
|
|
321
|
+
connection's `.db`), long-lived: the index check is memoized per handle
|
|
322
|
+
object, and `client.db(name)` returns a new object on every call, so call
|
|
323
|
+
it once. Reads must go to the primary (no `secondary*` read preference on
|
|
324
|
+
this handle or its client): the caps' bound and the race recovery read
|
|
325
|
+
what was just written.
|
|
326
|
+
- **Time.** `now` is the server's clock or omitted, never a request value.
|
|
327
|
+
- **Partner.** Pass only the `agency_id` / `org_id` the advocate picked in
|
|
328
|
+
the recipient picker (the same ids the magic-link pre-fill reads), never a
|
|
329
|
+
free-typed or body-supplied subject.
|
|
330
|
+
- **Pre-fill.** To show the advocate their OWN pending adds in the
|
|
331
|
+
magic-link pre-fill, read with
|
|
332
|
+
`listReferralContactsForPartner(db, partner, { resolveSeats,
|
|
333
|
+
includeOwnPendingFor: verifiedToken.sub })` (the same `sub` as the
|
|
334
|
+
writer's `actor.id`). See below.
|
|
335
|
+
- **Confidential holders (pl-iza, 0.32.0).** Never return, persist, or log
|
|
336
|
+
a confidential address; use `confidentialCount` / `confidential.count`;
|
|
337
|
+
only `deliver` touches addresses. A sender sees the count (or one
|
|
338
|
+
all-or-nothing status), never `deliver`'s per-holder numbers. The
|
|
339
|
+
`sendOne` transport must not log `to`.
|
|
340
|
+
- **Logging.** On a thrown error log only its `name` and `code`: a
|
|
341
|
+
`PointOfContactShapeError` lists a stored row's issues and a driver error
|
|
342
|
+
can echo a stored value. Refusals carry no stored value.
|
|
343
|
+
- **Order of deployment.** The platform deploys and runs `ensurePocIndexes`
|
|
344
|
+
first; an app's writes are refused (`indexes_missing`) until it has.
|
|
345
|
+
- **Database privileges** the calling app's user needs on platform-db:
|
|
346
|
+
`find` on `agencies`, `organizations`, `registry_agencies` and
|
|
347
|
+
`pointsofcontact` (`countDocuments` is a `find`); `insert`, `remove` (a
|
|
348
|
+
withdrawn over-cap row) and `listIndexes` on `pointsofcontact`. No
|
|
349
|
+
`createIndex`, `dropIndex`, `update` or any other collection.
|
|
350
|
+
|
|
351
|
+
**The adder's own pending adds in the pre-fill** (Nate, 2026-10-15).
|
|
352
|
+
`listReferralContactsForPartner(db, partner, { resolveSeats,
|
|
353
|
+
includeOwnPendingFor: sub })` returns the partner's confirmed, network-visible
|
|
354
|
+
Referrals (magic link) recipients as before, then the asking advocate's OWN
|
|
355
|
+
pending in-app adds on that partner (active, `origin: in_app`, `createdBy`
|
|
356
|
+
= `sub`, tagged Referrals (magic link)), each marked `pending: true`
|
|
357
|
+
(`ReferralRecipient.pending`) so a UI can label it. Nobody else's pending add
|
|
358
|
+
is ever returned; confidential rows stay excluded (counted only, see 0.32.0); an
|
|
359
|
+
email a confirmed recipient already has is not repeated. `sub` is the
|
|
360
|
+
advocate's Auth0 `sub` from the verified token, the same pinning as the
|
|
361
|
+
writer's `actor.id`. Without the option the read is unchanged.
|
|
362
|
+
|
|
363
|
+
**Known deviations:**
|
|
364
|
+
|
|
365
|
+
- Seat-linked contacts still read ONE email and ONE phone from `users` until
|
|
366
|
+
a person Contact log exists (pl-9h4). Canon's motivating case (Crysta's own
|
|
367
|
+
seat-linked contact, `ct-crysta`) is therefore not yet met.
|
|
368
|
+
- Entries are removed, not retired. Canon's write-in ledger keeps retired
|
|
369
|
+
entries stamped `retiredOn` (retire-not-remove, `agencyhub.jsx` L8181-L8185).
|
|
370
|
+
- The identity key uses the preferred email only, as canon's uses the card's
|
|
371
|
+
flat email (`agencyhub.jsx` `hubSavePocs` L382-L384). Changing the preferred email changes
|
|
372
|
+
`identity_key`, and a secondary email shared with another row is not
|
|
373
|
+
deduplicated.
|
|
374
|
+
|
|
375
|
+
**Breaking surface** (every export whose shape changed):
|
|
376
|
+
|
|
377
|
+
| Export | 0.28.0 | 0.30.0 |
|
|
378
|
+
|---|---|---|
|
|
379
|
+
| `POC_SUBJECT_TYPES` / `PocSubjectType` | `… · site · …` | `… · location · …` |
|
|
380
|
+
| `PocSubjectRef` | `subject_type: "site"` | `subject_type: "location"` |
|
|
381
|
+
| `PocOwnerSchema` / `PocOwner` | accepts `site` | accepts `location` |
|
|
382
|
+
| `PocDetailsSchema` / `PocDetails` | `email?`, `phone?` | `emails?`, `phones?` (`PocContactEntry[]`; single fields refused) |
|
|
383
|
+
| `PocInAppSchema` / `PocInApp` | `email` (required), `phone?` | `emails` (at least one), `phones?` |
|
|
384
|
+
| `PocSeedSchema` / `PocSeed`, `PocPatchSchema` / `PocPatch` | via `PocDetailsSchema` | via `PocDetailsSchema` |
|
|
385
|
+
| `PointOfContactDocSchema` / `PointOfContactDoc` | `email`, `phone` | `emails`, `phones` |
|
|
386
|
+
| `PocRuleInput` | `email`, `phone` | `emails`, `phones` |
|
|
387
|
+
| `pocIdentityKey` input | `email` | `emails` (keys on the preferred) |
|
|
388
|
+
| `PointOfContactOwnerView` / `PointOfContactStewardView` | `email`, `phone` (stored) | `emails`, `phones` (row's own) + read-only `email`, `phone` (reachable preferred) |
|
|
389
|
+
| `PointOfContactNetworkView` / `ReferralRecipient` | `email`, `phone` | adds `emails`, `phones`; `email` / `phone` are the preferred entries' projections |
|
|
390
|
+
|
|
19
391
|
## CVC-136 core indicators 1.2.0 / 0.29.0
|
|
20
392
|
|
|
21
393
|
0.29.0 appends ONE core indicator, `potential_trafficking_victim_recorded`
|
|
@@ -57,7 +429,7 @@ What it holds:
|
|
|
57
429
|
`readServiceListings(db, query, { categories })`, the one raw-driver read
|
|
58
430
|
(by org, org + program, category keys or id).
|
|
59
431
|
|
|
60
|
-
Folded into
|
|
432
|
+
Folded into 0.28.0 before its release (co-6zr), so every app reads listings as
|
|
61
433
|
the Platform's own Network reads do (platform `feat/pl-srl-followups`,
|
|
62
434
|
pl-6uk / pl-avy):
|
|
63
435
|
|
|
@@ -104,6 +476,7 @@ What it holds:
|
|
|
104
476
|
- `toDirectoryOrganizationView` (one view over both shapes),
|
|
105
477
|
`readDirectoryOrganization` and `readAgencyOwnOrganization`, the raw-driver
|
|
106
478
|
reads (pass `toObjectId` so a string id matches an ObjectId `_id`).
|
|
479
|
+
|
|
107
480
|
## points-of-contact / 0.28.0
|
|
108
481
|
|
|
109
482
|
0.28.0 (pl-3r8) ships the **Point of contact** read contract at
|