placementt-core 1.400.1093 → 1.400.1094

package/lib/typeDefinitions.d.ts

@@ -1347,6 +1347,14 @@ export type InstituteData = {
         };
     };
     cs?: CustomerSuccessData;
+    /** Engagement email state: the weekly cap shared by onboarding nudges and
+     * feature marketing, and where each engine has got to. Written only by
+     * the engagement cron (Placementt-Backend featureEngagement.ts). */
+    engagement?: InstituteEngagement;
+    /** The last engagement email, for the dashboard to show the same message
+     * as a popup. Overwritten on every send; the web app writes `clickedAt`
+     * and `declinedAt` back, and the cron reads them to steer campaigns. */
+    engagementPrompt?: EngagementPrompt;
     /** The ONS region the school sits in, as an ASHE Table 15 region code
      * ("E12000008" for the South East). Set by an admin; nothing derives it
      * from the address. When present, the careers library adds a "pay near
@@ -4304,6 +4312,79 @@ export type CustomerSuccessData = {
     };
     metrics?: CustomerSuccessMetrics;
 };
+export type InstituteEngagement = {
+    /** Last engagement email of any kind, for the one-per-week cap. */
+    lastEmailAt?: string;
+    onboarding?: {
+        /** The step last nudged, so the same step is not sent twice in a row
+         * without a change (the cron caps repeats of one step). */
+        lastStepKey?: string;
+        lastVariant?: "setup" | "resend";
+        lastSentAt?: string;
+        /** How many times in a row the same step has been sent. */
+        repeats?: number;
+    };
+    marketing?: {
+        activeCampaignId?: string;
+        cooldownUntil?: string;
+        consecutiveIgnored?: number;
+        /** Feature key → ISO date the suppression lifts. */
+        suppressed?: {
+            [featureKey: string]: string;
+        };
+    };
+};
+export type EngagementPrompt = {
+    /** `${kind}:${key}:${variant|touch}:${YYYY-MM-DD}` */
+    id: string;
+    kind: "marketing" | "onboarding";
+    /** FeatureMarketingKey or OnboardingStep.key */
+    key: string;
+    /** Onboarding only. */
+    variant?: "setup" | "resend";
+    /** Marketing only, 0-based. */
+    touch?: number;
+    label: string;
+    description: string;
+    path: string;
+    sentAt: string;
+    /** Written by the web app. */
+    clickedAt?: string;
+    /** Written by the web app, marketing only. */
+    declinedAt?: string;
+};
+/** `featureCampaigns/{oId}_{featureKey}_{academicYear}` */
+export type FeatureCampaign = {
+    oId: string;
+    featureKey: string;
+    /** "2026-27" */
+    academicYear: string;
+    status: "active" | "adopted" | "declined" | "expired";
+    startedAt: string;
+    touchesSent: {
+        touch: number;
+        templateId: number;
+        sentAt: string;
+        recipients: string[];
+    }[];
+    clickedAt?: string;
+    declinedAt?: string;
+    adoptedAt?: string;
+    endedAt?: string;
+};
+/** `engagementEmails/{autoId}`: one flat log document per send, for the
+ * admin view. */
+export type EngagementEmailLog = {
+    oId: string;
+    kind: "marketing" | "onboarding";
+    key: string;
+    variant?: "setup" | "resend";
+    touch?: number;
+    templateId: number;
+    recipients: string[];
+    sentAt: string;
+    campaignId?: string;
+};
 export type CustomerTask = {
     id: string;
     customerId: string;

package/lib/typeDefinitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"typeDefinitions.js","sourceRoot":"","sources":["../src/typeDefinitions.ts"],"names":[],"mappings":";;;AAkqIA,sDASC;AAeD,oDAKC;AAaD,0CAEC;AAnoED;;;;;kFAKkF;AACrE,QAAA,qBAAqB,GAAG,SAAS,CAAC;AAClC,QAAA,iBAAiB,GAAG,OAAO,CAAC;AA+iEzC;yEACyE;AAC5D,QAAA,0BAA0B,GAA2C;IAC9E,gBAAgB,EAAE,2BAA2B;IAC7C,mBAAmB,EAAE,sBAAsB;IAC3C,cAAc,EAAE,iBAAiB;IACjC,kBAAkB,EAAE,qBAAqB;IACzC,UAAU,EAAE,oCAAoC;IAChD,aAAa,EAAE,yBAAyB;IACxC,aAAa,EAAE,wBAAwB;IACvC,KAAK,EAAE,OAAO;CACjB,CAAC;AAEW,QAAA,0BAA0B,GAA+C;IAClF,QAAQ,EAAE,WAAW;IACrB,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,OAAO;CACjB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,SAAgB,qBAAqB,CAAC,SAAsC;IACxE,QAAQ,SAAS,EAAE,CAAC;QACpB,KAAK,MAAM,CAAC,CAAC,OAAO,OAAO,CAAC;QAC5B,KAAK,OAAO,CAAC,CAAC,OAAO,OAAO,CAAC;QAC7B,KAAK,WAAW,CAAC;QACjB,KAAK,OAAO,CAAC;QACb,KAAK,OAAO,CAAC;QACb,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC;IAC3B,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAChC,IAAwC,EACxC,MAA6C;IAE7C,OAAO,IAAI,EAAE,WAAW,IAAI,MAAM,EAAE,YAAY,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,KAA6D;IACzF,OAAO,GAAG,KAAK,CAAC,cAAc,IAAI,EAAE,IAAI,KAAK,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;AAC/E,CAAC"}
+{"version":3,"file":"typeDefinitions.js","sourceRoot":"","sources":["../src/typeDefinitions.ts"],"names":[],"mappings":";;;AA0qIA,sDASC;AAeD,oDAKC;AAaD,0CAEC;AAnoED;;;;;kFAKkF;AACrE,QAAA,qBAAqB,GAAG,SAAS,CAAC;AAClC,QAAA,iBAAiB,GAAG,OAAO,CAAC;AA+iEzC;yEACyE;AAC5D,QAAA,0BAA0B,GAA2C;IAC9E,gBAAgB,EAAE,2BAA2B;IAC7C,mBAAmB,EAAE,sBAAsB;IAC3C,cAAc,EAAE,iBAAiB;IACjC,kBAAkB,EAAE,qBAAqB;IACzC,UAAU,EAAE,oCAAoC;IAChD,aAAa,EAAE,yBAAyB;IACxC,aAAa,EAAE,wBAAwB;IACvC,KAAK,EAAE,OAAO;CACjB,CAAC;AAEW,QAAA,0BAA0B,GAA+C;IAClF,QAAQ,EAAE,WAAW;IACrB,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,OAAO;CACjB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,SAAgB,qBAAqB,CAAC,SAAsC;IACxE,QAAQ,SAAS,EAAE,CAAC;QACpB,KAAK,MAAM,CAAC,CAAC,OAAO,OAAO,CAAC;QAC5B,KAAK,OAAO,CAAC,CAAC,OAAO,OAAO,CAAC;QAC7B,KAAK,WAAW,CAAC;QACjB,KAAK,OAAO,CAAC;QACb,KAAK,OAAO,CAAC;QACb,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC;IAC3B,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAChC,IAAwC,EACxC,MAA6C;IAE7C,OAAO,IAAI,EAAE,WAAW,IAAI,MAAM,EAAE,YAAY,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,KAA6D;IACzF,OAAO,GAAG,KAAK,CAAC,cAAc,IAAI,EAAE,IAAI,KAAK,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;AAC/E,CAAC"}

