@htilabs/platform-common-models 0.64.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.
package/README.md CHANGED
@@ -16,6 +16,152 @@ 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
+ ## 0.66.0 — the agency link sheet: every Agency points at its Organization (additive)
20
+
21
+ The data dictionary says every Agency points at an Org (an Agency is an Org's
22
+ participation in an Account). In production 5 of 115 `agencies` rows carry
23
+ `organizationId`, and 53 of the rest hold a VSP answer that belongs on an
24
+ organization they do not have. This release adds the reviewed sheet that
25
+ links them. Nothing in the published package changes except the root exports
26
+ below; the rest is in `scripts/` (runbook:
27
+ `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`, "The agency link sheet").
28
+
29
+ - `mintOrgKey`, `isOrgKey` and `ORG_KEY_PATTERN` are now exported from the
30
+ package root as well as from `/org-directory`, so an app can mint a key
31
+ where it creates an organization without a second import path.
32
+ - `fill-org-registry --propose-agency-orgs` (read-only) writes one CSV line
33
+ per agency with no `organizationId`: plain facts read from the agency row
34
+ (apps, account or not, deployed, off-PAVE, test account, retired, type,
35
+ VSP answer), a proposed organization, and the reason.
36
+ - An organization is proposed on two kinds of evidence only: an
37
+ organization that already names the agency as its own
38
+ (`organizations.agencyId`), or exactly one organization with the same
39
+ name that is not another agency's own and not in another agency's list.
40
+ Never on a loose name match.
41
+ - Nothing is proposed for an agency that holds no account (ruled
42
+ 2026-10-15/17 to become an Org plus a referrals contact, which this tool
43
+ does not do), for a test or internal row, or where the evidence is not
44
+ clear-cut. The reason says which.
45
+ - The reviewer fills `approved` with an organization's database id,
46
+ `create`, or nothing.
47
+ - `--apply-agency-orgs <sheet> [--created-user <users._id>]` prints every
48
+ line with the agency's and the organization's stored names, refuses the
49
+ whole sheet if any line cannot be applied (another database's sheet, a
50
+ changed agency name, an agency that already has an `organizationId`, an
51
+ organization that is missing or another agency's own, two lines for one
52
+ organization), then asks for the database name, saves before-images and
53
+ writes line by line. A link a sign-in completed in between counts as done
54
+ and is not undone; an agency that got a different organization in between
55
+ is skipped and the line says what was taken back; a line the database
56
+ refuses fails alone; every line's result is printed and the command exits
57
+ non-zero if any was not linked. The plan marks a line whose organization's
58
+ type or VSP answer differs from the agency's.
59
+ - Both halves of the link are written: `agencies.organizationId` and
60
+ `organizations.agencyId` (`isAgencyOwnOrganization`).
61
+ - `create` adds the agency's own organization the way the auth service does
62
+ at a first sign-in: a new `_id`, the agency's name, `status` 1, `agencyId` and `agencyScope` the agency, `community` the
63
+ agency's state (else `UNKNOWN`), empty `phones` / `emails`, and
64
+ `createdUser` the operator's platform user. `type` (CVC-48
65
+ `core-referral_entity_category`) is the type the agency row already
66
+ carries, or `unknown`; nothing is worked out. `create` is refused while
67
+ any organization still stores a type number (`migrate:org-type-keys` goes
68
+ first). No VSP answer is written: the fill copies the agency's answer.
69
+ - An organization created by the link sheet deliberately gets **no `key`**
70
+ at creation: a stated exception to "every create stores `key`", because an
71
+ identifier never changes and the identifier sheet must be able to give the
72
+ agency's own organization its curated identifier. Creating an agency's own
73
+ organization where a same-named copy sits in another agency's list
74
+ knowingly leaves two rows until the copy is folded in (a merge: re-point
75
+ references, then delete the copy), which is not built in production yet.
76
+ - The identifier sheet (`--propose-keys`, run after the links) now reads
77
+ `agencies` too: when several rows could take one curated key and exactly
78
+ one is an agency's own organization, it proposes the key for that row and
79
+ marks the others as copies to leave blank. Otherwise the rows stay
80
+ contested. `proposeOrgKeys` takes the agencies as an optional fourth
81
+ argument.
82
+ - Undo is the existing `--rollback`. It removes an `organizationId` this
83
+ tool set (only while it still holds that value) and deletes an
84
+ organization it created only while that row is still exactly as created
85
+ and nothing in this database points at it (an agency, a unit, a personnel
86
+ record, a point of contact, a service listing); otherwise the organization
87
+ stays and the line says why. Linking to a stored organization sets only
88
+ its `agencyId`, so an undo of the fill still recognises the row.
89
+ Before-image files from 0.65.0 still read.
90
+ - Order of a run: type keys, agency link sheet, identifier sheet (proposed
91
+ after the links are applied), fill, report.
92
+
93
+ ## 0.65.0 — the Org's identifier: `key` (additive)
94
+
95
+ An organization now carries its identifier, the one value that names the same
96
+ organization in every database (the UDD Org `id`, a slug such as `the_spring`;
97
+ schema of record hti-features `udd-schemas/org/Org.v1.json`). Until now an
98
+ `organizations` row had only `_id`, which is each database's own, so nothing
99
+ tied a production row to the same organization in the Admin Hub's curated list.
100
+
101
+ - `ORG_RECORD_FIELD_NAMES` gains `key` (first). `addOrgRecordFields` declares
102
+ it (`String`, immutable, slug-shaped) and a partial unique index
103
+ `org_key_unique` (`ORG_KEY_INDEX_NAME`; the definition is exported as
104
+ `ORG_KEY_INDEX_SPEC` / `ORG_KEY_INDEX_OPTIONS`). A row with no key, or a
105
+ null one, is not indexed, so those never collide.
106
+ - What `immutable` does, measured on Mongoose 9.3.1 against MongoDB (the
107
+ tests are in `scripts/fill-org-registry.test.ts`, run in CI): the model
108
+ stores a key **only while it is creating the row**.
109
+ - Stored: `new Model({ key }).save()`, `Model.create({ key })`, and an
110
+ upsert that inserts the row (`$setOnInsert: { key }`, or `$set`, which
111
+ Mongoose moves to `$setOnInsert`).
112
+ - Not stored, and **no error is raised**: on a row that already exists,
113
+ `doc.key = …; doc.save()` and `updateOne` / `findOneAndUpdate` with
114
+ `$set: { key }`, or an upsert that finds the row. This is true whether
115
+ the row already has a key or has none, so a model cannot give an old row
116
+ its first key.
117
+ - Stored as `key`, not `id`: Mongoose gives every document an `id` of its own,
118
+ and the curated store already names it `key`.
119
+ - `isOrgKey`, `ORG_KEY_PATTERN`, `mintOrgKey(_id)` → `org-<_id>` for an
120
+ organization created without one (the curated store's rule: a new key never
121
+ encodes a name). `OrgIdentityWriteSchema` still refuses `key`: it is never
122
+ taken from a request body and never changes.
123
+ - `toDirectoryOrganizationView` returns `key` (null on a row not yet given one).
124
+ - Consumers: a model that mounts `addOrgRecordFields` gains the path and passes
125
+ `organizationSchemaIssues` unchanged. Upgrading alone does not give new
126
+ organizations an identifier: each app has to store one where it creates an
127
+ organization, in one of the forms that work:
128
+
129
+ ```ts
130
+ const _id = new Types.ObjectId();
131
+ await new Organization({ _id, name, key: mintOrgKey(_id) }).save(); // or Organization.create({ … })
132
+
133
+ await Organization.updateOne(
134
+ { _id },
135
+ { $set: { name }, $setOnInsert: { key: mintOrgKey(_id) } },
136
+ { upsert: true },
137
+ );
138
+ ```
139
+
140
+ Do not set `key` on a row that already exists (it is silently dropped, see
141
+ above). Existing rows get theirs only from the registry fill's key sheet,
142
+ which writes with the plain MongoDB driver.
143
+ - `scripts/fill-org-registry.ts`: matches a row to the curated list by `key`
144
+ first; `--propose-keys` / `--apply-keys` give existing rows their identifier
145
+ from a sheet a person reviews (see `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`):
146
+ - The sheet has a `stored_id` column (the slug an old row carries in its
147
+ `id` field). `approved_key` takes a curated key, the line's own
148
+ `stored_id`, or `mint` (`org-<_id>`).
149
+ - Nothing is proposed when the evidence is not clear-cut, and the reason
150
+ says which case it is (two rows for one key, sources that disagree, a
151
+ name or database id that matches two curated organizations, a match by
152
+ short name only, an old slug the curated list does not know).
153
+ - `--apply-keys` prints each organization's stored name beside its key,
154
+ refuses a line whose name is not the stored one, marks an approval that
155
+ differs from the proposal, and builds the `org_key_unique` index first if
156
+ the collection does not have it (it says so before asking to confirm; it
157
+ refuses if an index of that name exists with other options).
158
+ - It plans all or nothing, then writes row by row: a row edited in between,
159
+ or one the database refuses, is reported and the command exits non-zero.
160
+ - Undo (`--rollback`) removes an identifier whenever the row still holds
161
+ the one the script wrote, even after an app has saved the row. Undo the
162
+ most recent apply first (the fill, then the identifiers).
163
+ - Both commands stop if a curated organization has no key, a malformed
164
+ key, a key another curated organization has, or the key `mint`.
19
165
  ## 0.64.0 — gender and disability: the codebook code on every category; the two reporting claims hold our own codes (additive; Crysta 2026-11-10)
