placementt-core 1.400.1237 → 1.400.1239

package/src/onboardingPathways.ts

@@ -2,7 +2,7 @@ import {InstituteData} from "./typeDefinitions";
 import {ResolvedProducts} from "./productResolver";
 import {SurveyGroupScope} from "./surveys/types";
 import {activityLoggingState} from "./activityLogging";
-import {BREVO_TEMPLATE_UNSET, FEATURE_MARKETING_BY_KEY, FeatureMarketingCounts, FeatureMarketingKey, askForEngagementPlan, featurePlanStatus, isSelfServeSignUp} from "./featureMarketing";
+import {FEATURE_MARKETING_BY_KEY, FeatureMarketingCounts, FeatureMarketingKey, askForEngagementPlan, featurePlanStatus, isSelfServeSignUp} from "./featureMarketing";
 import {hasWondeConnection} from "./studentData";
 
 /**
@@ -46,19 +46,13 @@ export const ONBOARDING_PATHWAY_KEYS: OnboardingPathwayKey[] = [
  * were onboarded by hand and get the plan board on their homepage instead. */
 export const JOIN_WINDOW_DAYS = 60;
 
-/** Days after a step's first email that its second and third go. The second
- * is shorter with an offer of a call, the third asks whether now is the right
- * time and carries the "pick a different term" link. */
-export const ONBOARDING_EMAIL_DAYS = [0, 7, 21];
-
-/** The shared second and third emails, the same for every step with the
- * step's name and link filled in. Unset falls back to the step's own template.
- *
- * Template ids from here on are labels for emails written in the backend
- * (awsSES/templates/engagement.ts), in the 9000s to stay clear of Brevo's. */
-export const ONBOARDING_REMINDER_TEMPLATE_IDS: {second: number, third: number} = {
-    second: 9090,
-    third: 9091,
+/** The shared reminders in a step email's weekly reminder chain
+ * (sendEmailReminders): the first and third, with the step's name and link
+ * filled in. The second resends the step's own email. A step on the plan
+ * board gets the version with a "pick a different term" link. */
+export const ONBOARDING_REMINDER_TEMPLATES = {
+    first: {plain: "engagementReminderDay7", plan: "engagementReminderDay7Plan"},
+    third: {plain: "engagementReminderDay21", plan: "engagementReminderDay21Plan"},
 };
 
 /** Everything marketing reads, plus the counts that only onboarding asks for. */
@@ -102,9 +96,10 @@ export type OnboardingStep = {
     /** Built for the current academic year. Absent on a once-only step. Only
      * consulted once `done` is true, so it need not repeat that check. */
     thisYear?: (ctx: OnboardingContext) => boolean,
-    /** Brevo template ids by email variant. `resend` is only read on steps
-     * with `thisYear`. `BREVO_TEMPLATE_UNSET` means not made yet: skip. */
-    templateIds: {setup: number, resend?: number},
+    /** The admin email template (constants.ts emailTemplates) for each email
+     * variant. `resend` is only read on steps with `thisYear`. Absent means no
+     * email has been written for the step yet. */
+    emailTemplates?: {setup: string, resend?: string},
     /** The feature on the school's plan board this step sets up, when it is
      * not the pathway's. Nothing is sent about it before its planned term. */
     feature?: FeatureMarketingKey,
@@ -159,7 +154,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Pick Your Features",
                 description: "Choose what you'll use CareerThread for, and we'll set your account up around it.",
                 path: "/home",
-                templateIds: {setup: 9001},
+                emailTemplates: {setup: "engagementPickFeatures"},
                 needs: ["students"],
                 optional: true,
                 // Accounts from before the picker that already have students are past this.
@@ -170,7 +165,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Plan Your Year",
                 description: "Drag each feature into the term you want to set it up in. We won't email about anything before then.",
                 path: "/organisation/overview",
-                templateIds: {setup: 9002},
+                emailTemplates: {setup: "engagementPlanYear"},
                 needs: [],
                 optional: true,
                 // Asked once; a plan saved in any year counts.
@@ -182,7 +177,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Invite Your Staff",
                 description: "Give the rest of the careers team their own logins so the work is shared.",
                 path: "/organisation/staff",
-                templateIds: {setup: 9003},
+                emailTemplates: {setup: "engagementInviteStaff"},
                 needs: ["staff"],
                 emails: 1,
                 optional: true,
@@ -200,7 +195,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Choose How to Add Your Students",
                 description: "Connect through Wonde, send us a file from your MIS, or upload a spreadsheet. Pick one and we'll send what you need.",
                 path: "/students",
-                templateIds: {setup: 9010},
+                emailTemplates: {setup: "engagementStudentRoute"},
                 needs: ["students"],
                 // A trust and a hub hold no students of their own; their
                 // first step is linking the schools that do.
@@ -212,7 +207,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Approve the Wonde Connection",
                 description: "Approve CareerThread in your Wonde portal and your students sync automatically.",
                 path: "/students",
-                templateIds: {setup: 9011},
+                emailTemplates: {setup: "engagementWonde"},
                 needs: ["students"],
                 applies: studentRouteIs("wonde"),
                 done: (ctx) => hasStudents(ctx) || hasWondeConnection(ctx.institute),
@@ -222,7 +217,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up Your MIS File Transfer",
                 description: "Schedule an export from your MIS to us and your students stay up to date.",
                 path: "/students",
-                templateIds: {setup: 9012},
+                emailTemplates: {setup: "engagementMis"},
                 needs: ["students"],
                 applies: studentRouteIs("mis"),
                 done: hasStudents,
@@ -232,7 +227,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Add Your Students",
                 description: "Upload a spreadsheet of your students and every student gets an account.",
                 path: "/students",
-                templateIds: {setup: 9013},
+                emailTemplates: {setup: "engagementUploadStudents"},
                 needs: ["students"],
                 applies: studentRouteIs("csv"),
                 done: hasStudents,
@@ -249,7 +244,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Link Your Schools",
                 description: "Invite trust schools to CareerThread, to contribute to their careers provision.",
                 path: "/schools",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["schools"],
                 done: ({counts}) => (counts.schools || 0) > 0,
             },
@@ -265,7 +259,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Add Your Schools",
                 description: "Invite the schools in your area and they appear on your hub.",
                 path: "/schools",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["schools"],
                 done: ({counts}) => (counts.schools || 0) > 0,
             },
