@htilabs/platform-common-models 0.65.0 → 0.66.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.
@@ -0,0 +1,263 @@
1
+ import { z } from 'zod';
2
+ import { b as ProgramReviewStatus } from './vocabulary-Cxhi9EGt.cjs';
3
+
4
+ /**
5
+ * The Org record: the ONE definition of what an `organizations` row holds
6
+ * about an organization, for every app that reads or writes the platform-wide
7
+ * registry (Thread, PAVE, the Platform, auth). Pure: no mongoose, no driver.
8
+ * The Mongoose twin is `schemas/organization.ts` (`addOrgRecordFields`); a
9
+ * package test holds the two key lists equal.
10
+ *
11
+ * ## Canon
12
+ *
13
+ * UDD Org Data Object (Notion `7d71ef14abcd832fa3a6816ebe7a5dd9`, § 1 and § 5;
14
+ * schema of record hti-features `udd-schemas/org/Org.v1.json`): an Org is one
15
+ * real-world organization in the one platform-wide registry. It holds its name
16
+ * (legal and common), its acronym, its required type, its parent when it is a
17
+ * unit of a larger one, the two HMIS victim-service-provider answers, and how
18
+ * it arrived and whether HTI Labs has reviewed it. Crysta, 2026-11-10: "It
19
+ * shouldn't be different in thread vs. pave. And the data objects for Org need
20
+ * to be the same in both apps."
21
+ *
22
+ * ## Stored names
23
+ *
24
+ * The UDD spells these snake_case (`legal_name`, `parent_org_id`, ...). The
25
+ * live platform-db writers use camelCase, so the stored names are the UDD's in
26
+ * camelCase, as for the org-type fields (`schemas/agency.ts`) and the program
27
+ * row (`schemas/organization-program.ts`). Two exceptions. The UDD `acronym` is
28
+ * stored as `shortName`: a top-level `acronym` key marks a pre-pl-958 PAVE row
29
+ * (`organizationRowShape`), and PAVE 2.0 already writes `shortName`. And the
30
+ * UDD `id` (the Org's one identifier, a slug such as `the_spring`) is stored as
31
+ * `key`: Mongoose gives every document an `id` of its own (the `_id` as a
32
+ * string), and the Admin Hub's curated store already names it `key`.
33
+ *
34
+ * ## What is NOT here
35
+ *
36
+ * - `name` and `type`: every writer already stores them. `type` is mid-move
37
+ * from the IC-58 number to the CVC-48 key and each app validates the
38
+ * transition form itself until the migration has run.
39
+ * - The row's tenancy and plumbing (`agencyScope`, `agencyId`, `community`,
40
+ * `canonicalKey`, `status`, `programs`, contact fields): unchanged by this
41
+ * module. {@link ORGANIZATION_ROW_KEYS} lists them so a model can be checked
42
+ * against the whole row.
43
+ */
44
+
45
+ /**
46
+ * Review lifecycle of an organization added from inside an app. The same three
47
+ * words, and the same lifecycle, as a program named inside an app (UDD Org
48
+ * § 5 "how it arrived"; census item 2: "the same lifecycle a program named
49
+ * inside an app has"). Absent on a steward row: nothing to review.
50
+ */
51
+ declare const ORG_REVIEW_STATUS: {
52
+ readonly PENDING: "pending";
53
+ readonly CONFIRMED: "confirmed";
54
+ readonly REJECTED: "rejected";
55
+ };
56
+ declare const ORG_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
57
+ type OrgReviewStatus = ProgramReviewStatus;
58
+ /**
59
+ * `organizations.status`: 1 active, 2 inactive (soft-deleted; never removed).
60
+ * The codes auth, Thread and PAVE already store.
61
+ */
62
+ declare const ORGANIZATION_STATUS: {
63
+ readonly ACTIVE: 1;
64
+ readonly INACTIVE: 2;
65
+ };
66
+ type OrganizationStatus = (typeof ORGANIZATION_STATUS)[keyof typeof ORGANIZATION_STATUS];
67
+ /**
68
+ * Whether an organization may be OFFERED in a picker: active (an absent
69
+ * `status` reads active, as legacy rows carry none) and not declined by HTI
70
+ * Labs. A pending organization IS offered: an organization added inside an app
71
+ * is available everywhere from the moment it is added (UDD Org § 2 scenario 1).
72
+ * A stored reference to an organization that is no longer offered still
73
+ * resolves by id.
74
+ */
75
+ declare function isListedOrganization(row: {
76
+ status?: number | null | undefined;
77
+ reviewStatus?: string | null | undefined;
78
+ }): boolean;
79
+ /**
80
+ * The Org definition's fields beyond `name` and `type`, in the Mongoose
81
+ * fragment's declaration order (`orgRecordSchemaDefinition`).
82
+ */
83
+ declare const ORG_RECORD_FIELD_NAMES: readonly ["key", "legalName", "commonName", "shortName", "website", "parentOrgId", "vsp", "vspPrivateNonprofit", "reviewStatus", "addedInApp", "addedBy"];
84
+ type OrgRecordFieldName = (typeof ORG_RECORD_FIELD_NAMES)[number];
85
+ /**
86
+ * Stored on the row today and NOT part of the Org definition (UDD Org § 5,
87
+ * "As built today, and not part of this definition"; Org.v1's runtime-overlay
88
+ * five: `isCustom`, `added_in_session`, `added_by_user_id`, `type_override`,
89
+ * `division`). PAVE 2.0 writes them; every model declares
90
+ * them so no app silently drops another app's value. `typeKey` is the CVC-48
91
+ * key PAVE writes beside a numeric `type` and retires with the type migration.
92
+ */
93
+ declare const ORG_AS_BUILT_FIELD_NAMES: readonly ["requiresROI", "isCustom", "addedByUserId", "addedInSession", "division", "typeOverride", "typeKey"];
94
+ type OrgAsBuiltFieldName = (typeof ORG_AS_BUILT_FIELD_NAMES)[number];
95
+ /** The row's keys every writer already stored before this module. */
96
+ declare const ORGANIZATION_BASE_ROW_KEYS: readonly ["name", "type", "phones", "emails", "address", "notes", "status", "agencyScope", "agencyId", "community", "canonicalKey", "isAnonymous", "programs"];
97
+ /**
98
+ * Every top-level key of a shared-shape `organizations` row, the record
99
+ * envelope aside. A model that declares exactly these is the same data object
100
+ * as every other app's (`organizationSchemaIssues`, `schemas/organization.ts`).
101
+ */
102
+ declare const ORGANIZATION_ROW_KEYS: readonly ["name", "type", "phones", "emails", "address", "notes", "status", "agencyScope", "agencyId", "community", "canonicalKey", "isAnonymous", "programs", "key", "legalName", "commonName", "shortName", "website", "parentOrgId", "vsp", "vspPrivateNonprofit", "reviewStatus", "addedInApp", "addedBy", "requiresROI", "isCustom", "addedByUserId", "addedInSession", "division", "typeOverride", "typeKey"];
103
+ type OrganizationRowKey = (typeof ORGANIZATION_ROW_KEYS)[number];
104
+ /** The record envelope each app's base document adds; never Org facts. */
105
+ declare const ORGANIZATION_ENVELOPE_KEYS: readonly ["_id", "__v", "_schemaVersion", "createdUser", "createdTime", "updatedUser", "updatedTime"];
106
+ /**
107
+ * The Org's identifier (UDD Org `id`; stored as `key`): the one value that
108
+ * names the same organization in every database, where `_id` is each
109
+ * database's own. A lower-case slug: `the_spring`, `ascension_stjohn`,
110
+ * `org-custom-8daxtira`, `org-6a1f5dadd0c33a5a149f3413`.
111
+ *
112
+ * Rules (the curated store's, Kickoff 13 item 3): unique; never changes once
113
+ * set; never taken from a request body (`OrgIdentityWriteSchema` is strict and
114
+ * does not name it); a new organization's key never encodes its name
115
+ * ({@link mintOrgKey}). A row written before 0.65.0 has none until the
116
+ * registry fill stamps one from a reviewed sheet.
117
+ */
118
+ declare const ORG_KEY_PATTERN: RegExp;
119
+ /** Whether a value is a well-formed Org identifier. */
120
+ declare function isOrgKey(value: unknown): value is string;
121
+ /**
122
+ * The identifier for an organization created without one (added inside an
123
+ * app, or by a steward typing a new organization): `org-<its _id>`. It encodes
124
+ * no name, so a later rename never makes it wrong.
125
+ */
126
+ declare function mintOrgKey(id: string | {
127
+ toHexString(): string;
128
+ }): string;
129
+ /** The two-step message; the same sentence the Mongoose mount throws. */
130
+ declare const ORG_VSP_TWO_STEP_MESSAGE = "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true";
131
+ /**
132
+ * The identity half of the record, as a request body may carry it. Every key
133
+ * is optional (a PATCH names only what it changes); `null` clears a field.
134
+ * Strict: an unknown key is refused, so a snake_case spelling never passes as
135
+ * a silent no-op.
136
+ */
137
+ declare const OrgIdentityWriteSchema: z.ZodObject<{
138
+ legalName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
139
+ commonName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
140
+ shortName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
141
+ website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
142
+ parentOrgId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
143
+ }, "strict", z.ZodTypeAny, {
144
+ website?: string | null | undefined;
145
+ legalName?: string | null | undefined;
146
+ commonName?: string | null | undefined;
147
+ shortName?: string | null | undefined;
148
+ parentOrgId?: string | null | undefined;
149
+ }, {
150
+ website?: string | null | undefined;
151
+ legalName?: string | null | undefined;
152
+ commonName?: string | null | undefined;
153
+ shortName?: string | null | undefined;
154
+ parentOrgId?: string | null | undefined;
155
+ }>;
156
+ type OrgIdentityWrite = z.infer<typeof OrgIdentityWriteSchema>;
157
+ /**
158
+ * The two HMIS victim-service-provider answers. Tri-state: `null` is "not yet
159
+ * captured", never a coerced false. Step 2 may be answered only with step 1
160
+ * `true` in the same body (an update cannot see the stored row), and a body
161
+ * that sets step 1 to `false` or `null` clears step 2 with it. Only HTI Labs
162
+ * sets them (UDD Org rulings 2026-10-08 and 2026-10-09); the route decides who
163
+ * that is.
164
+ */
165
+ declare const OrgVspWriteSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
166
+ vsp: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
167
+ vspPrivateNonprofit: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
168
+ }, "strict", z.ZodTypeAny, {
169
+ vspPrivateNonprofit?: boolean | null | undefined;
170
+ vsp?: boolean | null | undefined;
171
+ }, {
172
+ vspPrivateNonprofit?: boolean | null | undefined;
173
+ vsp?: boolean | null | undefined;
174
+ }>, {
175
+ vspPrivateNonprofit?: boolean | null | undefined;
176
+ vsp?: boolean | null | undefined;
177
+ }, {
178
+ vspPrivateNonprofit?: boolean | null | undefined;
179
+ vsp?: boolean | null | undefined;
180
+ }>, {
181
+ vspPrivateNonprofit?: boolean | null | undefined;
182
+ vsp?: boolean | null | undefined;
183
+ }, {
184
+ vspPrivateNonprofit?: boolean | null | undefined;
185
+ vsp?: boolean | null | undefined;
186
+ }>;
187
+ type OrgVspWrite = z.infer<typeof OrgVspWriteSchema>;
188
+ /**
189
+ * How an organization arrived. Never taken from a request body: the server
190
+ * stamps it from the authenticated caller ({@link orgArrivalStamp}).
191
+ *
192
+ * The same three facts, under the same names, as a Program, a Service Listing
193
+ * and a Point of contact carry (`added_by` · `added_in_app` · `review_status`;
194
+ * UDD ratification request R17, "how an organization arrived"). The older
195
+ * runtime-overlay names on the row (`addedByUserId`, `isCustom`) are as-built
196
+ * extras; `addedInSession` is carried as on the program row.
197
+ */
198
+ interface OrgArrival {
199
+ reviewStatus: OrgReviewStatus;
200
+ /** The app the organization was added in: `thread`, `pave`, `leads`, `platform`. */
201
+ addedInApp: string;
202
+ /** The adding user's platform `users._id`, as a string. */
203
+ addedBy: string;
204
+ /** The session it was added in, when there was one. */
205
+ addedInSession?: string;
206
+ }
207
+ /**
208
+ * The arrival stamp for an organization a user adds from inside an app: it is
209
+ * on the list at once and waits for HTI Labs' review (UDD Org § 2 scenario 5;
210
+ * census item 2). A steward's own add carries no stamp.
211
+ */
212
+ declare function orgArrivalStamp(input: {
213
+ app: string;
214
+ userId: string;
215
+ sessionId?: string | null | undefined;
216
+ }): OrgArrival;
217
+ interface OrgNames {
218
+ name?: string | null | undefined;
219
+ commonName?: string | null | undefined;
220
+ legalName?: string | null | undefined;
221
+ shortName?: string | null | undefined;
222
+ }
223
+ /**
224
+ * The name to use when a sentence or a label names an organization: its common
225
+ * name when it has one, else its name. Canon: the prototype's contact-history
226
+ * register and referral wording (`org.common_name || org.name`).
227
+ */
228
+ declare function orgCommonName(org: OrgNames | null | undefined): string;
229
+ /**
230
+ * The name a report to a funder or HMIS uses: the legal name when captured,
231
+ * else the name (Org.v1 `legal_name`: "consumers fall back to name when blank").
232
+ */
233
+ declare function orgLegalName(org: OrgNames | null | undefined): string;
234
+ /** Whether a row's name is nothing but its short name ("ASJS" named "ASJS"). */
235
+ declare function isShortNameOnly(org: OrgNames | null | undefined): boolean;
236
+ /**
237
+ * How a unit of a larger organization reads: its own name, and "<parent> unit"
238
+ * beneath it when the unit has no name beyond its short name (Crysta
239
+ * 2026-09-03, "No names yet — show the parent"). A row with a real name keeps
240
+ * it. Canon: the prototype's one resolver, `orgDisplayParts`.
241
+ */
242
+ declare function orgDisplayParts(org: OrgNames | null | undefined, parent: OrgNames | null | undefined): {
243
+ name: string;
244
+ sub: string;
245
+ };
246
+ /** {@link orgDisplayParts} on one line: "ASJS · Ascension St. John Medical Center unit". */
247
+ declare function orgDisplayName(org: OrgNames | null | undefined, parent?: OrgNames | null | undefined): string;
248
+ /**
249
+ * Why `parentOrgId` may not be set to this value, or null when it may. One
250
+ * level only (the picker folds units under their organization): an
251
+ * organization is never its own parent, a parent is not itself a unit, and an
252
+ * organization that has units cannot become one.
253
+ */
254
+ declare function orgParentIssue(input: {
255
+ orgId: string | null | undefined;
256
+ parentOrgId: string | null | undefined;
257
+ /** The proposed parent's own `parentOrgId`, when the parent row was read. */
258
+ parentsParentOrgId?: string | null | undefined;
259
+ /** Whether any organization already names `orgId` as its parent. */
260
+ hasUnits?: boolean | undefined;
261
+ }): "self" | "parent_is_unit" | "org_has_units" | null;
262
+
263
+ export { orgDisplayParts as A, orgLegalName as B, orgParentIssue as C, ORG_KEY_PATTERN as O, type OrgReviewStatus as a, ORGANIZATION_BASE_ROW_KEYS as b, ORGANIZATION_ENVELOPE_KEYS as c, ORGANIZATION_ROW_KEYS as d, ORGANIZATION_STATUS as e, ORG_AS_BUILT_FIELD_NAMES as f, ORG_RECORD_FIELD_NAMES as g, ORG_REVIEW_STATUS as h, isOrgKey as i, ORG_REVIEW_STATUS_VALUES as j, ORG_VSP_TWO_STEP_MESSAGE as k, type OrgArrival as l, mintOrgKey as m, type OrgAsBuiltFieldName as n, type OrgIdentityWrite as o, OrgIdentityWriteSchema as p, type OrgRecordFieldName as q, type OrgVspWrite as r, OrgVspWriteSchema as s, type OrganizationRowKey as t, type OrganizationStatus as u, isListedOrganization as v, isShortNameOnly as w, orgArrivalStamp as x, orgCommonName as y, orgDisplayName as z };
@@ -0,0 +1,263 @@
1
+ import { z } from 'zod';
2
+ import { b as ProgramReviewStatus } from './vocabulary-Cxhi9EGt.js';
3
+
4
+ /**
5
+ * The Org record: the ONE definition of what an `organizations` row holds
6
+ * about an organization, for every app that reads or writes the platform-wide
7
+ * registry (Thread, PAVE, the Platform, auth). Pure: no mongoose, no driver.
8
+ * The Mongoose twin is `schemas/organization.ts` (`addOrgRecordFields`); a
9
+ * package test holds the two key lists equal.
10
+ *
11
+ * ## Canon
12
+ *
13
+ * UDD Org Data Object (Notion `7d71ef14abcd832fa3a6816ebe7a5dd9`, § 1 and § 5;
14
+ * schema of record hti-features `udd-schemas/org/Org.v1.json`): an Org is one
15
+ * real-world organization in the one platform-wide registry. It holds its name
16
+ * (legal and common), its acronym, its required type, its parent when it is a
17
+ * unit of a larger one, the two HMIS victim-service-provider answers, and how
18
+ * it arrived and whether HTI Labs has reviewed it. Crysta, 2026-11-10: "It
19
+ * shouldn't be different in thread vs. pave. And the data objects for Org need
20
+ * to be the same in both apps."
21
+ *
22
+ * ## Stored names
23
+ *
24
+ * The UDD spells these snake_case (`legal_name`, `parent_org_id`, ...). The
25
+ * live platform-db writers use camelCase, so the stored names are the UDD's in
26
+ * camelCase, as for the org-type fields (`schemas/agency.ts`) and the program
27
+ * row (`schemas/organization-program.ts`). Two exceptions. The UDD `acronym` is
28
+ * stored as `shortName`: a top-level `acronym` key marks a pre-pl-958 PAVE row
29
+ * (`organizationRowShape`), and PAVE 2.0 already writes `shortName`. And the
30
+ * UDD `id` (the Org's one identifier, a slug such as `the_spring`) is stored as
31
+ * `key`: Mongoose gives every document an `id` of its own (the `_id` as a
32
+ * string), and the Admin Hub's curated store already names it `key`.
33
+ *
34
+ * ## What is NOT here
35
+ *
36
+ * - `name` and `type`: every writer already stores them. `type` is mid-move
37
+ * from the IC-58 number to the CVC-48 key and each app validates the
38
+ * transition form itself until the migration has run.
39
+ * - The row's tenancy and plumbing (`agencyScope`, `agencyId`, `community`,
40
+ * `canonicalKey`, `status`, `programs`, contact fields): unchanged by this
41
+ * module. {@link ORGANIZATION_ROW_KEYS} lists them so a model can be checked
42
+ * against the whole row.
43
+ */
44
+
45
+ /**
46
+ * Review lifecycle of an organization added from inside an app. The same three
47
+ * words, and the same lifecycle, as a program named inside an app (UDD Org
48
+ * § 5 "how it arrived"; census item 2: "the same lifecycle a program named
49
+ * inside an app has"). Absent on a steward row: nothing to review.
50
+ */
51
+ declare const ORG_REVIEW_STATUS: {
52
+ readonly PENDING: "pending";
53
+ readonly CONFIRMED: "confirmed";
54
+ readonly REJECTED: "rejected";
55
+ };
56
+ declare const ORG_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
57
+ type OrgReviewStatus = ProgramReviewStatus;
58
+ /**
59
+ * `organizations.status`: 1 active, 2 inactive (soft-deleted; never removed).
60
+ * The codes auth, Thread and PAVE already store.
61
+ */
62
+ declare const ORGANIZATION_STATUS: {
63
+ readonly ACTIVE: 1;
64
+ readonly INACTIVE: 2;
65
+ };
66
+ type OrganizationStatus = (typeof ORGANIZATION_STATUS)[keyof typeof ORGANIZATION_STATUS];
67
+ /**
68
+ * Whether an organization may be OFFERED in a picker: active (an absent
69
+ * `status` reads active, as legacy rows carry none) and not declined by HTI
70
+ * Labs. A pending organization IS offered: an organization added inside an app
71
+ * is available everywhere from the moment it is added (UDD Org § 2 scenario 1).
72
+ * A stored reference to an organization that is no longer offered still
73
+ * resolves by id.
74
+ */
75
+ declare function isListedOrganization(row: {
76
+ status?: number | null | undefined;
77
+ reviewStatus?: string | null | undefined;
78
+ }): boolean;
79
+ /**
80
+ * The Org definition's fields beyond `name` and `type`, in the Mongoose
81
+ * fragment's declaration order (`orgRecordSchemaDefinition`).
82
+ */
83
+ declare const ORG_RECORD_FIELD_NAMES: readonly ["key", "legalName", "commonName", "shortName", "website", "parentOrgId", "vsp", "vspPrivateNonprofit", "reviewStatus", "addedInApp", "addedBy"];
84
+ type OrgRecordFieldName = (typeof ORG_RECORD_FIELD_NAMES)[number];
85
+ /**
86
+ * Stored on the row today and NOT part of the Org definition (UDD Org § 5,
87
+ * "As built today, and not part of this definition"; Org.v1's runtime-overlay
88
+ * five: `isCustom`, `added_in_session`, `added_by_user_id`, `type_override`,
89
+ * `division`). PAVE 2.0 writes them; every model declares
90
+ * them so no app silently drops another app's value. `typeKey` is the CVC-48
91
+ * key PAVE writes beside a numeric `type` and retires with the type migration.
92
+ */
93
+ declare const ORG_AS_BUILT_FIELD_NAMES: readonly ["requiresROI", "isCustom", "addedByUserId", "addedInSession", "division", "typeOverride", "typeKey"];
94
+ type OrgAsBuiltFieldName = (typeof ORG_AS_BUILT_FIELD_NAMES)[number];
95
+ /** The row's keys every writer already stored before this module. */
96
+ declare const ORGANIZATION_BASE_ROW_KEYS: readonly ["name", "type", "phones", "emails", "address", "notes", "status", "agencyScope", "agencyId", "community", "canonicalKey", "isAnonymous", "programs"];
97
+ /**
98
+ * Every top-level key of a shared-shape `organizations` row, the record
99
+ * envelope aside. A model that declares exactly these is the same data object
100
+ * as every other app's (`organizationSchemaIssues`, `schemas/organization.ts`).
101
+ */
102
+ declare const ORGANIZATION_ROW_KEYS: readonly ["name", "type", "phones", "emails", "address", "notes", "status", "agencyScope", "agencyId", "community", "canonicalKey", "isAnonymous", "programs", "key", "legalName", "commonName", "shortName", "website", "parentOrgId", "vsp", "vspPrivateNonprofit", "reviewStatus", "addedInApp", "addedBy", "requiresROI", "isCustom", "addedByUserId", "addedInSession", "division", "typeOverride", "typeKey"];
103
+ type OrganizationRowKey = (typeof ORGANIZATION_ROW_KEYS)[number];
104
+ /** The record envelope each app's base document adds; never Org facts. */
105
+ declare const ORGANIZATION_ENVELOPE_KEYS: readonly ["_id", "__v", "_schemaVersion", "createdUser", "createdTime", "updatedUser", "updatedTime"];
106
+ /**
107
+ * The Org's identifier (UDD Org `id`; stored as `key`): the one value that
108
+ * names the same organization in every database, where `_id` is each
109
+ * database's own. A lower-case slug: `the_spring`, `ascension_stjohn`,
110
+ * `org-custom-8daxtira`, `org-6a1f5dadd0c33a5a149f3413`.
111
+ *
112
+ * Rules (the curated store's, Kickoff 13 item 3): unique; never changes once
113
+ * set; never taken from a request body (`OrgIdentityWriteSchema` is strict and
114
+ * does not name it); a new organization's key never encodes its name
115
+ * ({@link mintOrgKey}). A row written before 0.65.0 has none until the
116
+ * registry fill stamps one from a reviewed sheet.
117
+ */
118
+ declare const ORG_KEY_PATTERN: RegExp;
119
+ /** Whether a value is a well-formed Org identifier. */
120
+ declare function isOrgKey(value: unknown): value is string;
121
+ /**
122
+ * The identifier for an organization created without one (added inside an
123
+ * app, or by a steward typing a new organization): `org-<its _id>`. It encodes
124
+ * no name, so a later rename never makes it wrong.
125
+ */
126
+ declare function mintOrgKey(id: string | {
127
+ toHexString(): string;
128
+ }): string;
129
+ /** The two-step message; the same sentence the Mongoose mount throws. */
130
+ declare const ORG_VSP_TWO_STEP_MESSAGE = "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true";
131
+ /**
132
+ * The identity half of the record, as a request body may carry it. Every key
133
+ * is optional (a PATCH names only what it changes); `null` clears a field.
134
+ * Strict: an unknown key is refused, so a snake_case spelling never passes as
135
+ * a silent no-op.
136
+ */
137
+ declare const OrgIdentityWriteSchema: z.ZodObject<{
138
+ legalName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
139
+ commonName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
140
+ shortName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
141
+ website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
142
+ parentOrgId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
143
+ }, "strict", z.ZodTypeAny, {
144
+ website?: string | null | undefined;
145
+ legalName?: string | null | undefined;
146
+ commonName?: string | null | undefined;
147
+ shortName?: string | null | undefined;
148
+ parentOrgId?: string | null | undefined;
149
+ }, {
150
+ website?: string | null | undefined;
151
+ legalName?: string | null | undefined;
152
+ commonName?: string | null | undefined;
153
+ shortName?: string | null | undefined;
154
+ parentOrgId?: string | null | undefined;
155
+ }>;
156
+ type OrgIdentityWrite = z.infer<typeof OrgIdentityWriteSchema>;
157
+ /**
158
+ * The two HMIS victim-service-provider answers. Tri-state: `null` is "not yet
159
+ * captured", never a coerced false. Step 2 may be answered only with step 1
160
+ * `true` in the same body (an update cannot see the stored row), and a body
161
+ * that sets step 1 to `false` or `null` clears step 2 with it. Only HTI Labs
162
+ * sets them (UDD Org rulings 2026-10-08 and 2026-10-09); the route decides who
163
+ * that is.
164
+ */
165
+ declare const OrgVspWriteSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
166
+ vsp: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
167
+ vspPrivateNonprofit: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
168
+ }, "strict", z.ZodTypeAny, {
169
+ vspPrivateNonprofit?: boolean | null | undefined;
170
+ vsp?: boolean | null | undefined;
171
+ }, {
172
+ vspPrivateNonprofit?: boolean | null | undefined;
173
+ vsp?: boolean | null | undefined;
174
+ }>, {
175
+ vspPrivateNonprofit?: boolean | null | undefined;
176
+ vsp?: boolean | null | undefined;
177
+ }, {
178
+ vspPrivateNonprofit?: boolean | null | undefined;
179
+ vsp?: boolean | null | undefined;
180
+ }>, {
181
+ vspPrivateNonprofit?: boolean | null | undefined;
182
+ vsp?: boolean | null | undefined;
183
+ }, {
184
+ vspPrivateNonprofit?: boolean | null | undefined;
185
+ vsp?: boolean | null | undefined;
186
+ }>;
187
+ type OrgVspWrite = z.infer<typeof OrgVspWriteSchema>;
188
+ /**
189
+ * How an organization arrived. Never taken from a request body: the server
190
+ * stamps it from the authenticated caller ({@link orgArrivalStamp}).
191
+ *
192
+ * The same three facts, under the same names, as a Program, a Service Listing
193
+ * and a Point of contact carry (`added_by` · `added_in_app` · `review_status`;
194
+ * UDD ratification request R17, "how an organization arrived"). The older
195
+ * runtime-overlay names on the row (`addedByUserId`, `isCustom`) are as-built
196
+ * extras; `addedInSession` is carried as on the program row.
197
+ */
198
+ interface OrgArrival {
199
+ reviewStatus: OrgReviewStatus;
200
+ /** The app the organization was added in: `thread`, `pave`, `leads`, `platform`. */
201
+ addedInApp: string;
202
+ /** The adding user's platform `users._id`, as a string. */
203
+ addedBy: string;
204
+ /** The session it was added in, when there was one. */
205
+ addedInSession?: string;
206
+ }
207
+ /**
208
+ * The arrival stamp for an organization a user adds from inside an app: it is
209
+ * on the list at once and waits for HTI Labs' review (UDD Org § 2 scenario 5;
210
+ * census item 2). A steward's own add carries no stamp.
211
+ */
212
+ declare function orgArrivalStamp(input: {
213
+ app: string;
214
+ userId: string;
215
+ sessionId?: string | null | undefined;
216
+ }): OrgArrival;
217
+ interface OrgNames {
218
+ name?: string | null | undefined;
219
+ commonName?: string | null | undefined;
220
+ legalName?: string | null | undefined;
221
+ shortName?: string | null | undefined;
222
+ }
223
+ /**
224
+ * The name to use when a sentence or a label names an organization: its common
225
+ * name when it has one, else its name. Canon: the prototype's contact-history
226
+ * register and referral wording (`org.common_name || org.name`).
227
+ */
228
+ declare function orgCommonName(org: OrgNames | null | undefined): string;
229
+ /**
230
+ * The name a report to a funder or HMIS uses: the legal name when captured,
231
+ * else the name (Org.v1 `legal_name`: "consumers fall back to name when blank").
232
+ */
233
+ declare function orgLegalName(org: OrgNames | null | undefined): string;
234
+ /** Whether a row's name is nothing but its short name ("ASJS" named "ASJS"). */
235
+ declare function isShortNameOnly(org: OrgNames | null | undefined): boolean;
236
+ /**
237
+ * How a unit of a larger organization reads: its own name, and "<parent> unit"
238
+ * beneath it when the unit has no name beyond its short name (Crysta
239
+ * 2026-09-03, "No names yet — show the parent"). A row with a real name keeps
240
+ * it. Canon: the prototype's one resolver, `orgDisplayParts`.
241
+ */
242
+ declare function orgDisplayParts(org: OrgNames | null | undefined, parent: OrgNames | null | undefined): {
243
+ name: string;
244
+ sub: string;
245
+ };
246
+ /** {@link orgDisplayParts} on one line: "ASJS · Ascension St. John Medical Center unit". */
247
+ declare function orgDisplayName(org: OrgNames | null | undefined, parent?: OrgNames | null | undefined): string;
248
+ /**
249
+ * Why `parentOrgId` may not be set to this value, or null when it may. One
250
+ * level only (the picker folds units under their organization): an
251
+ * organization is never its own parent, a parent is not itself a unit, and an
252
+ * organization that has units cannot become one.
253
+ */
254
+ declare function orgParentIssue(input: {
255
+ orgId: string | null | undefined;
256
+ parentOrgId: string | null | undefined;
257
+ /** The proposed parent's own `parentOrgId`, when the parent row was read. */
258
+ parentsParentOrgId?: string | null | undefined;
259
+ /** Whether any organization already names `orgId` as its parent. */
260
+ hasUnits?: boolean | undefined;
261
+ }): "self" | "parent_is_unit" | "org_has_units" | null;
262
+
263
+ export { orgDisplayParts as A, orgLegalName as B, orgParentIssue as C, ORG_KEY_PATTERN as O, type OrgReviewStatus as a, ORGANIZATION_BASE_ROW_KEYS as b, ORGANIZATION_ENVELOPE_KEYS as c, ORGANIZATION_ROW_KEYS as d, ORGANIZATION_STATUS as e, ORG_AS_BUILT_FIELD_NAMES as f, ORG_RECORD_FIELD_NAMES as g, ORG_REVIEW_STATUS as h, isOrgKey as i, ORG_REVIEW_STATUS_VALUES as j, ORG_VSP_TWO_STEP_MESSAGE as k, type OrgArrival as l, mintOrgKey as m, type OrgAsBuiltFieldName as n, type OrgIdentityWrite as o, OrgIdentityWriteSchema as p, type OrgRecordFieldName as q, type OrgVspWrite as r, OrgVspWriteSchema as s, type OrganizationRowKey as t, type OrganizationStatus as u, isListedOrganization as v, isShortNameOnly as w, orgArrivalStamp as x, orgCommonName as y, orgDisplayName as z };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.65.0",
3
+ "version": "0.66.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The Org's identifier helpers are reachable from the package root as well as
3
+ * from `/org-directory` (0.66.0): an app mints a key where it creates an
4
+ * organization, next to the model it already imports from the root.
5
+ */
6
+ import { describe, expect, it } from "vitest";
7
+
8
+ import * as root from "../index.js";
9
+ import * as orgDirectory from "../orgDirectory/index.js";
10
+
11
+ describe("the Org identifier helpers on the package root", () => {
12
+ it("are the same objects the /org-directory subpath exports", () => {
13
+ expect(root.mintOrgKey).toBe(orgDirectory.mintOrgKey);
14
+ expect(root.isOrgKey).toBe(orgDirectory.isOrgKey);
15
+ expect(root.ORG_KEY_PATTERN).toBe(orgDirectory.ORG_KEY_PATTERN);
16
+ });
17
+
18
+ it("work from the root", () => {
19
+ const key: string = root.mintOrgKey("6A1F5DADD0C33A5A149F3413");
20
+ expect(key).toBe("org-6a1f5dadd0c33a5a149f3413");
21
+ expect(root.isOrgKey(key)).toBe(true);
22
+ expect(root.ORG_KEY_PATTERN.test("The Spring")).toBe(false);
23
+ });
24
+ });
package/src/index.ts CHANGED
@@ -117,6 +117,13 @@ export type {
117
117
  SetOrgTypeInput,
118
118
  } from "./validation/agency.js";
119
119
 
120
+ // ─── The Org's identifier ───────────────────────────────────────────────────
121
+ // An app stores `key: mintOrgKey(_id)` in the same place it creates an
122
+ // organization, which is where it already imports its model from this root.
123
+ // The rest of the org directory stays on the `/org-directory` subpath, which
124
+ // exports these three as well.
125
+ export { ORG_KEY_PATTERN, isOrgKey, mintOrgKey } from "./orgDirectory/orgRecord.js";
126
+
120
127
  // ─── CVC factory model named aliases ────────────────────────────────────────
121
128
  // Per co-am3.7 bead: surface the model factories under explicit
122
129
  // `compileCvcRegistryModel` / `compileCvcEntryModel` names. The underlying