placementt-core 1.400.922 → 1.400.923

package/lib/typeDefinitions.d.ts

@@ -883,6 +883,7 @@ export type InstituteData = {
         yearGroupsIncluded?: number[];
         closeAfterDays?: number;
     };
+    destinationsConfig?: DestinationsConfig;
     acceptingAlumni?: boolean;
     approveAlumni?: boolean;
     shareAlumni?: boolean;
@@ -1983,6 +1984,76 @@ export type AspirationCycle = {
     aggregates?: AspirationAggregates;
     emailTemplateId?: string;
     studentSelection?: string;
+    autoProvisioned?: boolean;
+    resolveRecipientsAtSend?: boolean;
+};
+/**
+ * Extra recipient constraints beyond "active student in the target year group".
+ * Same shape as a cohortFilters entry. Empty/absent = every active student in the
+ * year group. Stored on DestinationsConfig and re-resolved at each send so the
+ * cohort always reflects the live roster (students roll up a year each September).
+ */
+export type DestinationsRecipientFilter = {
+    k: string;
+    e?: WhereFilterOp;
+    v: unknown;
+}[];
+/** One scheduled survey in a year's aspiration programme. `sendMMDD` is "MM-DD". */
+export type AspirationSurveySlot = {
+    sendMMDD: string;
+    label?: string;
+};
+/**
+ * One-time Destinations setup, saved on institutes/{oId}.destinationsConfig by the
+ * setup wizard. destinationsProvisionCron reads it each year to auto-create that
+ * year's aspiration cycles and leaver groups. All MM-DD strings are zero-padded
+ * (e.g. "09-15"). Recipients are NOT frozen here — only the filter rule is stored;
+ * the actual student list is resolved when each form's emails fire.
+ */
+export type DestinationsConfig = {
+    aspirations: {
+        enabled: boolean;
+        yearGroups: number[];
+        /** Shared schedule applied to every selected year group (1–3 sends/year). */
+        surveys: AspirationSurveySlot[];
+        /** Optional per-year-group override. When a year group key is present its
+         * schedule REPLACES `surveys` for that year group only. */
+        surveysByYearGroup?: {
+            [yearGroup: string]: AspirationSurveySlot[];
+        };
+        closeAfterDays: number;
+        /** Extra constraints on top of "active Year-N student". Re-resolved each send. */
+        recipientFilters?: DestinationsRecipientFilter;
+    };
+    leavers: {
+        enabled: boolean;
+        yearGroups: number[];
+        intentionsSendMMDD: string;
+        resultsDay: {
+            enabled: boolean;
+            sendMMDD: string;
+        };
+        christmas: {
+            enabled: boolean;
+            sendMMDD: string;
+        };
+        /** true → every student in these groups leaves (no internal sixth form). */
+        allStudentsLeave?: boolean;
+        recipientFilters?: DestinationsRecipientFilter;
+    };
+    alumni: {
+        acceptingAlumni: boolean;
+        approveAlumni: boolean;
+        alumniConversations: boolean;
+        visibleToStudents: boolean;
+    };
+    /** MM-DD on which each new academic year's objects are created. Default "09-01". */
+    provisionMMDD: string;
+    /** e.g. "2026/27" — last academic year the cron provisioned. Guards double-provisioning. */
+    lastProvisionedYear?: string;
+    setupCompletedAt: string;
+    setupBy: string;
+    updatedAt?: string;
 };
 /**
  * Pre-aggregated leaver response counts on a LeaverGroup — updated atomically via
@@ -3041,6 +3112,11 @@ export type LeaverGroup = {
      * asks "are you staying on?" first, and stayers skip the alumni / consent
      * capture (and aren't seeded as alumni). */
     allStudentsLeave?: boolean;