20
166
 
21
167
  Crysta confirmed on 2026-11-10 that gender and disability follow the race rule
package/dist/index.cjs CHANGED
@@ -389,6 +389,10 @@ __export(src_exports, {
389
389
  NeedsAssessmentChangeTypeKeys: () => NeedsAssessmentChangeTypeKeys,
390
390
  NeedsResidentialAgainKeys: () => NeedsResidentialAgainKeys,
391
391
  ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: () => ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
392
+ ORG_KEY_INDEX_NAME: () => ORG_KEY_INDEX_NAME,
393
+ ORG_KEY_INDEX_OPTIONS: () => ORG_KEY_INDEX_OPTIONS,
394
+ ORG_KEY_INDEX_SPEC: () => ORG_KEY_INDEX_SPEC,
395
+ ORG_KEY_PATTERN: () => ORG_KEY_PATTERN,
392
396
  ORG_TYPE_FIELD_NAMES: () => ORG_TYPE_FIELD_NAMES,
393
397
  ORG_TYPE_HEADING_KEYS: () => ORG_TYPE_HEADING_KEYS,
394
398
  ORG_TYPE_KEYS: () => ORG_TYPE_KEYS,
@@ -742,6 +746,7 @@ __export(src_exports, {
742
746
  isLgbtqOrientation: () => isLgbtqOrientation,
743
747
  isLiveOrganizationProgram: () => isLiveOrganizationProgram,
744
748
  isNeverPickableServiceMechanism: () => isNeverPickableServiceMechanism,
749
+ isOrgKey: () => isOrgKey,
745
750
  isOrgTypeKey: () => isOrgTypeKey,
746
751
  isPermittedByCeiling: () => isPermittedByCeiling,
747
752
  isProgramReviewStatus: () => isProgramReviewStatus,
@@ -775,6 +780,7 @@ __export(src_exports, {
775
780
  militaryBranchSot: () => militaryBranch_v1_0_0_default,
776
781
  militaryStatusSot: () => militaryStatus_v1_0_0_default,
777
782
  minorAdultStatusSot: () => minorAdultStatus_v1_0_0_default,
783
+ mintOrgKey: () => mintOrgKey,
778
784
  mirrorOrgTypeFields: () => mirrorOrgTypeFields,
779
785
  nameTypeSot: () => nameType_v1_0_0_default,
780
786
  needsAssessmentChangeTypeSot: () => needsAssessmentChangeType_v1_0_0_default,
@@ -18735,6 +18741,7 @@ function isLiveOrganizationProgram(row) {
18735
18741
  // src/orgDirectory/orgRecord.ts
18736
18742
  var ORG_REVIEW_STATUS_VALUES = PROGRAM_REVIEW_STATUS_VALUES;
18737
18743
  var ORG_RECORD_FIELD_NAMES = Object.freeze([
18744
+ "key",
18738
18745
  "legalName",
18739
18746
  "commonName",
18740
18747
  "shortName",
@@ -18784,6 +18791,17 @@ var ORGANIZATION_ENVELOPE_KEYS = Object.freeze([
18784
18791
  "updatedUser",
18785
18792
  "updatedTime"
18786
18793
  ]);
18794
+ var ORG_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,119}$/;
18795
+ function isOrgKey(value) {
18796
+ return typeof value === "string" && ORG_KEY_PATTERN.test(value);
18797
+ }
18798
+ function mintOrgKey(id) {
18799
+ const hex = (typeof id === "string" ? id : id.toHexString()).trim().toLowerCase();
18800
+ if (!/^[0-9a-f]{24}$/.test(hex)) {
18801
+ throw new Error("mintOrgKey: needs the organization's 24-hex _id");
18802
+ }
18803
+ return `org-${hex}`;
18804
+ }
18787
18805
  var line = (max) => import_zod.z.string().trim().min(1).max(max).nullable();
18788
18806
  var ORG_VSP_TWO_STEP_MESSAGE = "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true";
18789
18807
  var OrgIdentityWriteSchema = import_zod.z.object({
@@ -18804,12 +18822,50 @@ var OrgVspWriteSchema = import_zod.z.object({
18804
18822
 
18805
18823
  // src/schemas/organization.ts
18806
18824
  var HEX_24 = /^[0-9a-fA-F]{24}$/;
18825
+ var ORG_KEY_INDEX_NAME = "org_key_unique";
18826
+ var ORG_KEY_INDEX_SPEC = Object.freeze({ key: 1 });
18827
+ var ORG_KEY_INDEX_OPTIONS = Object.freeze({
18828
+ name: ORG_KEY_INDEX_NAME,
18829
+ unique: true,
18830
+ partialFilterExpression: Object.freeze({ key: Object.freeze({ $type: "string" }) })
18831
+ });
18807
18832
  function isStoredDirectoryId(value) {
18808
18833
  if (value == null) return true;
18809
18834
  if (typeof value === "string") return value.trim() !== "";
18810
18835
  return typeof value === "object" && typeof value.toHexString === "function" && HEX_24.test(value.toHexString());
18811
18836
  }
18812
18837
  var orgRecordSchemaDefinition = {
18838
+ /**
18839
+ * The Org's identifier (the UDD `id`): the same value in every database.
18840
+ * Never taken from a request body.
18841
+ *
18842
+ * `immutable` means the model stores a key only while it is creating the
18843
+ * row. Measured on Mongoose 9.3.1 against MongoDB (the fill's test file
18844
+ * holds each line):
18845
+ *
18846
+ * - `new Model({ key }).save()` and `Model.create({ key })` store it.
18847
+ * - An upsert stores it when the upsert inserts the row (`$setOnInsert`, or
18848
+ * `$set`, which Mongoose moves to `$setOnInsert`); on a row that already
18849
+ * exists the upsert leaves `key` as it was.
18850
+ * - On a row that already exists, `doc.key = …; doc.save()` and
18851
+ * `updateOne` / `findOneAndUpdate` with `$set: { key }` do NOT write it,
18852
+ * and do not report an error. That holds whether the row has a key or has
18853
+ * none yet, so a model cannot give an old row its first key either.
18854
+ *
18855
+ * So an app stores `key: mintOrgKey(_id)` where it creates the
18856
+ * organization (`new Model().save()`, `create()`, or `$setOnInsert` on an
18857
+ * upsert). Rows that already exist get theirs from the registry fill's key
18858
+ * sheet, which writes with the plain MongoDB driver.
18859
+ */
18860
+ key: {
18861
+ type: String,
18862
+ trim: true,
18863
+ immutable: true,
18864
+ validate: {
18865
+ validator: (value) => value == null || isOrgKey(value),
18866
+ message: "key must be a lower-case slug (a-z, 0-9, _ and -)"
18867
+ }
18868
+ },
18813
18869
  /** The canonical reporting name (HMIS, funders). Readers fall back to `name`. */
18814
18870
  legalName: { type: String, trim: true },
18815
18871
  /** The name people use, when it differs from `name`. */
@@ -18858,6 +18914,13 @@ var orgAsBuiltSchemaDefinition = {
18858
18914
  };
18859
18915
  function addOrgRecordFields(schema, options = {}) {
18860
18916
  schema.add(orgRecordSchemaDefinition);
18917
+ schema.index(
18918
+ { ...ORG_KEY_INDEX_SPEC },
18919
+ {
18920
+ ...ORG_KEY_INDEX_OPTIONS,
18921
+ partialFilterExpression: { key: { ...ORG_KEY_INDEX_OPTIONS.partialFilterExpression.key } }
18922
+ }
18923
+ );
18861
18924
  for (const key of ORG_AS_BUILT_FIELD_NAMES) {
18862
18925
  if (schema.pathType(key) === "adhocOrUndefined") {
18863
18926
  schema.add({ [key]: orgAsBuiltSchemaDefinition[key] });
@@ -18866,6 +18929,7 @@ function addOrgRecordFields(schema, options = {}) {
18866
18929
  return installVspTwoStepHooks(schema, options);
18867
18930
  }
18868
18931
  var EXPECTED_INSTANCE = {
18932
+ key: "String",
18869
18933
  legalName: "String",
18870
18934
  commonName: "String",
18871
18935
  shortName: "String",
@@ -74768,6 +74832,10 @@ var CVC_197_VALUES = selectableCodes(
74768
74832
  NeedsAssessmentChangeTypeKeys,
74769
74833
  NeedsResidentialAgainKeys,
74770
74834
  ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
74835
+ ORG_KEY_INDEX_NAME,
74836
+ ORG_KEY_INDEX_OPTIONS,
74837
+ ORG_KEY_INDEX_SPEC,
74838
+ ORG_KEY_PATTERN,
74771
74839
  ORG_TYPE_FIELD_NAMES,
74772
74840
  ORG_TYPE_HEADING_KEYS,
74773
74841
  ORG_TYPE_KEYS,
@@ -75121,6 +75189,7 @@ var CVC_197_VALUES = selectableCodes(
75121
75189
  isLgbtqOrientation,
75122
75190
  isLiveOrganizationProgram,
75123
75191
  isNeverPickableServiceMechanism,
75192
+ isOrgKey,
75124
75193
  isOrgTypeKey,
75125
75194
  isPermittedByCeiling,
75126
75195
  isProgramReviewStatus,
@@ -75154,6 +75223,7 @@ var CVC_197_VALUES = selectableCodes(
75154
75223
  militaryBranchSot,
75155
75224
  militaryStatusSot,
75156
75225
  minorAdultStatusSot,
75226
+ mintOrgKey,
75157
75227
  mirrorOrgTypeFields,
75158
75228
  nameTypeSot,
75159
75229
  needsAssessmentChangeTypeSot,