@htilabs/platform-common-models 0.86.0 → 0.87.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 +18 -0
- package/dist/{index-XWSYon40.d.cts → index-1pWiqEBC.d.cts} +1 -1
- package/dist/{index-Bh1zO_Vu.d.ts → index-uz57Fic9.d.ts} +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/org-merge/index.cjs.map +1 -1
- package/dist/org-merge/index.js.map +1 -1
- package/dist/points-of-contact/index.cjs +222 -23
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.d.cts +50 -5
- package/dist/points-of-contact/index.d.ts +50 -5
- package/dist/points-of-contact/index.js +219 -22
- package/dist/points-of-contact/index.js.map +1 -1
- package/dist/reader-BmhzOis-.d.ts +273 -0
- package/dist/reader-DfQtdw6n.d.cts +273 -0
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/dist/seat-logs/index.cjs +815 -0
- package/dist/seat-logs/index.cjs.map +1 -0
- package/dist/seat-logs/index.d.cts +274 -0
- package/dist/seat-logs/index.d.ts +274 -0
- package/dist/seat-logs/index.js +742 -0
- package/dist/seat-logs/index.js.map +1 -0
- package/dist/validation/index.d.cts +1 -1
- package/dist/validation/index.d.ts +1 -1
- package/package.json +6 -1
- package/src/pointsOfContact/__tests__/seatContactLog.test.ts +170 -0
- package/src/pointsOfContact/readRules.ts +22 -4
- package/src/pointsOfContact/reader.ts +95 -1
- package/src/pointsOfContact/schemas.ts +4 -3
- package/src/seatLogs/__tests__/seatLogs.review.test.ts +222 -0
- package/src/seatLogs/__tests__/seatLogs.test.ts +335 -0
- package/src/seatLogs/index.ts +15 -0
- package/src/seatLogs/log.ts +700 -0
- package/src/seatLogs/personId.ts +100 -0
- package/src/seatLogs/personSlugWordlists.ts +40 -0
- package/src/seatLogs/reader.ts +143 -0
- package/src/seatLogs/schemas.ts +118 -0
- package/dist/{agency-CnVTwLeV.d.ts → agency-BHv54o79.d.ts} +4 -4
- package/dist/{agency-8ufZJJDH.d.cts → agency-Djp57S71.d.cts} +4 -4
- package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-DAuhe0cd.d.cts} +8 -8
- package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-DAuhe0cd.d.ts} +8 -8
|
@@ -0,0 +1,700 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The seat name log and contact log: the rules every writer applies. Pure, no
|
|
3
|
+
* I/O. Each operation takes the subject's current entries, returns the next
|
|
4
|
+
* entries plus which entries were inserted and which changed, so the caller
|
|
5
|
+
* writes exactly those rows (insert the new, update the changed) and never
|
|
6
|
+
* rewrites the whole log.
|
|
7
|
+
*
|
|
8
|
+
* Canon: platform-prototype `src/screens.jsx` @ 398fb24 (`SeatNamesLedger`
|
|
9
|
+
* L25149-L25288, `SeatMethodsLedger` L24981-L25137, `umSeatPhoneGuard`
|
|
10
|
+
* L24972-L24978, the email / name guards L25335-L25340), the store's
|
|
11
|
+
* `addEntry` / `act` (`src/objectStore.js` L660-L740: phone normalized at the
|
|
12
|
+
* boundary, the `digits` key stamped, `events[]` appended) and the spine
|
|
13
|
+
* cascade (`src/objectStructuresEngine.generated.js` L942-L1049: one display
|
|
14
|
+
* name per subject, one preferred contact per subject and type, an archived
|
|
15
|
+
* entry loses both flags).
|
|
16
|
+
*
|
|
17
|
+
* Rules carried here:
|
|
18
|
+
* - Display / preferred invariants: one live `is_display` (and with it
|
|
19
|
+
* `is_preferred`, which the profile always moves together) per subject on
|
|
20
|
+
* the name log; one live `is_preferred` per subject AND contact type on the
|
|
21
|
+
* contact log. The first live entry takes the mark.
|
|
22
|
+
* - Correction = insert the new entry, carry the mark onto it, archive the
|
|
23
|
+
* old one (`period_end` = today). Never edit in place. Correcting INTO a
|
|
24
|
+
* value already live hands that entry the mark and archives the wrong one.
|
|
25
|
+
* - A name log with no entries reads its seat's flat name as a synthetic
|
|
26
|
+
* `__flat__` row; the log is seeded from it (a `legal` display entry) only
|
|
27
|
+
* on the first real act.
|
|
28
|
+
* - The display name can't be retired (the ✕ is absent on its row); a
|
|
29
|
+
* preferred contact can't be retired while another live entry of its type
|
|
30
|
+
* exists.
|
|
31
|
+
* - Every act targets a LIVE entry; a retired entry id is refused
|
|
32
|
+
* (`entry_not_live`) with nothing changed — a stale tab or a double submit
|
|
33
|
+
* never moves a mark onto, re-dates or corrects a retired entry.
|
|
34
|
+
* - `events[]` is stamped as the store stamps it: per store call, `cascade`
|
|
35
|
+
* on every row whose display / preferred / period_end changed (the target
|
|
36
|
+
* included), then the call's own event (`add`, `set_display`,
|
|
37
|
+
* `set_preferred`, `archive`) on its target.
|
|
38
|
+
* - Entry ids: the default minter never collides within one act; the store
|
|
39
|
+
* needs a unique index on `entry_id` for collisions across requests.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
import {
|
|
43
|
+
SeatContactEntrySchema,
|
|
44
|
+
SeatNameEntrySchema,
|
|
45
|
+
type SeatContactEntry,
|
|
46
|
+
type SeatContactType,
|
|
47
|
+
type SeatLogSubject,
|
|
48
|
+
type SeatNameEntry,
|
|
49
|
+
type SeatNameType,
|
|
50
|
+
} from "./schemas.js";
|
|
51
|
+
|
|
52
|
+
/** The synthetic row id a seat with no name log shows its flat name under. */
|
|
53
|
+
export const FLAT_NAME_ENTRY_ID = "__flat__";
|
|
54
|
+
|
|
55
|
+
/** Who acts and when. `mintId` overrides the default id shape (tests). */
|
|
56
|
+
export interface SeatLogContext {
|
|
57
|
+
/** The acting seat's id (stamped on `events[]`). */
|
|
58
|
+
actor: string;
|
|
59
|
+
/** ISO instant; `period_end` on an archive is its day. Defaults to now. */
|
|
60
|
+
at?: string;
|
|
61
|
+
/**
|
|
62
|
+
* Mints an entry id. Default {@link mintSeatLogEntryId}. An id that clashes
|
|
63
|
+
* with a row already in the log is re-minted (up to 20 tries).
|
|
64
|
+
*/
|
|
65
|
+
mintId?: (kind: "name" | "contact", subject: SeatLogSubject) => string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** What an operation did. `entries` is the subject's whole next log. */
|
|
69
|
+
export interface SeatLogChange<E> {
|
|
70
|
+
entries: E[];
|
|
71
|
+
/** New rows to insert. */
|
|
72
|
+
inserted: E[];
|
|
73
|
+
/** Existing rows whose flags, dates, notes or events changed. */
|
|
74
|
+
updated: E[];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** A refused act: the reason, in the profile's words. */
|
|
78
|
+
export class SeatLogRefusal extends Error {
|
|
79
|
+
constructor(
|
|
80
|
+
readonly code:
|
|
81
|
+
| "name_blank"
|
|
82
|
+
| "display_name_not_retirable"
|
|
83
|
+
| "preferred_contact_not_retirable"
|
|
84
|
+
| "entry_not_found"
|
|
85
|
+
| "entry_not_live"
|
|
86
|
+
| "email_shape"
|
|
87
|
+
| "email_taken"
|
|
88
|
+
| "phone_no_digits"
|
|
89
|
+
| "phone_too_short"
|
|
90
|
+
| "phone_too_long",
|
|
91
|
+
message: string,
|
|
92
|
+
) {
|
|
93
|
+
super(message);
|
|
94
|
+
this.name = "SeatLogRefusal";
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const B36 = "0123456789abcdefghijklmnopqrstuvwxyz";
|
|
99
|
+
|
|
100
|
+
/** `n` random base-36 characters (Web Crypto when the runtime has it). */
|
|
101
|
+
function randomB36(n: number): string {
|
|
102
|
+
const c = (globalThis as { crypto?: { getRandomValues?(a: Uint8Array): Uint8Array } }).crypto;
|
|
103
|
+
const bytes = new Uint8Array(n);
|
|
104
|
+
if (c?.getRandomValues) c.getRandomValues(bytes);
|
|
105
|
+
else for (let i = 0; i < n; i++) bytes[i] = Math.floor(Math.random() * 256);
|
|
106
|
+
let out = "";
|
|
107
|
+
for (let i = 0; i < n; i++) out += B36[bytes[i] % 36];
|
|
108
|
+
return out;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The entry id: the prototype's shape, `nm-<subject>-rt<time><rand>` /
|
|
113
|
+
* `ci-<subject>-rt<time><rand>`, with 8 random base-36 characters where the
|
|
114
|
+
* prototype has 1, so two ids minted in the same millisecond do not collide
|
|
115
|
+
* (36^8 ≈ 2.8 × 10^12). Within one act a clash with a row already in the log
|
|
116
|
+
* is re-minted (see {@link SeatLogContext.mintId}); across subjects and
|
|
117
|
+
* requests the store's unique index on `entry_id` is the backstop.
|
|
118
|
+
*/
|
|
119
|
+
export function mintSeatLogEntryId(kind: "name" | "contact", subject: SeatLogSubject): string {
|
|
120
|
+
return (kind === "name" ? "nm-" : "ci-") + subject.subject_id + "-rt" +
|
|
121
|
+
Date.now().toString(36).slice(-5) + randomB36(8);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// ─── shared engine ──────────────────────────────────────────────────────────
|
|
125
|
+
|
|
126
|
+
type AnyEntry = SeatNameEntry | SeatContactEntry;
|
|
127
|
+
|
|
128
|
+
const isLive = (e: Pick<AnyEntry, "period_end">) => !e.period_end;
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* What the store compares to decide a row "changed" (canon `withSpineView`,
|
|
132
|
+
* objectStore.js L166-L191: display · preferred · primary · period_end; these
|
|
133
|
+
* logs carry no primary).
|
|
134
|
+
*/
|
|
135
|
+
const sigOf = (e: AnyEntry) =>
|
|
136
|
+
[("is_display" in e ? !!e.is_display : false), !!e.is_preferred, false, e.period_end || ""].join("|");
|
|
137
|
+
|
|
138
|
+
const flagOf = (r: AnyEntry, flag: "is_display" | "is_preferred"): boolean =>
|
|
139
|
+
!!(r as unknown as Record<string, unknown>)[flag];
|
|
140
|
+
const setFlagValue = (r: AnyEntry, flag: "is_display" | "is_preferred", v: boolean) => {
|
|
141
|
+
(r as unknown as Record<string, unknown>)[flag] = v;
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Working copy: deep-copies the subject's rows and records events exactly as
|
|
146
|
+
* the prototype store does. Each store call is one UNIT: the rows' state is
|
|
147
|
+
* snapshotted, the cascade runs, `cascade` is stamped on every row whose
|
|
148
|
+
* display / preferred / period_end changed (the target included), then the
|
|
149
|
+
* unit's own event (`add`, or the act's name) is appended to its target.
|
|
150
|
+
*/
|
|
151
|
+
class Draft<E extends AnyEntry> {
|
|
152
|
+
rows: E[];
|
|
153
|
+
private readonly added = new Set<string>();
|
|
154
|
+
private readonly touched = new Set<string>();
|
|
155
|
+
readonly at: string;
|
|
156
|
+
readonly day: string;
|
|
157
|
+
|
|
158
|
+
constructor(
|
|
159
|
+
entries: readonly E[],
|
|
160
|
+
readonly subject: SeatLogSubject,
|
|
161
|
+
readonly ctx: SeatLogContext,
|
|
162
|
+
) {
|
|
163
|
+
this.rows = entries
|
|
164
|
+
.filter((e) => e.subject_id === subject.subject_id && e.subject_type === subject.subject_type)
|
|
165
|
+
.map((e) => JSON.parse(JSON.stringify(e)) as E);
|
|
166
|
+
this.at = ctx.at ?? new Date().toISOString();
|
|
167
|
+
this.day = this.at.slice(0, 10);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
live(): E[] {
|
|
171
|
+
return this.rows.filter(isLive);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** The LIVE entry an act targets. A retired entry is refused, never acted on. */
|
|
175
|
+
findLive(id: string): E {
|
|
176
|
+
const r = this.rows.find((x) => x.entry_id === id);
|
|
177
|
+
if (!r) throw new SeatLogRefusal("entry_not_found", `No entry ${id} in this log.`);
|
|
178
|
+
if (!isLive(r)) throw new SeatLogRefusal("entry_not_live", `Entry ${id} is retired.`);
|
|
179
|
+
return r;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
private stamp(r: E, act: string): void {
|
|
183
|
+
r.events = [...(r.events ?? []), { act, at: this.at, actor: this.ctx.actor }];
|
|
184
|
+
this.touched.add(r.entry_id);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
private unit(mutate: () => void, target: E, act: string, skip?: E): void {
|
|
188
|
+
const before = new Map(this.rows.map((r) => [r, sigOf(r)] as const));
|
|
189
|
+
mutate();
|
|
190
|
+
for (const r of this.rows) {
|
|
191
|
+
const was = before.get(r);
|
|
192
|
+
if (r !== skip && was !== undefined && was !== sigOf(r)) this.stamp(r, "cascade");
|
|
193
|
+
}
|
|
194
|
+
this.stamp(target, act);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Insert a new row (canon `addEntry`): a flag it carries clears that flag
|
|
199
|
+
* on the subject's other live rows (contacts: same type only).
|
|
200
|
+
*/
|
|
201
|
+
insert(r: E): void {
|
|
202
|
+
if (this.rows.some((x) => x.entry_id === r.entry_id)) {
|
|
203
|
+
throw new Error(`seat-logs: entry_id_exists: ${r.entry_id}`);
|
|
204
|
+
}
|
|
205
|
+
this.unit(() => {
|
|
206
|
+
this.rows.push(r);
|
|
207
|
+
const scope = (x: E) => !("contact_type" in r) ||
|
|
208
|
+
(x as SeatContactEntry).contact_type === (r as SeatContactEntry).contact_type;
|
|
209
|
+
for (const flag of ["is_display", "is_preferred"] as const) {
|
|
210
|
+
if (flagOf(r, flag)) this.clearOthers(r, flag, scope);
|
|
211
|
+
}
|
|
212
|
+
}, r, "add", r);
|
|
213
|
+
this.added.add(r.entry_id);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
private clearOthers(target: E, flag: "is_display" | "is_preferred", scope: (r: E) => boolean) {
|
|
217
|
+
for (const x of this.rows) {
|
|
218
|
+
if (x !== target && isLive(x) && scope(x) && flagOf(x, flag)) setFlagValue(x, flag, false);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** Act `set_display` / `set_preferred`: the mark moves to `target` within `scope`. */
|
|
223
|
+
mark(target: E, flag: "is_display" | "is_preferred", scope: (r: E) => boolean): void {
|
|
224
|
+
this.unit(() => {
|
|
225
|
+
this.clearOthers(target, flag, scope);
|
|
226
|
+
setFlagValue(target, flag, true);
|
|
227
|
+
}, target, flag === "is_display" ? "set_display" : "set_preferred");
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/** Act `archive`: stamp `period_end`, clear both marks (spine `archiveEntry`). */
|
|
231
|
+
archive(r: E): void {
|
|
232
|
+
this.unit(() => {
|
|
233
|
+
r.period_end = this.day;
|
|
234
|
+
if ("is_display" in r) setFlagValue(r, "is_display", false);
|
|
235
|
+
r.is_preferred = false;
|
|
236
|
+
}, r, "archive");
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** A fresh id, re-minted on a clash with any row in this log. */
|
|
240
|
+
newId(kind: "name" | "contact"): string {
|
|
241
|
+
const mint = this.ctx.mintId ?? mintSeatLogEntryId;
|
|
242
|
+
for (let i = 0; i < 20; i++) {
|
|
243
|
+
const id = mint(kind, this.subject);
|
|
244
|
+
if (!this.rows.some((x) => x.entry_id === id)) return id;
|
|
245
|
+
}
|
|
246
|
+
throw new Error("seat-logs: entry_id_exists: could not mint an unused entry id in 20 tries");
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
done(): SeatLogChange<E> {
|
|
250
|
+
return {
|
|
251
|
+
entries: this.rows,
|
|
252
|
+
inserted: this.rows.filter((r) => this.added.has(r.entry_id)),
|
|
253
|
+
updated: this.rows.filter((r) => this.touched.has(r.entry_id) && !this.added.has(r.entry_id)),
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
const base = (subject: SeatLogSubject) => ({
|
|
259
|
+
subject_id: subject.subject_id,
|
|
260
|
+
subject_type: subject.subject_type,
|
|
261
|
+
source: "admin_hub",
|
|
262
|
+
method: "direct_entry",
|
|
263
|
+
});
|
|
264
|
+
|
|
265
|
+
const correctsNote = (prior: string, old: string) =>
|
|
266
|
+
[prior, "Corrects “" + old + "”"].filter(Boolean).join(" · ");
|
|
267
|
+
|
|
268
|
+
// ─── names ──────────────────────────────────────────────────────────────────
|
|
269
|
+
|
|
270
|
+
/** The profile's refusal for a blank name. */
|
|
271
|
+
export const SEAT_NAME_BLANK_REFUSAL = "A member keeps a name — the directory row can't go blank.";
|
|
272
|
+
|
|
273
|
+
/** Live entries, in log order. */
|
|
274
|
+
export function liveSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[] {
|
|
275
|
+
return entries.filter(isLive);
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Retired entries ("Past names"). */
|
|
279
|
+
export function pastSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[] {
|
|
280
|
+
return entries.filter((e) => !isLive(e));
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/** The display entry: the live one marked display, else the first live one, else null. */
|
|
284
|
+
export function seatDisplayNameEntry(entries: readonly SeatNameEntry[]): SeatNameEntry | null {
|
|
285
|
+
const live = liveSeatNames(entries);
|
|
286
|
+
return live.find((e) => e.is_display) ?? live[0] ?? null;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* The seat's flat `name` projection: the display entry's `raw`, or `null`
|
|
291
|
+
* when the log has no live entry (the caller keeps the flat name as it is —
|
|
292
|
+
* the prototype only writes a non-empty projection).
|
|
293
|
+
*/
|
|
294
|
+
export function seatNameProjection(entries: readonly SeatNameEntry[]): string | null {
|
|
295
|
+
return seatDisplayNameEntry(entries)?.raw || null;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/** A synthetic display row standing for the flat name when the log is empty. */
|
|
299
|
+
export type FlatNameRow = Pick<SeatNameEntry, "entry_id" | "raw" | "name_type" | "is_display">;
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* The rows the Names list draws: the live log, or the flat name as one
|
|
303
|
+
* `__flat__` display row when the log has none (nothing is written for it).
|
|
304
|
+
*/
|
|
305
|
+
export function seatNameRows(
|
|
306
|
+
entries: readonly SeatNameEntry[],
|
|
307
|
+
flatName: string | null | undefined,
|
|
308
|
+
): (SeatNameEntry | FlatNameRow)[] {
|
|
309
|
+
const live = liveSeatNames(entries);
|
|
310
|
+
if (live.length) return live;
|
|
311
|
+
const flat = (flatName ?? "").trim();
|
|
312
|
+
return flat ? [{ entry_id: FLAT_NAME_ENTRY_ID, raw: flat, name_type: "legal", is_display: true }] : [];
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function seedFromFlat(d: Draft<SeatNameEntry>, flatName: string | null | undefined): void {
|
|
316
|
+
const flat = (flatName ?? "").trim();
|
|
317
|
+
if (d.live().length || !flat) return;
|
|
318
|
+
d.insert(SeatNameEntrySchema.parse({
|
|
319
|
+
entry_id: d.newId("name"), ...base(d.subject),
|
|
320
|
+
name_type: "legal", raw: flat, is_display: true, is_preferred: true,
|
|
321
|
+
period_start: "", period_end: "", notes: "",
|
|
322
|
+
}));
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Seed the log from the seat's flat name (a `legal` display entry). A no-op
|
|
327
|
+
* when the log already has a live entry or the flat name is blank. Every act
|
|
328
|
+
* below does this first; exposed for a caller that needs the log minted.
|
|
329
|
+
*/
|
|
330
|
+
export function seedSeatNameLog(
|
|
331
|
+
entries: readonly SeatNameEntry[],
|
|
332
|
+
subject: SeatLogSubject,
|
|
333
|
+
flatName: string | null | undefined,
|
|
334
|
+
ctx: SeatLogContext,
|
|
335
|
+
): SeatLogChange<SeatNameEntry> {
|
|
336
|
+
const d = new Draft(entries, subject, ctx);
|
|
337
|
+
seedFromFlat(d, flatName);
|
|
338
|
+
return d.done();
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* Add a name. Seeds from the flat name first; a name already live (exact
|
|
343
|
+
* text) is a no-op; the first live name becomes the display name.
|
|
344
|
+
*/
|
|
345
|
+
export function addSeatName(
|
|
346
|
+
entries: readonly SeatNameEntry[],
|
|
347
|
+
subject: SeatLogSubject,
|
|
348
|
+
input: { raw: string; name_type: SeatNameType },
|
|
349
|
+
ctx: SeatLogContext & { flatName?: string | null },
|
|
350
|
+
): SeatLogChange<SeatNameEntry> {
|
|
351
|
+
const v = input.raw.trim();
|
|
352
|
+
if (!v) throw new SeatLogRefusal("name_blank", SEAT_NAME_BLANK_REFUSAL);
|
|
353
|
+
const d = new Draft(entries, subject, ctx);
|
|
354
|
+
seedFromFlat(d, ctx.flatName);
|
|
355
|
+
if (d.live().some((r) => r.raw === v)) return d.done();
|
|
356
|
+
const first = d.live().length === 0;
|
|
357
|
+
d.insert(SeatNameEntrySchema.parse({
|
|
358
|
+
entry_id: d.newId("name"), ...base(subject),
|
|
359
|
+
name_type: input.name_type, raw: v, is_display: first, is_preferred: first,
|
|
360
|
+
period_start: "", period_end: "", notes: "",
|
|
361
|
+
}));
|
|
362
|
+
return d.done();
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
function markDisplay(d: Draft<SeatNameEntry>, target: SeatNameEntry): void {
|
|
366
|
+
d.mark(target, "is_display", () => true);
|
|
367
|
+
d.mark(target, "is_preferred", () => true);
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
/** Make an entry the display name (★); moves the preferred mark with it. */
|
|
371
|
+
export function setSeatDisplayName(
|
|
372
|
+
entries: readonly SeatNameEntry[],
|
|
373
|
+
subject: SeatLogSubject,
|
|
374
|
+
entryId: string,
|
|
375
|
+
ctx: SeatLogContext & { flatName?: string | null },
|
|
376
|
+
): SeatLogChange<SeatNameEntry> {
|
|
377
|
+
const d = new Draft(entries, subject, ctx);
|
|
378
|
+
seedFromFlat(d, ctx.flatName);
|
|
379
|
+
markDisplay(d, d.findLive(entryId));
|
|
380
|
+
return d.done();
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* Correct a name: insert the corrected entry ("Corrects “old”" in its notes),
|
|
385
|
+
* carry the display mark onto it, archive the old one. `entryId` may be
|
|
386
|
+
* `__flat__` (the log is seeded from the flat name, then corrected). The same
|
|
387
|
+
* text (after trimming) is a no-op.
|
|
388
|
+
*/
|
|
389
|
+
export function correctSeatName(
|
|
390
|
+
entries: readonly SeatNameEntry[],
|
|
391
|
+
subject: SeatLogSubject,
|
|
392
|
+
entryId: string,
|
|
393
|
+
next: string,
|
|
394
|
+
ctx: SeatLogContext & { flatName?: string | null },
|
|
395
|
+
): SeatLogChange<SeatNameEntry> {
|
|
396
|
+
const v = next.trim();
|
|
397
|
+
if (!v) throw new SeatLogRefusal("name_blank", SEAT_NAME_BLANK_REFUSAL);
|
|
398
|
+
const d = new Draft(entries, subject, ctx);
|
|
399
|
+
let target: SeatNameEntry;
|
|
400
|
+
if (entryId === FLAT_NAME_ENTRY_ID) {
|
|
401
|
+
const flat = (ctx.flatName ?? "").trim();
|
|
402
|
+
if (flat && v === flat && !d.live().length) return d.done(); // unchanged: nothing is seeded
|
|
403
|
+
seedFromFlat(d, ctx.flatName);
|
|
404
|
+
const hit = d.live().find((x) => x.raw === flat);
|
|
405
|
+
if (!hit) throw new SeatLogRefusal("entry_not_found", "No flat name to correct.");
|
|
406
|
+
target = hit;
|
|
407
|
+
} else {
|
|
408
|
+
target = d.findLive(entryId);
|
|
409
|
+
}
|
|
410
|
+
// Correcting to the same text changes nothing (the prototype's editor only
|
|
411
|
+
// commits a changed value; the contact path has the same no-op).
|
|
412
|
+
if (v === target.raw) return d.done();
|
|
413
|
+
const dupe = d.live().find((x) => x.raw === v && x.entry_id !== target.entry_id);
|
|
414
|
+
if (dupe) {
|
|
415
|
+
if (target.is_display) markDisplay(d, dupe);
|
|
416
|
+
d.archive(target);
|
|
417
|
+
return d.done();
|
|
418
|
+
}
|
|
419
|
+
const added = SeatNameEntrySchema.parse({
|
|
420
|
+
entry_id: d.newId("name"), ...base(subject),
|
|
421
|
+
name_type: target.name_type || "legal", raw: v, is_display: false, is_preferred: false,
|
|
422
|
+
period_start: target.period_start || "", period_end: "",
|
|
423
|
+
notes: correctsNote(target.notes, target.raw),
|
|
424
|
+
});
|
|
425
|
+
d.insert(added);
|
|
426
|
+
if (target.is_display) markDisplay(d, added);
|
|
427
|
+
d.archive(target);
|
|
428
|
+
return d.done();
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/** Retire a name (stays in the log, dated). The display name is refused. */
|
|
432
|
+
export function retireSeatName(
|
|
433
|
+
entries: readonly SeatNameEntry[],
|
|
434
|
+
subject: SeatLogSubject,
|
|
435
|
+
entryId: string,
|
|
436
|
+
ctx: SeatLogContext,
|
|
437
|
+
): SeatLogChange<SeatNameEntry> {
|
|
438
|
+
const d = new Draft(entries, subject, ctx);
|
|
439
|
+
const target = d.findLive(entryId);
|
|
440
|
+
if (target.is_display) {
|
|
441
|
+
throw new SeatLogRefusal(
|
|
442
|
+
"display_name_not_retirable",
|
|
443
|
+
"The display name can't be retired — star another name first.",
|
|
444
|
+
);
|
|
445
|
+
}
|
|
446
|
+
d.archive(target);
|
|
447
|
+
return d.done();
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
// ─── contacts ───────────────────────────────────────────────────────────────
|
|
451
|
+
|
|
452
|
+
/**
|
|
453
|
+
* How a phone is DRAWN and stored on the seat log: every non-digit dropped, a
|
|
454
|
+
* redundant US `1` dropped, `(AAA) BBB-CCCC`, `+cc (AAA) BBB-CCCC` past ten
|
|
455
|
+
* digits. Canon `formatPhone` (objectStructuresEngine L232-L244), verbatim in
|
|
456
|
+
* behaviour. Empty when there is no digit.
|
|
457
|
+
*/
|
|
458
|
+
export function formatSeatPhone(s: string): string {
|
|
459
|
+
let d = String(s ?? "").replace(/\D/g, "");
|
|
460
|
+
if (!d) return "";
|
|
461
|
+
if (d.length === 11 && d.charAt(0) === "1") d = d.slice(1);
|
|
462
|
+
if (d.length <= 3) return `(${d}`;
|
|
463
|
+
if (d.length <= 6) return `(${d.slice(0, 3)}) ${d.slice(3)}`;
|
|
464
|
+
if (d.length <= 10) return `(${d.slice(0, 3)}) ${d.slice(3, 6)}-${d.slice(6)}`;
|
|
465
|
+
const cc = d.slice(0, d.length - 10);
|
|
466
|
+
const r = d.slice(d.length - 10);
|
|
467
|
+
return `+${cc} (${r.slice(0, 3)}) ${r.slice(3, 6)}-${r.slice(6)}`;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/**
|
|
471
|
+
* How a value is WRITTEN (PHONE-NORMALIZE 2026-08-28): trimmed; a phone in
|
|
472
|
+
* {@link formatSeatPhone}'s form, or as typed when it has no digit. Canon
|
|
473
|
+
* `canonContactValue` (objectStore L618-L623).
|
|
474
|
+
*/
|
|
475
|
+
export function canonSeatContactValue(type: SeatContactType, value: string): string {
|
|
476
|
+
const v = String(value ?? "").trim();
|
|
477
|
+
if (type !== "phone" || !v) return v;
|
|
478
|
+
return formatSeatPhone(v) || v;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/**
|
|
482
|
+
* WHICH contact this is (PHONE-DIGITS-KEY 2026-08-28): a phone's digits with a
|
|
483
|
+
* leading US `1` dropped; an email's lowercased text. Canon `contactKey`
|
|
484
|
+
* (objectStore L648-L657) over `phoneDigits` (engine L268-L272).
|
|
485
|
+
*/
|
|
486
|
+
export function seatContactKey(type: SeatContactType, value: string): string {
|
|
487
|
+
const v = String(value ?? "").trim();
|
|
488
|
+
if (!v) return "";
|
|
489
|
+
if (type === "phone") {
|
|
490
|
+
const d = v.replace(/\D/g, "");
|
|
491
|
+
return d.length === 11 && d.charAt(0) === "1" ? d.slice(1) : d;
|
|
492
|
+
}
|
|
493
|
+
return v.toLowerCase();
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* The phone guard (`umSeatPhoneGuard`): `""` when acceptable (blank included —
|
|
498
|
+
* a seat may have no number on file), else the refusal in the profile's words.
|
|
499
|
+
* 7-15 digits (the object spine's `detectFromInput` bounds).
|
|
500
|
+
*/
|
|
501
|
+
export function seatPhoneRefusal(value: string): string {
|
|
502
|
+
const t = String(value ?? "").trim();
|
|
503
|
+
if (!t) return "";
|
|
504
|
+
const d = t.replace(/\D/g, "");
|
|
505
|
+
if (!d) return "That doesn't have any numbers in it — a phone entry needs digits.";
|
|
506
|
+
if (d.length < 7) return "That's too short for a phone number — it needs at least 7 digits.";
|
|
507
|
+
if (d.length > 15) return "That's too long for a phone number — 15 digits is the international maximum.";
|
|
508
|
+
return "";
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* The email guard: `""` when acceptable (blank included), else the refusal.
|
|
513
|
+
* `otherSeatEmails` are the addresses on OTHER seats (the directory-uniqueness
|
|
514
|
+
* check); the caller supplies them.
|
|
515
|
+
*/
|
|
516
|
+
export function seatEmailRefusal(value: string, otherSeatEmails: Iterable<string> = []): string {
|
|
517
|
+
const t = String(value ?? "").trim();
|
|
518
|
+
if (!t) return "";
|
|
519
|
+
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)) {
|
|
520
|
+
return "That isn't a working address yet — it needs an @ and a domain.";
|
|
521
|
+
}
|
|
522
|
+
const key = t.toLowerCase();
|
|
523
|
+
for (const e of otherSeatEmails) {
|
|
524
|
+
if ((e ?? "").toLowerCase() === key) return "Already in the directory — two seats can't share an address.";
|
|
525
|
+
}
|
|
526
|
+
return "";
|
|
527
|
+
}
|
|
528
|
+
|
|
529
|
+
function guardContact(
|
|
530
|
+
type: SeatContactType,
|
|
531
|
+
value: string,
|
|
532
|
+
otherSeatEmails?: Iterable<string>,
|
|
533
|
+
): void {
|
|
534
|
+
if (type === "email") {
|
|
535
|
+
const m = seatEmailRefusal(value, otherSeatEmails);
|
|
536
|
+
if (m) {
|
|
537
|
+
throw new SeatLogRefusal(m.startsWith("Already") ? "email_taken" : "email_shape", m);
|
|
538
|
+
}
|
|
539
|
+
return;
|
|
540
|
+
}
|
|
541
|
+
const m = seatPhoneRefusal(value);
|
|
542
|
+
if (!m) return;
|
|
543
|
+
const code = m.includes("numbers in it") ? "phone_no_digits"
|
|
544
|
+
: m.includes("too short") ? "phone_too_short" : "phone_too_long";
|
|
545
|
+
throw new SeatLogRefusal(code, m);
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
/** Live email and phone entries, in log order. */
|
|
549
|
+
export function liveSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[] {
|
|
550
|
+
return entries.filter(isLive);
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
/** Retired entries ("Past contact details"). */
|
|
554
|
+
export function pastSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[] {
|
|
555
|
+
return entries.filter((e) => !isLive(e));
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/** The preferred live entry of a type, else the first live one, else null. */
|
|
559
|
+
export function preferredSeatContact(
|
|
560
|
+
entries: readonly SeatContactEntry[],
|
|
561
|
+
type: SeatContactType,
|
|
562
|
+
): SeatContactEntry | null {
|
|
563
|
+
const live = liveSeatContacts(entries).filter((e) => e.contact_type === type);
|
|
564
|
+
return live.find((e) => e.is_preferred) ?? live[0] ?? null;
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/**
|
|
568
|
+
* The seat's flat `email` projection (the login projection): the preferred
|
|
569
|
+
* email's value, or `""` when the log has no live email. Canon
|
|
570
|
+
* `syncEmailProjection` (screens.jsx L24987-L24993).
|
|
571
|
+
*/
|
|
572
|
+
export function seatEmailProjection(entries: readonly SeatContactEntry[]): string {
|
|
573
|
+
return preferredSeatContact(entries, "email")?.value ?? "";
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
/** Whether the ✕ is offered: not on the preferred entry while another of its type is live. */
|
|
577
|
+
export function canRetireSeatContact(
|
|
578
|
+
entries: readonly SeatContactEntry[],
|
|
579
|
+
entry: SeatContactEntry,
|
|
580
|
+
): boolean {
|
|
581
|
+
if (!entry.is_preferred) return true;
|
|
582
|
+
return liveSeatContacts(entries).filter((x) => x.contact_type === entry.contact_type).length <= 1;
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
function contactRow(
|
|
586
|
+
d: Draft<SeatContactEntry>,
|
|
587
|
+
fields: Omit<
|
|
588
|
+
SeatContactEntry,
|
|
589
|
+
"entry_id" | "subject_id" | "subject_type" | "source" | "method" | "digits" | "events"
|
|
590
|
+
>,
|
|
591
|
+
): SeatContactEntry {
|
|
592
|
+
const row: SeatContactEntry = {
|
|
593
|
+
entry_id: d.newId("contact"), ...base(d.subject), ...fields,
|
|
594
|
+
} as SeatContactEntry;
|
|
595
|
+
if (row.contact_type === "phone") row.digits = seatContactKey("phone", row.value);
|
|
596
|
+
return SeatContactEntrySchema.parse(row);
|
|
597
|
+
}
|
|
598
|
+
|
|
599
|
+
/**
|
|
600
|
+
* Add an email or phone. Refused by the type's guard; normalized; a value
|
|
601
|
+
* already live of the same type (by {@link seatContactKey}) is a no-op; the
|
|
602
|
+
* first live entry of its type becomes preferred.
|
|
603
|
+
*/
|
|
604
|
+
export function addSeatContact(
|
|
605
|
+
entries: readonly SeatContactEntry[],
|
|
606
|
+
subject: SeatLogSubject,
|
|
607
|
+
input: { contact_type: SeatContactType; value: string },
|
|
608
|
+
ctx: SeatLogContext & { otherSeatEmails?: Iterable<string> },
|
|
609
|
+
): SeatLogChange<SeatContactEntry> {
|
|
610
|
+
const v0 = String(input.value ?? "").trim();
|
|
611
|
+
const d = new Draft(entries, subject, ctx);
|
|
612
|
+
if (!v0) return d.done();
|
|
613
|
+
guardContact(input.contact_type, v0, ctx.otherSeatEmails);
|
|
614
|
+
const type = input.contact_type;
|
|
615
|
+
const v = canonSeatContactValue(type, v0);
|
|
616
|
+
const key = seatContactKey(type, v);
|
|
617
|
+
const sameType = d.live().filter((r) => r.contact_type === type);
|
|
618
|
+
if (sameType.some((r) => seatContactKey(type, r.value) === key)) return d.done();
|
|
619
|
+
d.insert(contactRow(d, {
|
|
620
|
+
contact_type: type, value: v, use: "", is_preferred: sameType.length === 0,
|
|
621
|
+
safety_status: "", period_start: "", period_end: "", notes: "",
|
|
622
|
+
}));
|
|
623
|
+
return d.done();
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
function markPreferred(d: Draft<SeatContactEntry>, target: SeatContactEntry): void {
|
|
627
|
+
d.mark(target, "is_preferred", (r) => r.contact_type === target.contact_type);
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/** Make an entry the preferred of its type (☆ prefer). */
|
|
631
|
+
export function setPreferredSeatContact(
|
|
632
|
+
entries: readonly SeatContactEntry[],
|
|
633
|
+
subject: SeatLogSubject,
|
|
634
|
+
entryId: string,
|
|
635
|
+
ctx: SeatLogContext,
|
|
636
|
+
): SeatLogChange<SeatContactEntry> {
|
|
637
|
+
const d = new Draft(entries, subject, ctx);
|
|
638
|
+
markPreferred(d, d.findLive(entryId));
|
|
639
|
+
return d.done();
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
/**
|
|
643
|
+
* Correct an email or phone. Guarded and normalized like an add. Re-typing the
|
|
644
|
+
* same value in another shape is a no-op. Correcting INTO a live value of the
|
|
645
|
+
* same type hands it the preferred mark and archives the wrong one; otherwise
|
|
646
|
+
* the corrected entry is inserted ("Corrects “old”"), takes the mark, and the
|
|
647
|
+
* old one is archived.
|
|
648
|
+
*/
|
|
649
|
+
export function correctSeatContact(
|
|
650
|
+
entries: readonly SeatContactEntry[],
|
|
651
|
+
subject: SeatLogSubject,
|
|
652
|
+
entryId: string,
|
|
653
|
+
next: string,
|
|
654
|
+
ctx: SeatLogContext & { otherSeatEmails?: Iterable<string> },
|
|
655
|
+
): SeatLogChange<SeatContactEntry> {
|
|
656
|
+
const d = new Draft(entries, subject, ctx);
|
|
657
|
+
const target = d.findLive(entryId);
|
|
658
|
+
const type = target.contact_type;
|
|
659
|
+
guardContact(type, String(next ?? "").trim(), ctx.otherSeatEmails);
|
|
660
|
+
const v = canonSeatContactValue(type, next);
|
|
661
|
+
if (!v || v === target.value) return d.done();
|
|
662
|
+
const key = seatContactKey(type, v);
|
|
663
|
+
const dupe = d.live().find((x) =>
|
|
664
|
+
x.contact_type === type &&
|
|
665
|
+
seatContactKey(type, x.value) === key &&
|
|
666
|
+
x.entry_id !== target.entry_id);
|
|
667
|
+
if (dupe) {
|
|
668
|
+
if (target.is_preferred) markPreferred(d, dupe);
|
|
669
|
+
d.archive(target);
|
|
670
|
+
return d.done();
|
|
671
|
+
}
|
|
672
|
+
const added = contactRow(d, {
|
|
673
|
+
contact_type: type, value: v, use: target.use || "", is_preferred: false,
|
|
674
|
+
safety_status: target.safety_status || "", period_start: target.period_start || "",
|
|
675
|
+
period_end: "", notes: correctsNote(target.notes, target.value),
|
|
676
|
+
});
|
|
677
|
+
d.insert(added);
|
|
678
|
+
if (target.is_preferred) markPreferred(d, added);
|
|
679
|
+
d.archive(target);
|
|
680
|
+
return d.done();
|
|
681
|
+
}
|
|
682
|
+
|
|
683
|
+
/** Retire an email or phone (stays in the log, dated). See {@link canRetireSeatContact}. */
|
|
684
|
+
export function retireSeatContact(
|
|
685
|
+
entries: readonly SeatContactEntry[],
|
|
686
|
+
subject: SeatLogSubject,
|
|
687
|
+
entryId: string,
|
|
688
|
+
ctx: SeatLogContext,
|
|
689
|
+
): SeatLogChange<SeatContactEntry> {
|
|
690
|
+
const d = new Draft(entries, subject, ctx);
|
|
691
|
+
const target = d.findLive(entryId);
|
|
692
|
+
if (!canRetireSeatContact(d.rows, target)) {
|
|
693
|
+
throw new SeatLogRefusal(
|
|
694
|
+
"preferred_contact_not_retirable",
|
|
695
|
+
`Prefer another ${target.contact_type} before retiring this one.`,
|
|
696
|
+
);
|
|
697
|
+
}
|
|
698
|
+
d.archive(target);
|
|
699
|
+
return d.done();
|
|
700
|
+
}
|