@@ -274,7 +267,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Add Your Employers",
                 description: "Import the employers you already work with.",
                 path: "/network",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["employers"],
                 done: ({counts}) => (counts.employers || 0) > 0,
             },
@@ -283,7 +275,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Enable Your Public Events Page",
                 description: "Let employers find and sign up to your events themselves.",
                 path: "/network/overview#employerSettings",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: [],
                 done: ({institute}) => Boolean(institute.publicEventPage),
             },
@@ -292,7 +283,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Send Your First Email Campaign",
                 description: "Reach every employer on the hub in one go.",
                 path: "/network/emailCampaigns",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["emailCampaigns"],
                 done: ({counts}) => (counts.emailCampaigns || 0) > 0,
             },
@@ -301,7 +291,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Create Your First Event",
                 description: "Invite schools and employers and track who turns up.",
                 path: "/events",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["events"],
                 done: marketingAdopted("events"),
             },
@@ -320,7 +309,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Request Your First Event",
                 description: "Pick the kind of employers you want and we handle the invites.",
                 path: "/events",
-                templateIds: {setup: 9030},
+                emailTemplates: {setup: "engagementHubFirstEvent"},
                 needs: ["events"],
                 done: ({counts}) => (counts.events || 0) > 0,
             },
@@ -337,7 +326,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up a Work Experience Group",
                 description: "Create a recurring group and we'll make the cohort every year.",
                 path: "/cohorts",
-                templateIds: {setup: 9020, resend: 9021},
+                emailTemplates: {setup: "engagementWexGroups", resend: "engagementWexCohort"},
                 needs: ["cohorts", "cohortsThisYear"],
                 done: marketingAdopted("wexCohort"),
                 thisYear: ({counts}) => (counts.cohortsThisYear || 0) > 0,