+    /** Created by destinationsProvisionCron from the institute's DestinationsConfig
+     * (not via the manual New Leaver Group flow). Auto-provisioned groups defer
+     * recipient fan-out: leaverRequests are built from `students` when invite
+     * emails fire, so the cohort is always resolved against the live roster. */
+    autoProvisioned?: boolean;
     /** Post-leaving checkpoint schedule. Absent = checkpoints disabled for this group. */
     checkpointConfig?: {
         resultsDay?: {

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.922",
+  "version": "1.400.923",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/typeDefinitions.ts

@@ -871,12 +871,17 @@ export type InstituteData = {
         }
     },
     // ASPIRATION CYCLE CONFIGURATION (Form A — annual student intent tracking)
+    // @deprecated dead config — never read at runtime. Superseded by destinationsConfig.
     aspirationCycleConfig?: {
         autoSend?: boolean,                     // if true, cron fires each year on scheduledSendMMDD
         scheduledSendMMDD?: string,             // e.g. "09-15" — MM-DD of annual auto-send
         yearGroupsIncluded?: number[],          // which year groups receive Form A; default [7,8,9,10,11]
         closeAfterDays?: number,                // default 21 — link validity window
     },
+    // DESTINATIONS SETUP + ANNUAL AUTO-PROVISIONING (Form A + Form B + checkpoints)
+    // Written by the setup wizard (aspirations-saveDestinationsConfig); read by
+    // destinationsProvisionCron each September to create that year's surveys/groups.
+    destinationsConfig?: DestinationsConfig,
     acceptingAlumni?: boolean,
     approveAlumni?: boolean,
     shareAlumni?: boolean
@@ -1895,7 +1900,68 @@ export type AspirationCycle = {
     reminderSentAt?: string,                    // ISO — day-14 reminder fire time
     aggregates?: AspirationAggregates,          // pre-aggregated response data for dashboard charts
     emailTemplateId?: string,                   // optional custom email template; falls back to system default
-    studentSelection?: string,                  // JSON-serialised DataViewerSelectionBackend — audit of staff-picked recipients
+    studentSelection?: string,                  // JSON-serialised DataViewerSelectionBackend — audit of staff-picked recipients (or the rule to re-resolve when resolveRecipientsAtSend)
+    autoProvisioned?: boolean,                   // created by destinationsProvisionCron from the institute's DestinationsConfig, not by staff
+    resolveRecipientsAtSend?: boolean,           // true on auto-provisioned cycles — aspirationRequests are fanned out from studentSelection when emails fire, not at creation
+}
+
+/**
+ * Extra recipient constraints beyond "active student in the target year group".
+ * Same shape as a cohortFilters entry. Empty/absent = every active student in the
+ * year group. Stored on DestinationsConfig and re-resolved at each send so the
+ * cohort always reflects the live roster (students roll up a year each September).
+ */
+export type DestinationsRecipientFilter = {k: string, e?: WhereFilterOp, v: unknown}[];
+
+/** One scheduled survey in a year's aspiration programme. `sendMMDD` is "MM-DD". */
+export type AspirationSurveySlot = {sendMMDD: string, label?: string};
+
+/**
+ * One-time Destinations setup, saved on institutes/{oId}.destinationsConfig by the
+ * setup wizard. destinationsProvisionCron reads it each year to auto-create that
+ * year's aspiration cycles and leaver groups. All MM-DD strings are zero-padded
+ * (e.g. "09-15"). Recipients are NOT frozen here — only the filter rule is stored;
+ * the actual student list is resolved when each form's emails fire.
+ */
+export type DestinationsConfig = {
+    // ── Aspirations (Form A) ──
+    aspirations: {
+        enabled: boolean,
+        yearGroups: number[],                   // e.g. [7,8,9,10,11]
+        /** Shared schedule applied to every selected year group (1–3 sends/year). */
+        surveys: AspirationSurveySlot[],
+        /** Optional per-year-group override. When a year group key is present its
+         * schedule REPLACES `surveys` for that year group only. */
+        surveysByYearGroup?: {[yearGroup: string]: AspirationSurveySlot[]},
+        closeAfterDays: number,                 // default 21
+        /** Extra constraints on top of "active Year-N student". Re-resolved each send. */
+        recipientFilters?: DestinationsRecipientFilter,
+    },
+    // ── Leavers (Form B + checkpoints) ──
+    leavers: {
+        enabled: boolean,
+        yearGroups: number[],                   // subset of [11, 13]
+        intentionsSendMMDD: string,             // Form B, before they leave — default "06-15"
+        resultsDay: {enabled: boolean, sendMMDD: string},   // default "08-29"
+        christmas: {enabled: boolean, sendMMDD: string},    // default "12-08"
+        /** true → every student in these groups leaves (no internal sixth form). */
+        allStudentsLeave?: boolean,
+        recipientFilters?: DestinationsRecipientFilter,
+    },
+    // ── Alumni (mirrors the institute root flags) ──
+    alumni: {
+        acceptingAlumni: boolean,
+        approveAlumni: boolean,
+        alumniConversations: boolean,
+        visibleToStudents: boolean,             // default visibility for new alumni records
+    },
+    /** MM-DD on which each new academic year's objects are created. Default "09-01". */
+    provisionMMDD: string,
+    /** e.g. "2026/27" — last academic year the cron provisioned. Guards double-provisioning. */
+    lastProvisionedYear?: string,
+    setupCompletedAt: string,                   // ISO — stamped server-side on first save
+    setupBy: string,                            // staff uid — stamped server-side
+    updatedAt?: string,
 }
 
 /**
@@ -3036,6 +3102,12 @@ export type LeaverGroup = {
      * capture (and aren't seeded as alumni). */
     allStudentsLeave?: boolean,
 
+    /** Created by destinationsProvisionCron from the institute's DestinationsConfig
+     * (not via the manual New Leaver Group flow). Auto-provisioned groups defer
+     * recipient fan-out: leaverRequests are built from `students` when invite
+     * emails fire, so the cohort is always resolved against the live roster. */
+    autoProvisioned?: boolean,
+
     /** Post-leaving checkpoint schedule. Absent = checkpoints disabled for this group. */
     checkpointConfig?: {
         resultsDay?: {enabled: boolean, sendAt: string, emailTemplateId?: string},   // ISO datetime