placementt-core 1.400.1235 → 1.400.1237

package/src/callables/events.ts

@@ -92,6 +92,73 @@ export const eventsCallables = {
     // Public, same credential as above. The changes an email-only school makes on its invite page.
     // Slot bookings go through events-bookEventSlots and tasks through the same callables employers
     // use (events-submitExternalForm, events-updateFileView, events-uploadRequiredFile).
+    // Public: an event's parent sign-up link. Without eventParentId, the event and the places left, for
+    // a parent signing up (notAccepting once the organiser closes sign-ups or the places run out). With it,
+    // that parent's booking too: the externalEventParents id is the credential, as for non-user schools.
+    // details: {event, eventParent?, organiserName, branding, forms, files, schools (hub events: names of
+    // schools on the event, for the parent to pick), placesLeft: {adults?, children?}}.
+    "events-getParentSignUp": {
+        request: z.object({
+            eventId: z.string().min(1),
+            eventParentId: z.string().min(1).optional(),
+        }),
+        response: z.object({
+            code: z.enum(["found", "notFound", "notAccepting"]),
+            details: z.any().optional(),
+        }),
+    },
+    // Public, same credential. "signUp" makes the externalEventParents doc and emails the parent their
+    // booking link; an email already signed up is emailed its link instead ("emailed"). Tasks are the
+    // event's parentInvites: uploads go to storage at instituteEvents/:oId/:eventId/parent/:eventParentId/:index
+    // first, then "upload" records them.
+    "events-updateParentSignUp": {
+        request: z.discriminatedUnion("action", [
+            z.object({
+                action: z.literal("signUp"),
+                eventId: z.string().min(1),
+                forename: z.string().trim().min(1),
+                surname: z.string().trim().min(1),
+                email: z.string().trim().email(),
+                schoolName: optionalField(z.string().trim()),
+                adults: z.number().int().min(0),
+                children: z.number().int().min(0),
+            }),
+            z.object({
+                action: z.literal("update"),
+                eventParentId: z.string().min(1),
+                adults: z.number().int().min(0),
+                children: z.number().int().min(0),
+                schoolName: optionalField(z.string().trim()),
+            }),
+            z.object({
+                action: z.literal("cancel"),
+                eventParentId: z.string().min(1),
+            }),
+            z.object({
+                action: z.literal("submitForm"),
+                eventParentId: z.string().min(1),
+                formId: z.string().min(1),
+                formData: z.record(z.unknown()),
+            }),
+            z.object({
+                action: z.literal("viewFile"),
+                eventParentId: z.string().min(1),
+                fileId: z.string().min(1),
+            }),
+            z.object({
+                action: z.literal("upload"),
+                eventParentId: z.string().min(1),
+                index: z.number().int().min(0),
+                fileName: z.string().min(1),
+            }),
+        ]),
+        response: z.object({
+            code: z.enum(["updated", "emailed", "full"]),
+            eventParentId: z.string().optional(),
+            // "upload": the uploaded file's download URL.
+            url: z.string().optional(),
+        }),
+    },
     "events-updateNonUserSchoolInvite": {
         request: z.discriminatedUnion("action", [
             z.object({

package/src/invoicing.test.ts

@@ -1,4 +1,4 @@
-import {invoiceYearLabel, addDays, calculateInvoice, discountAmount, invoiceFromQuote} from "./invoicing";
+import {invoiceYearLabel, addDays, calculateInvoice, discountAmount, invoiceFromQuote, isLastYearCohort} from "./invoicing";
 import {instituteQuote} from "./pricing";
 
 /**
@@ -147,3 +147,30 @@ describe("dates", () => {
         expect(addDays("2026-01-30", 3)).toBe("2026-02-02");
     });
 });
+
+describe("isLastYearCohort", () => {
+    const today = new Date("2026-11-03T12:00:00Z");
+
+    it("reads a cohort's academic year in either form", () => {
+        expect(isLastYearCohort({academicYear: "2025/26"}, today)).toBe(true);
+        expect(isLastYearCohort({academicYear: "2025-26"}, today)).toBe(true);
+        expect(isLastYearCohort({academicYear: "2026/27"}, today)).toBe(false);
+    });
+
+    it("falls back to when the placements ended", () => {
+        expect(isLastYearCohort({endPlacements: "2026-07-10"}, today)).toBe(true);
+        expect(isLastYearCohort({endPlacements: "2025-07-10"}, today)).toBe(false);
+        expect(isLastYearCohort({}, today)).toBe(false);
+    });
+});
+
+describe("returning school invoice rows", () => {
+    it("shows the returning discount as the row's own discount", () => {
+        const quote = instituteQuote({products: {wex: true}, students: 800, pricing: {wexY10: 40, returningUnplaced: 10}});
+        const draft = invoiceFromQuote(quote, {instituteName: "Test School", today: new Date("2026-11-03")});
+        const row = draft.lines.find((l) => l.key === "wexY10");
+        expect(row?.description).toContain("10 placements discounted");
+        expect(row?.discount?.type).toBe("amount");
+        expect(calculateInvoice(draft).net).toBeCloseTo(quote.total, 2);
+    });
+});

package/src/invoicing.ts

@@ -192,9 +192,12 @@ export function invoiceFromQuote(
             // was never discounted, and a percentage would take a slice of it.
             const saved = line.undiscounted === undefined ? 0 : round((line.undiscounted - line.amount) * schools);
 
+            const returning = line.returningPlacements ?
+                ` (returning school: ${line.returningPlacements} placement${line.returningPlacements === 1 ? "" : "s"} discounted for students without a placement last year)` : "";
+
             return {
                 key: line.key,
-                description: `${line.label} — CareerThread ${invoiceYearLabel(today)}`,
+                description: `${line.label} — CareerThread ${invoiceYearLabel(today)}${returning}`,
                 quantity: perUnit ? perUnit.quantity : schools,
                 unitAmount: round(perUnit ? perUnit.rate : listPrice),
                 ...(saved > 0 ? {discount: {type: "amount" as const, value: saved}} : {}),
@@ -262,6 +265,14 @@ export type InvoiceRecord = {
     draft?: InvoiceDraft,
     /** Admin uid, when created from the admin panel. */
     createdBy?: string,
+    /** The latest draft emailed to an admin to check, before it went to the customer. */
+    draftSentTo?: string,
+    /** ISO timestamp. */
+    draftSentAt?: string,
+    /** Who the approved invoice was emailed to, by us rather than by Xero. */
+    sentTo?: string,
+    /** ISO timestamp. */
+    sentAt?: string,
     /** ISO timestamps. */
     createdAt: string,
     updatedAt: string,
@@ -274,3 +285,24 @@ export const CUSTOMER_VISIBLE_INVOICE_STATUSES: XeroInvoiceStatus[] = ["AUTHORIS
 
 /** Where the sync keeps its high-water mark. */
 export const BILLING_SYNC_PATH = ["adminConfig", "billingSync"];
+
+/**
+ * Whether a work experience cohort ran in the academic year before `today`'s,
+ * which is the year a returning school's unplaced students are counted from.
+ *
+ * Cohorts made by the recurring set-up carry their academic year ("2025/26");
+ * older ones are placed by when their placements ended.
+ *
+ * @param {object} cohort the cohort's year and placement dates.
+ * @param {Date} [today] the invoice date. Now when absent.
+ * @return {boolean} true for last year's cohorts.
+ */
+export function isLastYearCohort(
+    cohort: {academicYear?: string, endPlacements?: string, startPlacements?: string},
+    today: Date = new Date(),
+): boolean {
+    const lastStart = currentAcademicStartYear(today) - 1;
+    if (cohort.academicYear) return cohort.academicYear.replace("/", "-") === academicYearLabel(lastStart);
+    const ended = (cohort.endPlacements || cohort.startPlacements || "").split("T")[0];
+    return Boolean(ended) && ended >= `${lastStart}-09-01` && ended < `${lastStart + 1}-09-01`;
+}

package/src/pricing.test.ts

@@ -336,3 +336,33 @@ describe("quoteSnapshot", () => {
         expect(snapshot.discountTotal).toBe(0);
     });
 });
+
+describe("returning school discount", () => {
+    const base: SchoolPricingInput = {students: 800, wexY10: 30, wexY12: 10};
+
+    it("charges last year's unplaced students' placements at half their price", () => {
+        const full = calculateSchoolPrice(base);
+        const returning = calculateSchoolPrice({...base, returningUnplaced: 8});
+        const wex = (r: typeof full) => r.lines.filter((l) => l.key.startsWith("wex"));
+
+        const fullY10 = wex(full)[0].amount;
+        const fullY12 = wex(full)[1].amount;
+        // 8 of 40 placements: 6 in Y10, 2 in Y12, each at half its average rate.
+        expect(wex(returning)[0].returningPlacements).toBe(6);
+        expect(wex(returning)[1].returningPlacements).toBe(2);
+        expect(wex(returning)[0].amount).toBeCloseTo(fullY10 - 6 * (fullY10 / 30) * 0.5, 6);
+        expect(wex(returning)[1].amount).toBeCloseTo(fullY12 - 2 * (fullY12 / 10) * 0.5, 6);
+        expect(wex(returning)[0].undiscounted).toBeCloseTo(fullY10, 6);
+    });
+
+    it("never discounts more placements than are quoted", () => {
+        const all = calculateSchoolPrice({...base, returningUnplaced: 500});
+        const wex = all.lines.filter((l) => l.key.startsWith("wex"));
+        expect(wex.reduce((t, l) => t + (l.returningPlacements || 0), 0)).toBe(40);
+    });
+
+    it("does nothing without work experience", () => {
+        const quote = instituteQuote({products: {events: true}, students: 800, pricing: {returningUnplaced: 10}});
+        expect(quote.lines.some((l) => l.returningPlacements)).toBe(false);
+    });
+});

package/src/pricing.ts

@@ -59,6 +59,10 @@ export type PricingConfig = {
     },
     /** Careers hubs are a flat platform fee plus a fee for each school. */
     hub: {baseFee: number, perSchoolFee: number},
+    /** Taken off a returning school's placement fee for each student who was on
+     * work experience last year and didn't get a placement, as a fraction of
+     * that placement's price (0.5 = those placements are half price). */
+    returningUnplacedDiscount: number,
 };
 
 /** The pricing sheet's figures, as agreed for 2026. */
@@ -74,6 +78,7 @@ export const DEFAULT_PRICING_CONFIG: PricingConfig = {
     fullPlatformDiscount: 0.1,
     trust: {threshold: 10, discount: 0.05, largeDiscount: 0.1},
     hub: {baseFee: 2000, perSchoolFee: 150},
+    returningUnplacedDiscount: 0.5,
 };
 
 /** Where the adjustable copy of the config lives. */
@@ -103,6 +108,9 @@ export type SchoolPricingInput = {
     /** A price agreed with the customer, which replaces everything above it —
      * the discounts, the minimum fee and the total the products came to. */
     quoteOverride?: number,
+    /** Students on work experience last year who never got a placement. That
+     * many of this year's placements are charged at the returning discount. */
+    returningUnplaced?: number,
 };
 
 export type PricingLineKey =
@@ -113,8 +121,10 @@ export type PricingLine = {
     label: string,
     /** What the product costs after any partial-product discount. */
     amount: number,
-    /** The fee before its partial-product discount, when one was applied. */
+    /** The fee before its partial-product or returning discount, when one was applied. */
     undiscounted?: number,
+    /** Placements on this line charged at the returning discount. */
+    returningPlacements?: number,
     /** How the amount was reached, band by band. Empty for the base fee. */
     bands: PricingBand[],
 };
@@ -224,6 +234,44 @@ export function trustDiscountRate(
     return count >= config.trust.threshold ? config.trust.largeDiscount : config.trust.discount;
 }
 
+/**
+ * Charge last year's unplaced students' placements at the returning discount.
+ *
+ * A school that paid for students who never got a placement shouldn't pay full
+ * price for them again. Those placements are spread across the year groups in
+ * proportion to each one's placements, and priced at that year group's average
+ * rate per placement, so the graduated bands still decide what a placement is
+ * worth. Never more placements than this year's quote has.
+ *
+ * @param {Array} lines the fees so far; the work experience ones are changed in place.
+ * @param {object} input the quote's inputs.
+ * @param {object} config the figures to price with.
+ */
+function applyReturningDiscount(lines: PricingLine[], input: SchoolPricingInput, config: PricingConfig) {
+    const wexLines = lines.filter((l) => l.key === "wexY10" || l.key === "wexY12");
+    const placements = sum(wexLines.map((l) => sum(l.bands.map((b) => b.quantity))));
+    const unplaced = Math.min(Math.max(Math.floor(input.returningUnplaced || 0), 0), placements);
+    const rate = clampFraction(config.returningUnplacedDiscount);
+    if (!unplaced || !rate) return;
+
+    let remaining = unplaced;
+    wexLines.forEach((line, index) => {
+        const linePlacements = sum(line.bands.map((b) => b.quantity));
+        if (!linePlacements || !line.amount) return;
+        // The last year group takes whatever rounding left over, so the
+        // placements discounted always add up to the unplaced count.
+        const share = index === wexLines.length - 1 ?
+            Math.min(remaining, linePlacements) :
+            Math.min(Math.round(unplaced * linePlacements / placements), linePlacements, remaining);
+        if (!share) return;
+        remaining -= share;
+        const undiscounted = line.amount;
+        line.amount = undiscounted - share * (undiscounted / linePlacements) * rate;
+        line.undiscounted = undiscounted;
+        line.returningPlacements = share;
+    });
+}
+
 /**
  * Price a school, trust or hub-school quote.
  *
@@ -257,6 +305,7 @@ export function calculateSchoolPrice(
     };
     addWex("wexY10", "Work experience: Y10", input.wexY10);
     addWex("wexY12", "Work experience: Y12", input.wexY12);
+    applyReturningDiscount(lines, input, config);
 
     const addPerStudent = (key: "events"|"destinations", label: string, taken?: boolean, discounted?: boolean) => {
         if (!taken) return;
@@ -339,6 +388,7 @@ export function mergePricingConfig(stored?: Partial<PricingConfig>): PricingConf
         tiers: stored.tiers?.length ? stored.tiers.map((t, i) => ({...(d.tiers[i] || d.tiers[d.tiers.length - 1]), ...t})) : d.tiers,
         partialProductDiscount: {...d.partialProductDiscount, ...stored.partialProductDiscount},
         fullPlatformDiscount: stored.fullPlatformDiscount ?? d.fullPlatformDiscount,
+        returningUnplacedDiscount: stored.returningUnplacedDiscount ?? d.returningUnplacedDiscount,
         trust: {...d.trust, ...stored.trust},
         hub: {...d.hub, ...stored.hub},
     };
@@ -379,12 +429,19 @@ export type InstitutePricing = {
     discountReason?: string,
     /** A price agreed with the customer, which replaces the calculated one. */
     quoteOverride?: number,
+    /** Students on last year's work experience cohorts who never got a placement,
+     * charged at the returning discount this year. One school's, for a trust. */
+    returningUnplaced?: number,
     /** Schools in the trust, which set its discount. Trust accounts only. */
     schools?: number,
     /** Schools on the hub. Hub accounts only. */
     hubSchools?: number,
     /** The quote as last saved, for the customer to see. */
     quote?: InstituteQuoteSnapshot,
+    /** Academic years ("2026-27") an admin marked as invoiced outside the panel,
+     * for a customer billed some other way (old pricing, an invoice that can't
+     * be matched to them in Xero). Admin-only. */
+    markedInvoiced?: {[year: string]: {at: string, note?: string}},
 };
 
 /** A priced institute: the same shape for a school, a trust and a hub. */
@@ -550,6 +607,7 @@ export function instituteQuote(
         fullPlatformDiscount: pricing?.fullPlatformDiscount,
         bespokeDiscount: pricing?.bespokeDiscount,
         quoteOverride: pricing?.quoteOverride,
+        returningUnplaced: wex ? pricing?.returningUnplaced : undefined,
     }, config);
 }
 

package/src/typeDefinitions.ts

@@ -2564,6 +2564,16 @@ export type ExternalEvent = {
         exists?: boolean,
         perMatchTasks?: boolean,
     },
+    // Parents signing up to an event with parentAttendance set, from its public link
+    // (/event/parents/:oId/:eventId). Each sign-up is an externalEventParents doc.
+    acceptingParents?: boolean,
+    maxParentAdults?: number, // Adult places. Sign-ups close once they're taken.
+    maxParentChildren?: number, // Child places, as above.
+    parentInvites?: {
+        forms?: {form: string, relatedToUpload?: string, visibleTo?: ("employers"|"students"|"parents"|"school")[]}[],
+        files?: string[],
+        requiredFiles?: {fileName: string, fileType: string, visibleTo?: ("employers"|"students"|"parents"|"school")[]}[],
+    },
     employerInvites: {
         forms?: {form: string, relatedToUpload?: string, visibleTo?: ("employers"|"students"|"parents"|"school")[]}[],
         files?: string[],
@@ -2609,7 +2619,7 @@ export type ExternalEvent = {
         provider?: string|false,
         school?: string|false,
     },
-    completedStages: ("basicDetails"|"eventConfig"|"selectEmployers"|"employerInviteForms"|"sendEmployerInvites"|"setupStudentInvites"|"setupSchoolInvites"|"review"|"created"|"launched")[]
+    completedStages: ("basicDetails"|"eventConfig"|"selectEmployers"|"employerInviteForms"|"sendEmployerInvites"|"setupStudentInvites"|"setupSchoolInvites"|"setupParentInvites"|"review"|"created"|"launched")[]
 }&Address
 
 
@@ -3589,6 +3599,29 @@ export type ExternalEventCareersSchool = {
 }
 
 
+// A parent or carer signed up to an event from its public link, with how many adults and children
+// they're bringing. They have no account: the doc id is the credential for their booking page
+// (/event/parents/:oId/:eventId/:eventParentId), as for a school invited by email.
+export type ExternalEventParent = {
+    oId: string,
+    eventId: string,
+    visibleTo: string[],
+    created: string,
+    status: "confirmed"|"cancelled"|"removed", // "cancelled" by the parent, "removed" by the organiser
+    forename: string,
+    surname: string,
+    email: string,
+    adults: number,
+    children: number,
+    // Careers hub events only: the school their children go to, as they gave it.
+    schoolName?: string,
+    completedInvite?: {
+        filesViewed?: string[],
+        formsCompleted?: {[key: string]: unknown},
+        filesUploaded?: {[key: number]: string},
+    },
+}
+
 export type ExternalEventStudent = {
     oId: string,
     uid: string,