@@ -347,7 +336,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Build a Sign-Off Workflow",
                 description: "Decide who signs off each placement, in what order, and which forms they see.",
                 path: "/cohorts",
-                templateIds: {setup: 9022},
+                emailTemplates: {setup: "engagementWexWorkflow"},
                 needs: [],
                 done: ({institute}) =>
                     Object.values(institute.cohortConfig || {}).some((g) => Boolean(g.workflowId)),
@@ -357,7 +346,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Activate Your Students",
                 description: "Send them their logins and they can start adding placements.",
                 path: "/students",
-                templateIds: {setup: 9023},
+                emailTemplates: {setup: "engagementWexActivate"},
                 needs: ["activatedStudents"],
                 done: ({counts}) => (counts.activatedStudents || 0) > 0,
             },
@@ -366,7 +355,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Add Your First Placements",
                 description: "Students or staff add placements and the sign-off workflow takes it from there.",
                 path: "/cohorts",
-                templateIds: {setup: 9024},
+                emailTemplates: {setup: "engagementWexPlacements"},
                 needs: ["placements"],
                 done: ({counts}) => (counts.placements || 0) > 0,
             },
@@ -375,7 +364,7 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up Placement Feedback",
                 description: "Ask students and employers how it went, automatically, when each placement ends.",
                 path: "/cohorts",
-                templateIds: {setup: 9025},
+                emailTemplates: {setup: "engagementWexFeedback"},
                 needs: [],
                 done: ({institute}) =>
                     Object.values(institute.cohortConfig || {}).some((g) => Boolean(g.feedback)),
@@ -418,7 +407,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Import Your Employers",
                 description: "Bring in the employers you already work with, so your first event has people to invite.",
                 path: "/network",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["employers"],
                 done: ({counts}) => (counts.employers || 0) > 0,
             },
@@ -427,7 +415,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Open Your Employer Page",
                 description: "Let employers sign up to your network and see your events themselves.",
                 path: "/network/overview#employerSettings",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: [],
                 optional: true,
                 done: ({institute}) => Boolean(institute.publicEventPage),
@@ -437,7 +424,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Create Your First Event",
                 description: "Invite students, staff and employers and we'll track invites and attendance.",
                 path: "/events",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["events"],
                 done: marketingAdopted("events"),
             },
@@ -446,7 +432,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Invite Employers to an Event",
                 description: "Pick them from your network by sector and we chase the replies.",
                 path: "/events",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["eventAttendees"],
                 done: ({counts}) => (counts.eventAttendees || 0) > 0,
             },
@@ -471,7 +456,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up Career Aspiration Surveys",
                 description: "What students want to do next, asked every year and compared with where they go.",
                 path: "/destinations",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET, resend: BREVO_TEMPLATE_UNSET},
                 needs: ["surveyScopesThisYear"],
                 done: marketingAdopted("aspirations"),
                 thisYear: hasScope("aspirations"),
@@ -482,7 +466,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up Leaver Tracking",
                 description: "Intentions in spring, destinations in autumn, for every year that leaves.",
                 path: "/destinations/leavers",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET, resend: BREVO_TEMPLATE_UNSET},
                 needs: ["surveyScopesThisYear"],
                 done: marketingAdopted("leavers"),
                 thisYear: hasScope("leavers"),
@@ -493,7 +476,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Add Your Alumni",
                 description: "Import the leavers you're in touch with, or let this year's leavers opt in.",
                 path: "/network/alumni",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["alumni"],
                 applies: ({products}) => products.alumni,
                 done: marketingAdopted("alumni"),
@@ -511,7 +493,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up Skills Tracking",
                 description: "Choose the skills you assess and when, and the surveys go out on schedule.",
                 path: "/development/assessments",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET, resend: BREVO_TEMPLATE_UNSET},
                 needs: ["surveyScopesThisYear"],
                 done: marketingAdopted("skills"),
                 thisYear: hasScope("skills"),