package/package.json

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

package/src/typeDefinitions.ts

@@ -1381,6 +1381,14 @@ export type InstituteData = {
         }
     },
     cs?: CustomerSuccessData,
+    /** Engagement email state: the weekly cap shared by onboarding nudges and
+     * feature marketing, and where each engine has got to. Written only by
+     * the engagement cron (Placementt-Backend featureEngagement.ts). */
+    engagement?: InstituteEngagement,
+    /** The last engagement email, for the dashboard to show the same message
+     * as a popup. Overwritten on every send; the web app writes `clickedAt`
+     * and `declinedAt` back, and the cron reads them to steer campaigns. */
+    engagementPrompt?: EngagementPrompt,
     /** The ONS region the school sits in, as an ASHE Table 15 region code
      * ("E12000008" for the South East). Set by an admin; nothing derives it
      * from the address. When present, the careers library adds a "pay near
@@ -4456,6 +4464,80 @@ export type CustomerSuccessData = {
     metrics?: CustomerSuccessMetrics;
 };
 
+// ─── Engagement emails ───────────────────────────────────────────────────────
+// Onboarding nudges and feature marketing (onboardingPathways.ts and
+// featureMarketing.ts decide what to say; the backend cron decides when).
+
+export type InstituteEngagement = {
+    /** Last engagement email of any kind, for the one-per-week cap. */
+    lastEmailAt?: string,
+    onboarding?: {
+        /** The step last nudged, so the same step is not sent twice in a row
+         * without a change (the cron caps repeats of one step). */
+        lastStepKey?: string,
+        lastVariant?: "setup"|"resend",
+        lastSentAt?: string,
+        /** How many times in a row the same step has been sent. */
+        repeats?: number,
+    },
+    marketing?: {
+        activeCampaignId?: string,
+        cooldownUntil?: string,
+        consecutiveIgnored?: number,
+        /** Feature key → ISO date the suppression lifts. */
+        suppressed?: {[featureKey: string]: string},
+    },
+};
+
+export type EngagementPrompt = {
+    /** `${kind}:${key}:${variant|touch}:${YYYY-MM-DD}` */
+    id: string,
+    kind: "marketing"|"onboarding",
+    /** FeatureMarketingKey or OnboardingStep.key */
+    key: string,
+    /** Onboarding only. */
+    variant?: "setup"|"resend",
+    /** Marketing only, 0-based. */
+    touch?: number,
+    label: string,
+    description: string,
+    path: string,
+    sentAt: string,
+    /** Written by the web app. */
+    clickedAt?: string,
+    /** Written by the web app, marketing only. */
+    declinedAt?: string,
+};
+
+/** `featureCampaigns/{oId}_{featureKey}_{academicYear}` */
+export type FeatureCampaign = {
+    oId: string,
+    featureKey: string,
+    /** "2026-27" */
+    academicYear: string,
+    status: "active"|"adopted"|"declined"|"expired",
+    startedAt: string,
+    touchesSent: {touch: number, templateId: number, sentAt: string, recipients: string[]}[],
+    clickedAt?: string,
+    declinedAt?: string,
+    adoptedAt?: string,
+    endedAt?: string,
+};
+
+/** `engagementEmails/{autoId}`: one flat log document per send, for the
+ * admin view. */
+export type EngagementEmailLog = {
+    oId: string,
+    kind: "marketing"|"onboarding",
+    key: string,
+    variant?: "setup"|"resend",
+    touch?: number,
+    templateId: number,
+    recipients: string[],
+    sentAt: string,
+    campaignId?: string,
+};
+
 export type CustomerTask = {
     id: string;
     customerId: string;