@htilabs/platform-common-models 0.21.0 → 0.22.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/dist/cvcs/index.cjs +449 -50
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +491 -55
- package/dist/cvcs/index.d.ts +491 -55
- package/dist/cvcs/index.js +449 -50
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs +36 -1
- package/dist/enums/index.cjs.map +1 -1
- package/dist/enums/index.d.cts +37 -2
- package/dist/enums/index.d.ts +37 -2
- package/dist/enums/index.js +36 -1
- package/dist/enums/index.js.map +1 -1
- package/dist/index.cjs +589 -51
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +580 -51
- package/dist/index.js.map +1 -1
- package/dist/schemas/index.cjs +104 -0
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +240 -1
- package/dist/schemas/index.d.ts +240 -1
- package/dist/schemas/index.js +95 -0
- package/dist/schemas/index.js.map +1 -1
- package/package.json +1 -1
- package/src/__sot__/README.md +1 -0
- package/src/__sot__/coreFunctionFields.ts +121 -0
- package/src/__sot__/coreFunctions.pin.json +1546 -0
- package/src/__sot__/coreFunctions.published.json +233 -0
- package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
- package/src/__tests__/core-functions-canon.test.ts +308 -24
- package/src/__tests__/cvc-sot-snapshot.test.ts +7 -4
- package/src/__tests__/cvc-status-parser.test.ts +1 -1
- package/src/__tests__/cvc-structural.test.ts +1 -1
- package/src/__tests__/organization-program.test.ts +254 -0
- package/src/cvcs/{coreFunctions.v1.1.0.json → coreFunctions.v1.2.0.json} +446 -47
- package/src/cvcs/index.ts +1 -1
- package/src/generated/cvc-enums.ts +37 -2
- package/src/schemas/index.ts +18 -0
- package/src/schemas/organization-program.ts +297 -0
package/dist/schemas/index.d.cts
CHANGED
|
@@ -420,4 +420,243 @@ declare function addTeamDirectoryFields<S extends Schema>(schema: S): S;
|
|
|
420
420
|
*/
|
|
421
421
|
type TeamDirectoryFields = Partial<InferRawDocType<typeof teamDirectorySchemaDefinition>>;
|
|
422
422
|
|
|
423
|
-
|
|
423
|
+
/**
|
|
424
|
+
* @htilabs/platform-common-models — Organization program rows (`organizations.programs[]`)
|
|
425
|
+
*
|
|
426
|
+
* The ONE definition of the embedded program sub-document on the platform-db
|
|
427
|
+
* `organizations` collection, which both apps read and PAVE 2.0 writes.
|
|
428
|
+
*
|
|
429
|
+
* ## This is a FRAGMENT, not an Organization model
|
|
430
|
+
*
|
|
431
|
+
* No canonical Organization schema exists in this package (same posture as
|
|
432
|
+
* `schemas/team.ts` and `schemas/agency.ts`). `organizations` is written by
|
|
433
|
+
* PAVE 2.0 (`packages/db/src/models/organization.ts`) and read by Thread
|
|
434
|
+
* (`packages/db/src/models/platform/Organization.ts`, `select: false` on
|
|
435
|
+
* `programs`, read with `+programs`). Until this module, each app carried its
|
|
436
|
+
* own copy of the sub-schema — identical by hand. This module declares the
|
|
437
|
+
* program row ONCE; each consumer mounts it with
|
|
438
|
+
* {@link addOrganizationProgramsField} or builds the sub-schema with
|
|
439
|
+
* {@link buildOrganizationProgramSchema}.
|
|
440
|
+
*
|
|
441
|
+
* ## Canon
|
|
442
|
+
*
|
|
443
|
+
* - **UDD Program Data Object** (hti-features `udd-schemas/program/Program.v1.json`;
|
|
444
|
+
* profile confirmed by Crysta 2026-10-05): a Program (program / department /
|
|
445
|
+
* operational division / law-enforcement unit) is a fact about an
|
|
446
|
+
* ORGANIZATION — `org_id` is the owner. Its arrival is stored: `added_by`,
|
|
447
|
+
* `added_in_app`, `review_status`.
|
|
448
|
+
* - **PROGRAM-APP-ADDED** (prototype 2026-10-06; Crysta 2026-10-02: users
|
|
449
|
+
* "need to be able to capture org names and program names that may not be
|
|
450
|
+
* in existing list"): a program named inside an app is the organization's
|
|
451
|
+
* program from the moment it is typed, and waits for HTI Labs' review like a
|
|
452
|
+
* new organization does (GDR § 5.12 / § 5.16 rule 1). The steward's review
|
|
453
|
+
* queue in the HTI Platform confirms or rejects it; a confirmed row's "new"
|
|
454
|
+
* mark clears.
|
|
455
|
+
* - **ADR D13** (PAVE Greenfield): `SharingSettings` keys on
|
|
456
|
+
* `(organizationId, programId?)` — the program id is the join key an
|
|
457
|
+
* agency may share to.
|
|
458
|
+
*
|
|
459
|
+
* ## Field names
|
|
460
|
+
*
|
|
461
|
+
* Canon's program sheet spells these `program_id`, `label`, `review_status`,
|
|
462
|
+
* `added_by`, `added_in_app` (snake_case CSV columns). The live platform-db
|
|
463
|
+
* writers use camelCase (`programId`, `name`, `defaultSharingPolicy` are what
|
|
464
|
+
* PAVE 2.0 and Thread already store), so the arrival fields follow that
|
|
465
|
+
* convention: `reviewStatus`, `addedBy`, `addedInApp`, `addedInSession`.
|
|
466
|
+
*
|
|
467
|
+
* `addedInApp` is where the program was NAMED, not the program's own app
|
|
468
|
+
* (which app it operates in stays blank until the Admin Hub says).
|
|
469
|
+
*
|
|
470
|
+
* `addedInSession` is NOT on the UDD Program sheet (`Program.v1.json` carries
|
|
471
|
+
* `review_status · added_by · added_in_app` only). It is carried on the same
|
|
472
|
+
* precedent as the Org object's `added_in_session` (as-built OrgEntry overlay;
|
|
473
|
+
* RULED 2026-08-27 a migration note that retires into the `dataSource`
|
|
474
|
+
* provenance envelope at the cut-over) so a picker can tell "named in THIS
|
|
475
|
+
* session" from "awaiting review" across a reload. It retires with that trio.
|
|
476
|
+
*
|
|
477
|
+
* The sub-schema is STRICT (Mongoose default): a key outside the definition
|
|
478
|
+
* — including the sheet's snake_case spellings (`review_status`,
|
|
479
|
+
* `added_by`) — is dropped silently on cast, not rejected. Write camelCase.
|
|
480
|
+
*
|
|
481
|
+
* ## Who dedupes
|
|
482
|
+
*
|
|
483
|
+
* `programId` uniqueness and name-matching on add are the WRITER's job; the
|
|
484
|
+
* fragment enforces neither (two rows with one id validate and `$push`).
|
|
485
|
+
* PAVE 2.0's `POST /organizations/:id/programs` dedupes a typed name against
|
|
486
|
+
* the live rows (trimmed, case-insensitive) and mints `programId` server-side.
|
|
487
|
+
*
|
|
488
|
+
* ## Missingness
|
|
489
|
+
*
|
|
490
|
+
* `reviewStatus` is ABSENT (or null) on a steward row — nothing to review.
|
|
491
|
+
* There is no UNK / ANON / DNC here: the status is a lifecycle, not an
|
|
492
|
+
* answer anyone gives.
|
|
493
|
+
*/
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* Review lifecycle of a program named inside an app (UDD Program
|
|
497
|
+
* `review_status`). The sheet's own words — a lane's `pending_steward` /
|
|
498
|
+
* `declined` never reach the stored row.
|
|
499
|
+
*/
|
|
500
|
+
declare const PROGRAM_REVIEW_STATUS: {
|
|
501
|
+
readonly PENDING: "pending";
|
|
502
|
+
readonly CONFIRMED: "confirmed";
|
|
503
|
+
readonly REJECTED: "rejected";
|
|
504
|
+
};
|
|
505
|
+
type ProgramReviewStatus = (typeof PROGRAM_REVIEW_STATUS)[keyof typeof PROGRAM_REVIEW_STATUS];
|
|
506
|
+
/** The three values, for `enum:` declarations and Zod `z.enum`. */
|
|
507
|
+
declare const PROGRAM_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
|
|
508
|
+
declare function isProgramReviewStatus(value: unknown): value is ProgramReviewStatus;
|
|
509
|
+
/**
|
|
510
|
+
* One embedded Organization > Program row. `programId` + `name` are the
|
|
511
|
+
* load-bearing identity/label; everything else is optional and additive.
|
|
512
|
+
*
|
|
513
|
+
* `status` and `defaultSharingPolicy` are typed string codes (as PAVE 2.0 and
|
|
514
|
+
* Thread already store them — the CVC bind is a follow-up on the codebook,
|
|
515
|
+
* not this fragment).
|
|
516
|
+
*/
|
|
517
|
+
declare const organizationProgramSchemaDefinition: {
|
|
518
|
+
/** Stable identifier for the program within its Organization (server-minted). */
|
|
519
|
+
readonly programId: {
|
|
520
|
+
readonly type: StringConstructor;
|
|
521
|
+
readonly required: true;
|
|
522
|
+
};
|
|
523
|
+
/** Human-facing program name (canon `label`). */
|
|
524
|
+
readonly name: {
|
|
525
|
+
readonly type: StringConstructor;
|
|
526
|
+
readonly required: true;
|
|
527
|
+
};
|
|
528
|
+
/** Free-text program description. */
|
|
529
|
+
readonly description: {
|
|
530
|
+
readonly type: StringConstructor;
|
|
531
|
+
readonly required: false;
|
|
532
|
+
};
|
|
533
|
+
/** Lifecycle code; a `retired` program is not offered to pickers. */
|
|
534
|
+
readonly status: {
|
|
535
|
+
readonly type: StringConstructor;
|
|
536
|
+
readonly required: false;
|
|
537
|
+
};
|
|
538
|
+
/** Default sharing-policy code applied when sharing to this program (ADR D13). */
|
|
539
|
+
readonly defaultSharingPolicy: {
|
|
540
|
+
readonly type: StringConstructor;
|
|
541
|
+
readonly required: false;
|
|
542
|
+
};
|
|
543
|
+
/**
|
|
544
|
+
* pending · confirmed · rejected for a program named inside an app; absent on
|
|
545
|
+
* a steward row. A `rejected` row is never offered and never captures its
|
|
546
|
+
* name on a later add (a new row is minted).
|
|
547
|
+
*/
|
|
548
|
+
readonly reviewStatus: {
|
|
549
|
+
readonly type: StringConstructor;
|
|
550
|
+
readonly required: false;
|
|
551
|
+
readonly enum: readonly ["pending", "confirmed", "rejected"];
|
|
552
|
+
};
|
|
553
|
+
/** The seat (user id) that named it inside an app. */
|
|
554
|
+
readonly addedBy: {
|
|
555
|
+
readonly type: StringConstructor;
|
|
556
|
+
readonly required: false;
|
|
557
|
+
};
|
|
558
|
+
/** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
|
|
559
|
+
readonly addedInApp: {
|
|
560
|
+
readonly type: StringConstructor;
|
|
561
|
+
readonly required: false;
|
|
562
|
+
};
|
|
563
|
+
/** The session it was named in, when there was one. */
|
|
564
|
+
readonly addedInSession: {
|
|
565
|
+
readonly type: StringConstructor;
|
|
566
|
+
readonly required: false;
|
|
567
|
+
};
|
|
568
|
+
};
|
|
569
|
+
/**
|
|
570
|
+
* Build the program sub-schema. `{ _id: false }` — a program is identified by
|
|
571
|
+
* its own `programId`, not a Mongoose ObjectId (as both apps already do).
|
|
572
|
+
*/
|
|
573
|
+
declare function buildOrganizationProgramSchema(): Schema;
|
|
574
|
+
/**
|
|
575
|
+
* Build the `programs` field to add to an organization schema — a FRESH
|
|
576
|
+
* sub-schema per call. Mongoose does not clone a `Schema` instance on
|
|
577
|
+
* `schema.add()` or embedding, so a module-level instance would be shared by
|
|
578
|
+
* every consumer: a pre-hook, virtual or index one consumer put on its rows
|
|
579
|
+
* would run on, or be created for, every other consumer's documents (review
|
|
580
|
+
* finding, 2026-10-12). Each mount gets its own instance.
|
|
581
|
+
*
|
|
582
|
+
* `default: undefined` (NOT Mongoose's implicit `[]` for array paths): an
|
|
583
|
+
* organization without programs persists nothing and round-trips as absent,
|
|
584
|
+
* which keeps "none declared" distinct from "declared empty" and leaves every
|
|
585
|
+
* existing document's shape untouched.
|
|
586
|
+
*/
|
|
587
|
+
declare function buildOrganizationProgramsFieldDefinition(): {
|
|
588
|
+
programs: {
|
|
589
|
+
type: Schema[];
|
|
590
|
+
required: false;
|
|
591
|
+
default: undefined;
|
|
592
|
+
};
|
|
593
|
+
};
|
|
594
|
+
/**
|
|
595
|
+
* Update operations on which the row validators (enum, `required`) are
|
|
596
|
+
* enforced by {@link addOrganizationProgramsField}. Mongoose skips validators
|
|
597
|
+
* on update operations by default, and `$push` of a program row is the write
|
|
598
|
+
* path this fragment exists for (PAVE's `POST /organizations/:id/programs`).
|
|
599
|
+
*/
|
|
600
|
+
declare const ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: readonly ["updateOne", "updateMany", "findOneAndUpdate"];
|
|
601
|
+
interface AddOrganizationProgramsFieldOptions {
|
|
602
|
+
/** The path's `select` option; `false` is Thread's read posture. Omitted → Mongoose default. */
|
|
603
|
+
select?: boolean;
|
|
604
|
+
/**
|
|
605
|
+
* Install a `pre` hook on {@link ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS}
|
|
606
|
+
* that turns `runValidators` on unless the caller set it, so a `$push` of a
|
|
607
|
+
* row with a review status outside the vocabulary, or with no `programId`,
|
|
608
|
+
* is refused on the update paths exactly as on `save()` (the `agency.ts`
|
|
609
|
+
* precedent). Default `true`.
|
|
610
|
+
*
|
|
611
|
+
* SCHEMA-WIDE on these ops, not just `programs`: once mounted, every
|
|
612
|
+
* `updateOne` / `updateMany` / `findOneAndUpdate` on the consumer's schema
|
|
613
|
+
* runs validators for EVERY path it touches, unless the caller passes
|
|
614
|
+
* `runValidators` explicitly. A consumer that relied on Mongoose's default of
|
|
615
|
+
* skipping validators on updates for its other fields will see new
|
|
616
|
+
* rejections after mounting this. Pass `{ validateOnUpdate: false }` to opt
|
|
617
|
+
* out, or set `runValidators: false` on an individual query.
|
|
618
|
+
*/
|
|
619
|
+
validateOnUpdate?: boolean;
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Add the `programs[]` field to an existing organization schema.
|
|
623
|
+
*
|
|
624
|
+
* Adds no indexes. Installs the update-path validation hook described on
|
|
625
|
+
* {@link AddOrganizationProgramsFieldOptions} unless opted out. A consumer
|
|
626
|
+
* that wants `select: false` on the field (Thread) passes `{ select: false }`.
|
|
627
|
+
*
|
|
628
|
+
* REPLACES a `programs` path the consumer already declares (`schema.add`
|
|
629
|
+
* overwrites the path wholesale — the consumer's own sub-fields and its own
|
|
630
|
+
* `select` option do not survive). That is the point of ONE definition: a
|
|
631
|
+
* consumer removes its local `programs` declaration and passes its read
|
|
632
|
+
* posture here instead. A `console.warn` names the overwrite so a consumer
|
|
633
|
+
* that forgot does not lose `select: false` silently.
|
|
634
|
+
*
|
|
635
|
+
* @param schema - The consumer's organization schema
|
|
636
|
+
* @returns The same schema, for chaining
|
|
637
|
+
*/
|
|
638
|
+
declare function addOrganizationProgramsField<S extends Schema>(schema: S, options?: AddOrganizationProgramsFieldOptions): S;
|
|
639
|
+
/**
|
|
640
|
+
* Whether a program row may be OFFERED (and matched by name on an add).
|
|
641
|
+
* A retired or rejected program is not a place anyone can be enrolled today,
|
|
642
|
+
* so pickers do not list it and typing its name mints a new row rather than
|
|
643
|
+
* binding to it (the prototype's independent pre-review catch, 2026-10-06).
|
|
644
|
+
*/
|
|
645
|
+
declare function isLiveOrganizationProgram(row: {
|
|
646
|
+
status?: string | null | undefined;
|
|
647
|
+
reviewStatus?: string | null | undefined;
|
|
648
|
+
}): boolean;
|
|
649
|
+
/**
|
|
650
|
+
* Raw (persistence) shape of one program row, inferred from the DEFINITION.
|
|
651
|
+
*
|
|
652
|
+
* `programId` + `name` are required; every other field is optional (and may
|
|
653
|
+
* be `null`); `reviewStatus` is the three-word union. `{ _id: false }` matches
|
|
654
|
+
* the sub-schema, so the type carries no `_id` (the definition is `as const`
|
|
655
|
+
* so `required: false` stays a literal and is honoured by the inference).
|
|
656
|
+
*/
|
|
657
|
+
type OrganizationProgram = InferRawDocType<typeof organizationProgramSchemaDefinition, {
|
|
658
|
+
_id: false;
|
|
659
|
+
typeKey: "type";
|
|
660
|
+
}>;
|
|
661
|
+
|
|
662
|
+
export { type AddOrganizationProgramsFieldOptions, type Address, type Demographics, type Email, ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS, type OrganizationProgram, PROGRAM_REVIEW_STATUS, PROGRAM_REVIEW_STATUS_VALUES, type PersonName, type Phone, type ProgramReviewStatus, TEAM_MODEL_NAME, type TeamDirectoryFields, addOrganizationProgramsField, addTeamDirectoryFields, addressSchema, buildOrganizationProgramSchema, buildOrganizationProgramsFieldDefinition, demographicsSchema, emailSchema, isLiveOrganizationProgram, isProgramReviewStatus, organizationProgramSchemaDefinition, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
|
package/dist/schemas/index.d.ts
CHANGED
|
@@ -420,4 +420,243 @@ declare function addTeamDirectoryFields<S extends Schema>(schema: S): S;
|
|
|
420
420
|
*/
|
|
421
421
|
type TeamDirectoryFields = Partial<InferRawDocType<typeof teamDirectorySchemaDefinition>>;
|
|
422
422
|
|
|
423
|
-
|
|
423
|
+
/**
|
|
424
|
+
* @htilabs/platform-common-models — Organization program rows (`organizations.programs[]`)
|
|
425
|
+
*
|
|
426
|
+
* The ONE definition of the embedded program sub-document on the platform-db
|
|
427
|
+
* `organizations` collection, which both apps read and PAVE 2.0 writes.
|
|
428
|
+
*
|
|
429
|
+
* ## This is a FRAGMENT, not an Organization model
|
|
430
|
+
*
|
|
431
|
+
* No canonical Organization schema exists in this package (same posture as
|
|
432
|
+
* `schemas/team.ts` and `schemas/agency.ts`). `organizations` is written by
|
|
433
|
+
* PAVE 2.0 (`packages/db/src/models/organization.ts`) and read by Thread
|
|
434
|
+
* (`packages/db/src/models/platform/Organization.ts`, `select: false` on
|
|
435
|
+
* `programs`, read with `+programs`). Until this module, each app carried its
|
|
436
|
+
* own copy of the sub-schema — identical by hand. This module declares the
|
|
437
|
+
* program row ONCE; each consumer mounts it with
|
|
438
|
+
* {@link addOrganizationProgramsField} or builds the sub-schema with
|
|
439
|
+
* {@link buildOrganizationProgramSchema}.
|
|
440
|
+
*
|
|
441
|
+
* ## Canon
|
|
442
|
+
*
|
|
443
|
+
* - **UDD Program Data Object** (hti-features `udd-schemas/program/Program.v1.json`;
|
|
444
|
+
* profile confirmed by Crysta 2026-10-05): a Program (program / department /
|
|
445
|
+
* operational division / law-enforcement unit) is a fact about an
|
|
446
|
+
* ORGANIZATION — `org_id` is the owner. Its arrival is stored: `added_by`,
|
|
447
|
+
* `added_in_app`, `review_status`.
|
|
448
|
+
* - **PROGRAM-APP-ADDED** (prototype 2026-10-06; Crysta 2026-10-02: users
|
|
449
|
+
* "need to be able to capture org names and program names that may not be
|
|
450
|
+
* in existing list"): a program named inside an app is the organization's
|
|
451
|
+
* program from the moment it is typed, and waits for HTI Labs' review like a
|
|
452
|
+
* new organization does (GDR § 5.12 / § 5.16 rule 1). The steward's review
|
|
453
|
+
* queue in the HTI Platform confirms or rejects it; a confirmed row's "new"
|
|
454
|
+
* mark clears.
|
|
455
|
+
* - **ADR D13** (PAVE Greenfield): `SharingSettings` keys on
|
|
456
|
+
* `(organizationId, programId?)` — the program id is the join key an
|
|
457
|
+
* agency may share to.
|
|
458
|
+
*
|
|
459
|
+
* ## Field names
|
|
460
|
+
*
|
|
461
|
+
* Canon's program sheet spells these `program_id`, `label`, `review_status`,
|
|
462
|
+
* `added_by`, `added_in_app` (snake_case CSV columns). The live platform-db
|
|
463
|
+
* writers use camelCase (`programId`, `name`, `defaultSharingPolicy` are what
|
|
464
|
+
* PAVE 2.0 and Thread already store), so the arrival fields follow that
|
|
465
|
+
* convention: `reviewStatus`, `addedBy`, `addedInApp`, `addedInSession`.
|
|
466
|
+
*
|
|
467
|
+
* `addedInApp` is where the program was NAMED, not the program's own app
|
|
468
|
+
* (which app it operates in stays blank until the Admin Hub says).
|
|
469
|
+
*
|
|
470
|
+
* `addedInSession` is NOT on the UDD Program sheet (`Program.v1.json` carries
|
|
471
|
+
* `review_status · added_by · added_in_app` only). It is carried on the same
|
|
472
|
+
* precedent as the Org object's `added_in_session` (as-built OrgEntry overlay;
|
|
473
|
+
* RULED 2026-08-27 a migration note that retires into the `dataSource`
|
|
474
|
+
* provenance envelope at the cut-over) so a picker can tell "named in THIS
|
|
475
|
+
* session" from "awaiting review" across a reload. It retires with that trio.
|
|
476
|
+
*
|
|
477
|
+
* The sub-schema is STRICT (Mongoose default): a key outside the definition
|
|
478
|
+
* — including the sheet's snake_case spellings (`review_status`,
|
|
479
|
+
* `added_by`) — is dropped silently on cast, not rejected. Write camelCase.
|
|
480
|
+
*
|
|
481
|
+
* ## Who dedupes
|
|
482
|
+
*
|
|
483
|
+
* `programId` uniqueness and name-matching on add are the WRITER's job; the
|
|
484
|
+
* fragment enforces neither (two rows with one id validate and `$push`).
|
|
485
|
+
* PAVE 2.0's `POST /organizations/:id/programs` dedupes a typed name against
|
|
486
|
+
* the live rows (trimmed, case-insensitive) and mints `programId` server-side.
|
|
487
|
+
*
|
|
488
|
+
* ## Missingness
|
|
489
|
+
*
|
|
490
|
+
* `reviewStatus` is ABSENT (or null) on a steward row — nothing to review.
|
|
491
|
+
* There is no UNK / ANON / DNC here: the status is a lifecycle, not an
|
|
492
|
+
* answer anyone gives.
|
|
493
|
+
*/
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* Review lifecycle of a program named inside an app (UDD Program
|
|
497
|
+
* `review_status`). The sheet's own words — a lane's `pending_steward` /
|
|
498
|
+
* `declined` never reach the stored row.
|
|
499
|
+
*/
|
|
500
|
+
declare const PROGRAM_REVIEW_STATUS: {
|
|
501
|
+
readonly PENDING: "pending";
|
|
502
|
+
readonly CONFIRMED: "confirmed";
|
|
503
|
+
readonly REJECTED: "rejected";
|
|
504
|
+
};
|
|
505
|
+
type ProgramReviewStatus = (typeof PROGRAM_REVIEW_STATUS)[keyof typeof PROGRAM_REVIEW_STATUS];
|
|
506
|
+
/** The three values, for `enum:` declarations and Zod `z.enum`. */
|
|
507
|
+
declare const PROGRAM_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
|
|
508
|
+
declare function isProgramReviewStatus(value: unknown): value is ProgramReviewStatus;
|
|
509
|
+
/**
|
|
510
|
+
* One embedded Organization > Program row. `programId` + `name` are the
|
|
511
|
+
* load-bearing identity/label; everything else is optional and additive.
|
|
512
|
+
*
|
|
513
|
+
* `status` and `defaultSharingPolicy` are typed string codes (as PAVE 2.0 and
|
|
514
|
+
* Thread already store them — the CVC bind is a follow-up on the codebook,
|
|
515
|
+
* not this fragment).
|
|
516
|
+
*/
|
|
517
|
+
declare const organizationProgramSchemaDefinition: {
|
|
518
|
+
/** Stable identifier for the program within its Organization (server-minted). */
|
|
519
|
+
readonly programId: {
|
|
520
|
+
readonly type: StringConstructor;
|
|
521
|
+
readonly required: true;
|
|
522
|
+
};
|
|
523
|
+
/** Human-facing program name (canon `label`). */
|
|
524
|
+
readonly name: {
|
|
525
|
+
readonly type: StringConstructor;
|
|
526
|
+
readonly required: true;
|
|
527
|
+
};
|
|
528
|
+
/** Free-text program description. */
|
|
529
|
+
readonly description: {
|
|
530
|
+
readonly type: StringConstructor;
|
|
531
|
+
readonly required: false;
|
|
532
|
+
};
|
|
533
|
+
/** Lifecycle code; a `retired` program is not offered to pickers. */
|
|
534
|
+
readonly status: {
|
|
535
|
+
readonly type: StringConstructor;
|
|
536
|
+
readonly required: false;
|
|
537
|
+
};
|
|
538
|
+
/** Default sharing-policy code applied when sharing to this program (ADR D13). */
|
|
539
|
+
readonly defaultSharingPolicy: {
|
|
540
|
+
readonly type: StringConstructor;
|
|
541
|
+
readonly required: false;
|
|
542
|
+
};
|
|
543
|
+
/**
|
|
544
|
+
* pending · confirmed · rejected for a program named inside an app; absent on
|
|
545
|
+
* a steward row. A `rejected` row is never offered and never captures its
|
|
546
|
+
* name on a later add (a new row is minted).
|
|
547
|
+
*/
|
|
548
|
+
readonly reviewStatus: {
|
|
549
|
+
readonly type: StringConstructor;
|
|
550
|
+
readonly required: false;
|
|
551
|
+
readonly enum: readonly ["pending", "confirmed", "rejected"];
|
|
552
|
+
};
|
|
553
|
+
/** The seat (user id) that named it inside an app. */
|
|
554
|
+
readonly addedBy: {
|
|
555
|
+
readonly type: StringConstructor;
|
|
556
|
+
readonly required: false;
|
|
557
|
+
};
|
|
558
|
+
/** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
|
|
559
|
+
readonly addedInApp: {
|
|
560
|
+
readonly type: StringConstructor;
|
|
561
|
+
readonly required: false;
|
|
562
|
+
};
|
|
563
|
+
/** The session it was named in, when there was one. */
|
|
564
|
+
readonly addedInSession: {
|
|
565
|
+
readonly type: StringConstructor;
|
|
566
|
+
readonly required: false;
|
|
567
|
+
};
|
|
568
|
+
};
|
|
569
|
+
/**
|
|
570
|
+
* Build the program sub-schema. `{ _id: false }` — a program is identified by
|
|
571
|
+
* its own `programId`, not a Mongoose ObjectId (as both apps already do).
|
|
572
|
+
*/
|
|
573
|
+
declare function buildOrganizationProgramSchema(): Schema;
|
|
574
|
+
/**
|
|
575
|
+
* Build the `programs` field to add to an organization schema — a FRESH
|
|
576
|
+
* sub-schema per call. Mongoose does not clone a `Schema` instance on
|
|
577
|
+
* `schema.add()` or embedding, so a module-level instance would be shared by
|
|
578
|
+
* every consumer: a pre-hook, virtual or index one consumer put on its rows
|
|
579
|
+
* would run on, or be created for, every other consumer's documents (review
|
|
580
|
+
* finding, 2026-10-12). Each mount gets its own instance.
|
|
581
|
+
*
|
|
582
|
+
* `default: undefined` (NOT Mongoose's implicit `[]` for array paths): an
|
|
583
|
+
* organization without programs persists nothing and round-trips as absent,
|
|
584
|
+
* which keeps "none declared" distinct from "declared empty" and leaves every
|
|
585
|
+
* existing document's shape untouched.
|
|
586
|
+
*/
|
|
587
|
+
declare function buildOrganizationProgramsFieldDefinition(): {
|
|
588
|
+
programs: {
|
|
589
|
+
type: Schema[];
|
|
590
|
+
required: false;
|
|
591
|
+
default: undefined;
|
|
592
|
+
};
|
|
593
|
+
};
|
|
594
|
+
/**
|
|
595
|
+
* Update operations on which the row validators (enum, `required`) are
|
|
596
|
+
* enforced by {@link addOrganizationProgramsField}. Mongoose skips validators
|
|
597
|
+
* on update operations by default, and `$push` of a program row is the write
|
|
598
|
+
* path this fragment exists for (PAVE's `POST /organizations/:id/programs`).
|
|
599
|
+
*/
|
|
600
|
+
declare const ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: readonly ["updateOne", "updateMany", "findOneAndUpdate"];
|
|
601
|
+
interface AddOrganizationProgramsFieldOptions {
|
|
602
|
+
/** The path's `select` option; `false` is Thread's read posture. Omitted → Mongoose default. */
|
|
603
|
+
select?: boolean;
|
|
604
|
+
/**
|
|
605
|
+
* Install a `pre` hook on {@link ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS}
|
|
606
|
+
* that turns `runValidators` on unless the caller set it, so a `$push` of a
|
|
607
|
+
* row with a review status outside the vocabulary, or with no `programId`,
|
|
608
|
+
* is refused on the update paths exactly as on `save()` (the `agency.ts`
|
|
609
|
+
* precedent). Default `true`.
|
|
610
|
+
*
|
|
611
|
+
* SCHEMA-WIDE on these ops, not just `programs`: once mounted, every
|
|
612
|
+
* `updateOne` / `updateMany` / `findOneAndUpdate` on the consumer's schema
|
|
613
|
+
* runs validators for EVERY path it touches, unless the caller passes
|
|
614
|
+
* `runValidators` explicitly. A consumer that relied on Mongoose's default of
|
|
615
|
+
* skipping validators on updates for its other fields will see new
|
|
616
|
+
* rejections after mounting this. Pass `{ validateOnUpdate: false }` to opt
|
|
617
|
+
* out, or set `runValidators: false` on an individual query.
|
|
618
|
+
*/
|
|
619
|
+
validateOnUpdate?: boolean;
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Add the `programs[]` field to an existing organization schema.
|
|
623
|
+
*
|
|
624
|
+
* Adds no indexes. Installs the update-path validation hook described on
|
|
625
|
+
* {@link AddOrganizationProgramsFieldOptions} unless opted out. A consumer
|
|
626
|
+
* that wants `select: false` on the field (Thread) passes `{ select: false }`.
|
|
627
|
+
*
|
|
628
|
+
* REPLACES a `programs` path the consumer already declares (`schema.add`
|
|
629
|
+
* overwrites the path wholesale — the consumer's own sub-fields and its own
|
|
630
|
+
* `select` option do not survive). That is the point of ONE definition: a
|
|
631
|
+
* consumer removes its local `programs` declaration and passes its read
|
|
632
|
+
* posture here instead. A `console.warn` names the overwrite so a consumer
|
|
633
|
+
* that forgot does not lose `select: false` silently.
|
|
634
|
+
*
|
|
635
|
+
* @param schema - The consumer's organization schema
|
|
636
|
+
* @returns The same schema, for chaining
|
|
637
|
+
*/
|
|
638
|
+
declare function addOrganizationProgramsField<S extends Schema>(schema: S, options?: AddOrganizationProgramsFieldOptions): S;
|
|
639
|
+
/**
|
|
640
|
+
* Whether a program row may be OFFERED (and matched by name on an add).
|
|
641
|
+
* A retired or rejected program is not a place anyone can be enrolled today,
|
|
642
|
+
* so pickers do not list it and typing its name mints a new row rather than
|
|
643
|
+
* binding to it (the prototype's independent pre-review catch, 2026-10-06).
|
|
644
|
+
*/
|
|
645
|
+
declare function isLiveOrganizationProgram(row: {
|
|
646
|
+
status?: string | null | undefined;
|
|
647
|
+
reviewStatus?: string | null | undefined;
|
|
648
|
+
}): boolean;
|
|
649
|
+
/**
|
|
650
|
+
* Raw (persistence) shape of one program row, inferred from the DEFINITION.
|
|
651
|
+
*
|
|
652
|
+
* `programId` + `name` are required; every other field is optional (and may
|
|
653
|
+
* be `null`); `reviewStatus` is the three-word union. `{ _id: false }` matches
|
|
654
|
+
* the sub-schema, so the type carries no `_id` (the definition is `as const`
|
|
655
|
+
* so `required: false` stays a literal and is honoured by the inference).
|
|
656
|
+
*/
|
|
657
|
+
type OrganizationProgram = InferRawDocType<typeof organizationProgramSchemaDefinition, {
|
|
658
|
+
_id: false;
|
|
659
|
+
typeKey: "type";
|
|
660
|
+
}>;
|
|
661
|
+
|
|
662
|
+
export { type AddOrganizationProgramsFieldOptions, type Address, type Demographics, type Email, ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS, type OrganizationProgram, PROGRAM_REVIEW_STATUS, PROGRAM_REVIEW_STATUS_VALUES, type PersonName, type Phone, type ProgramReviewStatus, TEAM_MODEL_NAME, type TeamDirectoryFields, addOrganizationProgramsField, addTeamDirectoryFields, addressSchema, buildOrganizationProgramSchema, buildOrganizationProgramsFieldDefinition, demographicsSchema, emailSchema, isLiveOrganizationProgram, isProgramReviewStatus, organizationProgramSchemaDefinition, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
|
package/dist/schemas/index.js
CHANGED
|
@@ -5782,13 +5782,103 @@ function orgTypeFieldsDiffer(org, agency) {
|
|
|
5782
5782
|
const b = pickOrgTypeFields(agency);
|
|
5783
5783
|
return ORG_TYPE_FIELD_NAMES.filter((k) => a[k] !== b[k]);
|
|
5784
5784
|
}
|
|
5785
|
+
|
|
5786
|
+
// src/schemas/organization-program.ts
|
|
5787
|
+
import { Schema as Schema11 } from "mongoose";
|
|
5788
|
+
var PROGRAM_REVIEW_STATUS = {
|
|
5789
|
+
PENDING: "pending",
|
|
5790
|
+
CONFIRMED: "confirmed",
|
|
5791
|
+
REJECTED: "rejected"
|
|
5792
|
+
};
|
|
5793
|
+
var PROGRAM_REVIEW_STATUS_VALUES = Object.freeze([
|
|
5794
|
+
PROGRAM_REVIEW_STATUS.PENDING,
|
|
5795
|
+
PROGRAM_REVIEW_STATUS.CONFIRMED,
|
|
5796
|
+
PROGRAM_REVIEW_STATUS.REJECTED
|
|
5797
|
+
]);
|
|
5798
|
+
function isProgramReviewStatus(value) {
|
|
5799
|
+
return typeof value === "string" && PROGRAM_REVIEW_STATUS_VALUES.includes(value);
|
|
5800
|
+
}
|
|
5801
|
+
var organizationProgramSchemaDefinition = {
|
|
5802
|
+
/** Stable identifier for the program within its Organization (server-minted). */
|
|
5803
|
+
programId: { type: String, required: true },
|
|
5804
|
+
/** Human-facing program name (canon `label`). */
|
|
5805
|
+
name: { type: String, required: true },
|
|
5806
|
+
/** Free-text program description. */
|
|
5807
|
+
description: { type: String, required: false },
|
|
5808
|
+
/** Lifecycle code; a `retired` program is not offered to pickers. */
|
|
5809
|
+
status: { type: String, required: false },
|
|
5810
|
+
/** Default sharing-policy code applied when sharing to this program (ADR D13). */
|
|
5811
|
+
defaultSharingPolicy: { type: String, required: false },
|
|
5812
|
+
/**
|
|
5813
|
+
* pending · confirmed · rejected for a program named inside an app; absent on
|
|
5814
|
+
* a steward row. A `rejected` row is never offered and never captures its
|
|
5815
|
+
* name on a later add (a new row is minted).
|
|
5816
|
+
*/
|
|
5817
|
+
reviewStatus: {
|
|
5818
|
+
type: String,
|
|
5819
|
+
required: false,
|
|
5820
|
+
enum: [...PROGRAM_REVIEW_STATUS_VALUES]
|
|
5821
|
+
},
|
|
5822
|
+
/** The seat (user id) that named it inside an app. */
|
|
5823
|
+
addedBy: { type: String, required: false },
|
|
5824
|
+
/** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
|
|
5825
|
+
addedInApp: { type: String, required: false },
|
|
5826
|
+
/** The session it was named in, when there was one. */
|
|
5827
|
+
addedInSession: { type: String, required: false }
|
|
5828
|
+
};
|
|
5829
|
+
function buildOrganizationProgramSchema() {
|
|
5830
|
+
return new Schema11(organizationProgramSchemaDefinition, { _id: false });
|
|
5831
|
+
}
|
|
5832
|
+
function buildOrganizationProgramsFieldDefinition() {
|
|
5833
|
+
return {
|
|
5834
|
+
programs: {
|
|
5835
|
+
type: [buildOrganizationProgramSchema()],
|
|
5836
|
+
required: false,
|
|
5837
|
+
default: void 0
|
|
5838
|
+
}
|
|
5839
|
+
};
|
|
5840
|
+
}
|
|
5841
|
+
var ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS = Object.freeze([
|
|
5842
|
+
"updateOne",
|
|
5843
|
+
"updateMany",
|
|
5844
|
+
"findOneAndUpdate"
|
|
5845
|
+
]);
|
|
5846
|
+
function addOrganizationProgramsField(schema, options = {}) {
|
|
5847
|
+
if (schema.path("programs")) {
|
|
5848
|
+
console.warn(
|
|
5849
|
+
"[platform-common-models] addOrganizationProgramsField: replacing the schema's own `programs` path with the shared fragment; pass `{ select: false }` here if that is the consumer's read posture."
|
|
5850
|
+
);
|
|
5851
|
+
}
|
|
5852
|
+
schema.add({
|
|
5853
|
+
programs: {
|
|
5854
|
+
...buildOrganizationProgramsFieldDefinition().programs,
|
|
5855
|
+
...options.select !== void 0 ? { select: options.select } : {}
|
|
5856
|
+
}
|
|
5857
|
+
});
|
|
5858
|
+
if (options.validateOnUpdate ?? true) {
|
|
5859
|
+
schema.pre(
|
|
5860
|
+
[...ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS],
|
|
5861
|
+
function() {
|
|
5862
|
+
applyRunValidatorsIfUnset(this);
|
|
5863
|
+
}
|
|
5864
|
+
);
|
|
5865
|
+
}
|
|
5866
|
+
return schema;
|
|
5867
|
+
}
|
|
5868
|
+
function isLiveOrganizationProgram(row) {
|
|
5869
|
+
return row.status !== "retired" && row.reviewStatus !== PROGRAM_REVIEW_STATUS.REJECTED;
|
|
5870
|
+
}
|
|
5785
5871
|
export {
|
|
5786
5872
|
AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS,
|
|
5873
|
+
ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
|
|
5787
5874
|
ORG_TYPE_FIELD_NAMES,
|
|
5875
|
+
PROGRAM_REVIEW_STATUS,
|
|
5876
|
+
PROGRAM_REVIEW_STATUS_VALUES,
|
|
5788
5877
|
TEAM_MODEL_NAME,
|
|
5789
5878
|
VSP_TWO_STEP_ISSUE,
|
|
5790
5879
|
addAgencyOrgTypeFields,
|
|
5791
5880
|
addOrgTypeFields,
|
|
5881
|
+
addOrganizationProgramsField,
|
|
5792
5882
|
addTeamDirectoryFields,
|
|
5793
5883
|
addressSchema,
|
|
5794
5884
|
agencyOrgTypeSchemaDefinition,
|
|
@@ -5796,6 +5886,8 @@ export {
|
|
|
5796
5886
|
buildCvcEntrySchema,
|
|
5797
5887
|
buildCvcRegistrySchema,
|
|
5798
5888
|
buildFormSchema,
|
|
5889
|
+
buildOrganizationProgramSchema,
|
|
5890
|
+
buildOrganizationProgramsFieldDefinition,
|
|
5799
5891
|
buildPlatformFunctionSchema,
|
|
5800
5892
|
buildPlatformRoleSchema,
|
|
5801
5893
|
buildQuestionSchema,
|
|
@@ -5812,10 +5904,13 @@ export {
|
|
|
5812
5904
|
formSchemaOptions,
|
|
5813
5905
|
formSectionRefSchema,
|
|
5814
5906
|
guidanceSchema,
|
|
5907
|
+
isLiveOrganizationProgram,
|
|
5908
|
+
isProgramReviewStatus,
|
|
5815
5909
|
layoutSchema,
|
|
5816
5910
|
mirrorOrgTypeFields,
|
|
5817
5911
|
orgTypeFieldsDiffer,
|
|
5818
5912
|
orgTypeSchemaDefinition,
|
|
5913
|
+
organizationProgramSchemaDefinition,
|
|
5819
5914
|
personNameSchema,
|
|
5820
5915
|
phoneSchema,
|
|
5821
5916
|
platformFunctionSchemaDefinition,
|