@@ -522,7 +503,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Set Up 1:1 Careers Guidance",
                 description: "Schedule guidance meetings per year group and record them for Gatsby.",
                 path: "/development/guidance",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET, resend: BREVO_TEMPLATE_UNSET},
                 needs: ["surveyScopesThisYear"],
                 done: marketingAdopted("guidance"),
                 thisYear: hasScope("guidance"),
@@ -540,7 +520,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Launch It to a Year Group",
                 description: "Nothing is shown to a student until you say which years have been told.",
                 path: "/development/activities",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET, resend: BREVO_TEMPLATE_UNSET},
                 needs: [],
                 // A launch is made for one academic year unless the school said
                 // it rolls over, so last year's is set up but not this year's. Setup
@@ -561,7 +540,6 @@ export const ONBOARDING_PATHWAYS: OnboardingPathway[] = [
                 label: "Invite Your Parents",
                 description: "Write the invitation, upload the list, and the database builds from the replies.",
                 path: "/network/parents",
-                templateIds: {setup: BREVO_TEMPLATE_UNSET},
                 needs: ["parents"],
                 done: marketingAdopted("parents"),
             },
@@ -600,9 +578,8 @@ export type OnboardingStepProgress = {
     done: boolean,
     /** Which email this step would get, were it the one sent. */
     variant: OnboardingEmailVariant,
-    /** The Brevo template for that variant. `BREVO_TEMPLATE_UNSET` when it
-     * has not been made yet, in which case nothing is sent. */
-    templateId: number,
+    /** The admin email template for that variant, when one has been written. */
+    emailTemplate?: string,
     /** The plan board feature it sets up: its own, or its pathway's. */
     feature?: FeatureMarketingKey,
     /** How many emails it gets before it counts as passed or stuck. */
@@ -650,7 +627,7 @@ export const evaluateOnboarding = (ctx: OnboardingContext): OnboardingPathwayPro
                 state,
                 done: state === "done",
                 variant,
-                templateId: s.templateIds[variant] ?? BREVO_TEMPLATE_UNSET,
+                emailTemplate: s.emailTemplates?.[variant],
                 feature: s.feature ?? p.feature,
                 emails: s.emails ?? 3,
                 optional: Boolean(s.optional),
@@ -729,3 +706,35 @@ export const planFeatureOf = (kind: "marketing"|"onboarding"|"renewal", key: str
     const pathway = ONBOARDING_PATHWAYS.find((p) => p.steps.some((s) => s.key === key));
     return pathway?.steps.find((s) => s.key === key)?.feature ?? pathway?.feature;
 };
+
+/**
+ * Whether one step is done, judged on its own: an email sent by hand may be
+ * about a step that doesn't apply to the school (the Wonde email to a school
+ * on the spreadsheet route), so `applies` is not consulted. A step with
+ * `thisYear` is done once it is built for this year, and an optional step
+ * once it has been passed.
+ *
+ * @param {OnboardingContext} ctx the institute, its products and counts.
+ * @param {string} stepKey the step.
+ * @return {boolean|undefined} whether it is done, or undefined for an unknown step.
+ */
+export const onboardingStepDone = (ctx: OnboardingContext, stepKey: string): boolean|undefined => {
+    const step = ONBOARDING_PATHWAYS.flatMap((p) => p.steps).find((s) => s.key === stepKey);
+    if (!step) return undefined;
+    if (step.optional && ctx.institute.engagement?.onboarding?.passed?.[step.key]) return true;
+    return step.done(ctx) && (!step.thisYear || step.thisYear(ctx));
+};
+
+/**
+ * The step an admin email template is the email for.
+ *
+ * @param {string} templateKey the email template.
+ * @return {object|undefined} the step and its plan board feature.
+ */
+export const onboardingStepOfTemplate = (templateKey: string): {step: OnboardingStep, feature?: FeatureMarketingKey}|undefined => {
+    for (const pathway of ONBOARDING_PATHWAYS) {
+        const step = pathway.steps.find((s) => s.emailTemplates?.setup === templateKey || s.emailTemplates?.resend === templateKey);
+        if (step) return {step, feature: step.feature ?? pathway.feature};
+    }
+    return undefined;
+};

package/src/renewals.test.ts

@@ -3,7 +3,7 @@ jest.mock("./firebase/firebaseQuery", () => ({__esModule: true, default: class {
 
 import {InstituteData} from "./typeDefinitions";
 import {resolveProducts} from "./productResolver";
-import {RenewalStep, renewalSituation} from "./renewals";
+import {RenewalStep, renewalSituation, renewalTaskSchedule} from "./renewals";
 
 const school = (renewalDate?: string, overrides: Partial<InstituteData> = {}): InstituteData => ({
     name: "Calder Park Academy",
@@ -61,3 +61,23 @@ describe("renewals", () => {
         expect(at(thanked, "2026-11-10").due).toBeUndefined();
     });
 });
+
+describe("renewalTaskSchedule", () => {
+    it("dates each renewal task from the renewal date", () => {
+        expect(renewalTaskSchedule("2027-10-01", "2026-11-03")).toEqual([
+            {step: "headsUp", due: "2027-04-20"},
+            {step: "yearInReview", due: "2027-07-01"},
+            {step: "sixtyDay", due: "2027-08-02"},
+            {step: "thirtyDay", due: "2027-09-01"},
+            {step: "lapsed", due: "2027-10-02"},
+        ]);
+    });
+
+    it("keeps only the step a late date is in, of the ones already gone", () => {
+        expect(renewalTaskSchedule("2026-12-15", "2026-11-03").map((t) => t.step)).toEqual(["sixtyDay", "thirtyDay", "lapsed"]);
+    });
+
+    it("leaves out a heads-up or year in review more than a year before the 60-day email", () => {
+        expect(renewalTaskSchedule("2027-06-01", "2026-11-03").map((t) => t.step)).toEqual(["yearInReview", "sixtyDay", "thirtyDay", "lapsed"]);
+    });
+});

package/src/renewals.ts

@@ -8,9 +8,8 @@ import {londonYmd} from "./outreachRules";
  * Renewal is commercial and per customer, so it is kept apart from
  * re-onboarding, which is academic and per feature (the September plan board
  * and the "new year" steps). Tom renews every customer himself: each email
- * here is a personal draft from him, approved in the queue, and anything that
- * needs a person (no renewal date, a lapsed date, raising the invoice) is a
- * task for him rather than an email.
+ * here is a task for him, made when the renewal date is set
+ * (renewalTaskSchedule), that he sends from the task with the email in hand.
  *
  * The year runs from `cs.renewalDate`:
  * - headsUp: late April to May, before budgets for next year are set. Next
@@ -44,14 +43,13 @@ export const RENEWAL_STEP_LABELS: Record<RenewalStep, string> = {
 /** Steps that copy in the finance contact as well as the school's contacts. */
 export const RENEWAL_FINANCE_STEPS: RenewalStep[] = ["headsUp", "sixtyDay", "thirtyDay"];
 
-/** Brevo-style ids for the renewal emails, written in the backend
- * (awsSES/templates/engagement.ts) like the onboarding ones. */
-export const RENEWAL_TEMPLATE_IDS: Record<RenewalStep, number> = {
-    headsUp: 9101,
-    yearInReview: 9102,
-    sixtyDay: 9103,
-    thirtyDay: 9104,
-    thanks: 9105,
+/** The admin email template (constants.ts emailTemplates) for each step. */
+export const RENEWAL_EMAIL_TEMPLATES: Record<RenewalStep, string> = {
+    headsUp: "engagementRenewalPrice",
+    yearInReview: "engagementRenewalReview",
+    sixtyDay: "engagementRenewalDue",
+    thirtyDay: "engagementRenewalInvoice",
+    thanks: "engagementRenewalThanks",
 };
 
 export type RenewalSituation = {
@@ -136,3 +134,39 @@ export const renewalSituation = ({institute, products, now}: {institute: Institu
     }
     return {...base, lapsed: false, stage: "early"};
 };
+
+
+const addDays = (ymd: string, days: number): string => new Date(ymdToMs(ymd) + days * DAY_MS).toISOString().slice(0, 10);
+
+/**
+ * The renewal tasks for one renewal date, each with the day it is due: the
+ * same timings as renewalSituation, worked out once when the date is set
+ * rather than checked daily. The heads-up is the last 20 April and the year
+ * in review the last 1 July that fall within the year before the 60-day
+ * email. A date set late skips the steps already gone, but keeps the most
+ * recent one, since that's the step the customer is in. The thanks is not
+ * here: it is due when the date moves on.
+ *
+ * @param {string} renewalDate YYYY-MM-DD.
+ * @param {string} today YYYY-MM-DD, London.
+ * @return {object[]} each step and its due date, plus "lapsed" the day after renewal.
+ */
+export const renewalTaskSchedule = (renewalDate: string, today: string): {step: Exclude<RenewalStep, "thanks">|"lapsed", due: string}[] => {
+    const sixty = addDays(renewalDate, -60);
+    const yearBefore = addDays(renewalDate, -365);
+    const lastBefore = (md: string) => {
+        const year = Number(sixty.slice(0, 4));
+        const candidate = `${year}-${md}` < sixty ? `${year}-${md}` : `${year - 1}-${md}`;
+        return candidate >= yearBefore ? candidate : undefined;
+    };
+    const all = ([
+        {step: "headsUp", due: lastBefore("04-20")},
+        {step: "yearInReview", due: lastBefore("07-01")},
+        {step: "sixtyDay", due: sixty},
+        {step: "thirtyDay", due: addDays(renewalDate, -30)},
+    ] as {step: Exclude<RenewalStep, "thanks">, due?: string}[])
+        .filter((t): t is {step: Exclude<RenewalStep, "thanks">, due: string} => Boolean(t.due))
+        .sort((a, b) => a.due.localeCompare(b.due));
+    const gone = all.filter((t) => t.due < today);
+    return [...all.filter((t) => t.due >= today || t === gone[gone.length - 1]), {step: "lapsed", due: addDays(renewalDate, 1)}];
+};

package/src/typeDefinitions.ts

@@ -2012,7 +2012,7 @@ export type EmailTemplateConfig = {
         button?: {text: string, link: string},
         secondaryButton?: {text: string, link: string},
         optionalButtons?: {text: string, link: string}[],
-        type: "workflow"|"feedback"|"event"|"campaign"|"database"|"onboarding"|"skillsInvite"|"aspirationInvite"|"leaverInvite"|"leaverResultsInvite"|"leaverChristmasInvite",
+        type: "workflow"|"feedback"|"event"|"campaign"|"database"|"onboarding"|"skillsInvite"|"aspirationInvite"|"leaverInvite"|"leaverResultsInvite"|"leaverChristmasInvite"|"engagement",
         product: EmailTemplateProduct,
         sections?: EmailSectionNames[],
         group?: string, // Templates sharing a group are listed together, e.g. the three feedback requests.
@@ -2027,7 +2027,8 @@ export type EmailTemplateConfig = {
 // Which product a resource (email template, guidance doc, default form) belongs to, so customers only see resources for products they have.
 // Any ProductKey from the product resolver, "employerEvents" for the events container itself, or "hub" for careers hub only.
 export type ProductTag = ProductKey|"employerEvents"|"hub";
-export type EmailTemplateProduct = ProductTag;
+// "admin": CareerThread's own emails to customers (onboarding, renewals), only selectable by us.
+export type EmailTemplateProduct = ProductTag|"admin";
 
 export type EmailCampaign = {
     id: string,
@@ -3812,6 +3813,7 @@ export type YearScoreData = {
 
 type MessageTypes =
     "hubOrTrustInviteSchool" |
+    "engagementEmail" | // an admin email template sent to a school (featureEngagement.ts)
     "sendPlacementActionRequired" |
     "sendPlacementAdditionalInformationRequired" |
     "sendFeedbackReminder" |
@@ -3862,7 +3864,8 @@ export type SurveyMessageType =
 export type ReminderFallbackType =
     "checkInTrustedContact" | // legacy name for the below; live interaction docs still carry it
     "surveyParentFallback" | // chase the parent/trusted contact when the subject ignores their whole chain
-    "alumniCheckInFallback"; // the same, for the annual alumni check-in, which is not a survey
+    "alumniCheckInFallback" | // the same, for the annual alumni check-in, which is not a survey
+    "engagementStuck"; // an onboarding email's reminders ran out with the step still not done
 
 export type EmailInteraction = {
     messageId: string,
@@ -4637,20 +4640,11 @@ export type CustomerSuccessData = {
 };
 
 // ─── Engagement emails ───────────────────────────────────────────────────────
-// Onboarding nudges and feature marketing (onboardingPathways.ts and
-// featureMarketing.ts decide what to say; the backend cron decides when).
+// Onboarding and renewal emails, sent by an admin (onboardingPathways.ts and
+// renewals.ts say which; the emails are admin email templates).
 
 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,
         /** Optional steps whose emails ran out unanswered, keyed by step, with
          * the date. They count as done so the next step can start. */
         passed?: {[stepKey: string]: string},
@@ -4709,22 +4703,6 @@ export type FeatureCampaign = {
     endedAt?: string,
 };
 
-/** `engagementEmails/{autoId}`: one flat log document per send, for the
- * admin view. */
-export type EngagementEmailLog = {
-    oId: string,
-    kind: "marketing"|"onboarding"|"renewal",
-    key: string,
-    variant?: "setup"|"resend",
-    touch?: number,
-    templateId: number,
-    recipients: string[],
-    sentAt: string,
-    campaignId?: string,
-    /** The approved draft it was sent from. */
-    draftId?: string,
-};
-
 export type StudentRoute = {
     route: "wonde"|"mis"|"csv",
     chosenAt: string,
@@ -4749,46 +4727,6 @@ export type EngagementPlan = {
     savedBy: string,
 };
 
-/** Where an engagement email is in its approval: written as a draft, approved
- * by an admin for the next school morning, then sent; or skipped by an admin,
- * expired unapproved, or dropped because the school did the step first. */
-export type EngagementDraftStatus = "draft"|"approved"|"sent"|"skipped"|"expired"|"dropped";
-
-/** `engagementDrafts/{autoId}`: one engagement email to one institute. The
- * daily check writes every email as one of these and nothing sends until an
- * admin approves it. */
-export type EngagementDraft = {
-    oId: string,
-    instituteName: string,
-    kind: "marketing"|"onboarding"|"renewal",
-    key: string,
-    variant?: "setup"|"resend",
-    touch?: number,
-    templateId: number,
-    label: string,
-    description: string,
-    path: string,
-    campaignId?: string,
-    /** Onboarding: `engagement.onboarding.repeats` once this is sent. */
-    repeats?: number,
-    recipients: {email: string, forename: string, surname: string}[],
-    /** Drafts with the same template and step, approved together. */
-    batchKey: string,
-    status: EngagementDraftStatus,
-    createdAt: string,
-    approvedAt?: string,
-    approvedBy?: string,
-    /** 7:30am London on the school day after approval. */
-    sendAt?: string,
-    sentAt?: string,
-    sentTo?: string[],
-    /** When it was skipped, expired or dropped, and why. */
-    closedAt?: string,
-    closedReason?: string,
-    /** An admin changed the description or recipients. */
-    edited?: boolean,
-};
-
 export type CustomerTask = {
     id: string;
     customerId: string;
@@ -4806,6 +4744,8 @@ export type CustomerTask = {
     completedBy?: string;
     triggerType: "manual" | "renewalLogged" | "timeBased" | "metricThreshold" | "calendar";
     triggerKey?: string;
+    /** The admin email template (constants.ts emailTemplates) this task sends, from the task. */
+    emailTemplate?: string;
     commId?: string;
     commType?: "users";
     metadata?: {