placementt-core 1.400.1063 → 1.400.1065

package/lib/typeDefinitions.d.ts

@@ -1929,6 +1929,15 @@ export type ScheduledVisit = {
      * a new target type never needs a lookup table. */
     targetCollection: "placements" | "users";
     targetId: string;
+    /** The target's name, copied in at write time by whoever creates the check.
+     *
+     * Denormalised on purpose: a list of checks is a list of people, and reading the
+     * target doc per row costs one read per pupil every time a staff member opens a
+     * cohort's checks — a two-hundred-wide read for a name that never changes. Written
+     * by every generator and by the ad-hoc dialog; absent on checks written before
+     * this existed, so every reader falls back rather than showing a blank. */
+    targetForename?: string;
+    targetSurname?: string;
     date: string;
     checkType: "call" | "in-person" | "video" | "email" | "other";
     createdByUid: string;
@@ -1949,8 +1958,23 @@ export type ScheduledVisit = {
     /** Snapshotted off `forms` when assigned, so editing the form later never
      * rewrites the questions on checks already answered. */
     formSchema?: CustomFormSchema;
-    /** Raised by the assignee on completion when something needs escalating. */
+    /** LEGACY. Escalation flags now live on the check's private subdocument — see
+     * ScheduledCheckPrivate. Still declared because docs written before the split
+     * carry it and the backfill has to read it; nothing writes it any more.
+     *
+     * It moved because Firestore rules are document-level: a guidance check is read
+     * by the pupil it is about, and a pupil learning that staff flagged a concern
+     * about them, with no context, is the harm the flag exists to avoid. Filtering
+     * it out in the component hides it visually and nothing else. */
     concern?: boolean;
+    /** Denormalised "a pupil may read this check".
+     *
+     * True only on careersGuidance checks. It exists because the rule that lets a
+     * pupil read their own 1:1s cannot tell a guidance check from a leaver check
+     * without it — and a blanket "read your own checks" rule would hand a SEND
+     * leaver the pastoral notes on their own transition calls. The client query
+     * carries the same filter, because Firestore requires it to. */
+    studentVisible?: boolean;
     /** The slot's booking window, on checks generated from a window-mode guidance
      * slot. Absent on fixed-date and ad-hoc checks, which are booked from birth.
      *
@@ -1987,6 +2011,31 @@ export type ScheduledVisit = {
     /** Stamped when a check passes the grace period unanswered. */
     missedAt?: string;
 };
+/** The subcollection and document id both private subdocuments use. One name, in
+ * core, so the web client and the backend cannot address different documents.
+ *
+ * `<parent>/{id}/private/staff` — staff-only fields split out of a document a pupil
+ * is allowed to read. Firestore has no field-level read, so the only way to withhold
+ * a field from a reader who may have the document is to put it in another one. */
+export declare const PRIVATE_SUBCOLLECTION = "private";
+export declare const PRIVATE_STAFF_DOC = "staff";
+/** Staff-only fields belonging to a scheduledChecks doc. See PRIVATE_SUBCOLLECTION. */
+export type ScheduledCheckPrivate = {
+    /** Raised by the assignee on completion when something needs escalating. */
+    concern?: boolean;
+    /** The series the parent check belongs to, copied in so a cycle's concern count
+     * is one collection-group query rather than a read per completed check. */
+    seriesId?: string;
+    oId: string;
+};
+/** Staff-only fields belonging to a careersRecord doc. See PRIVATE_SUBCOLLECTION. */
+export type CareersRecordPrivate = {
+    /** Never shown to the pupil. The safeguarding-adjacent context a member of staff
+     * writes about a meeting, kept in its own document so the entry the pupil reads
+     * cannot carry it. */
+    staffNotes?: string;
+    oId: string;
+};
 /**
  * One dated 1:1 in a school's careers programme — "Year 11 get an options
  * conversation in October and a personal guidance meeting in February".
@@ -2012,6 +2061,14 @@ export type GuidanceSlot = SurveySlot & {
     /** Window mode only: how long the window runs from the slot's resolved date.
      * Absent = up to the next slot. */
     windowDays?: number;
+    /** Whether the PUPIL is emailed before their booked meeting, overriding the
+     * school-wide GuidanceConfig.remindPupils for this slot. Per slot because the
+     * answer genuinely differs: a booked personal guidance meeting is an appointment
+     * the pupil is expected to turn up to, and a whole-cohort assembly is not.
+     *
+     * Absent falls back to the school's setting, which is itself off by default —
+     * see guidanceRemindsPupil. */
+    remindPupil?: boolean;
 };
 /**
  * A named cohort inside the guidance programme, with its own slots — "pupil premium
@@ -2055,6 +2112,11 @@ export type GuidanceConfig = {
     };
     /** Named filtered cohorts whose slots supersede the year group's — see GuidanceGroup. */
     groups?: GuidanceGroup[];
+    /** Whether pupils are emailed before their booked 1:1s, school-wide. Off unless
+     * a careers leader turns it on: emailing a cohort of children is a decision for
+     * the school, not something that should arrive in a deploy. Individual slots may
+     * override it — see GuidanceSlot.remindPupil. */
+    remindPupils?: boolean;
     setupCompletedAt?: string;
     setupBy?: string;
     updatedAt?: string;
@@ -3869,7 +3931,13 @@ export type CareersRecordEntry = {
     durationMins?: number;
     /** Shared with the pupil. BM3 expects pupils to be able to access their record. */
     summary: string;
-    /** Never shown to the pupil. Kept separate so the summary can be surfaced safely. */
+    /** LEGACY. Staff notes now live on the entry's private subdocument — see
+     * CareersRecordPrivate. Still declared because entries written before the split
+     * carry it, the backfill has to read it, and the Compass exports assert it never
+     * leaves the platform.
+     *
+     * It moved because the pupil reads this document. Keeping the notes out of the
+     * component was never enough: the whole doc reaches the browser. */
     staffNotes?: string;
     /** "Any subsequent agreed decisions" — named in the benchmark, so evidence in its own right. */
     actions?: CareersRecordAction[];
@@ -3903,6 +3971,32 @@ export declare const CAREERS_RECORD_MODE_LABELS: Record<CareersRecordEntry["mode
  * @return {CareersRecordEntry["mode"]} the record's mode.
  */
 export declare function checkTypeToRecordMode(checkType: ScheduledVisit["checkType"]): CareersRecordEntry["mode"];
+/**
+ * Whether the pupil is emailed before a 1:1 from this slot.
+ *
+ * The slot has the final say and the school's setting is the default, so a school can
+ * turn the whole thing on and still leave the assembly silent. Both absent means no:
+ * pupil email is opt-in, because the reminders this feature is built on were written
+ * for staff and a school running the programme has not thereby agreed to email its
+ * children.
+ *
+ * @param {Pick<GuidanceSlot, "remindPupil">} [slot] the slot the check came from.
+ * @param {Pick<GuidanceConfig, "remindPupils">} [config] the school's guidance setup.
+ * @return {boolean} whether to email the pupil.
+ */
+export declare function guidanceRemindsPupil(slot?: Pick<GuidanceSlot, "remindPupil">, config?: Pick<GuidanceConfig, "remindPupils">): boolean;
+/**
+ * Who a check is about, off the check itself.
+ *
+ * The name is denormalised onto the check precisely so a list of them needs no read
+ * per row — see ScheduledVisit.targetForename. Returns an empty string for a check
+ * written before that field existed, which is the caller's cue to fall back to
+ * whatever roster it already has rather than print a uid at a member of staff.
+ *
+ * @param {Pick<ScheduledVisit, "targetForename"|"targetSurname">} check the check.
+ * @return {string} their name, or "" when the check does not carry one.
+ */
+export declare function checkTargetName(check: Pick<ScheduledVisit, "targetForename" | "targetSurname">): string;
 export type SuggestedFixRepo = "placementt-web" | "placementt-backend" | "placementt-core";
 export type SuggestedFix = {
     isCodeChange: boolean;

package/lib/typeDefinitions.js

@@ -1,7 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CAREERS_RECORD_MODE_LABELS = exports.CAREERS_RECORD_TYPE_LABELS = void 0;
+exports.CAREERS_RECORD_MODE_LABELS = exports.CAREERS_RECORD_TYPE_LABELS = exports.PRIVATE_STAFF_DOC = exports.PRIVATE_SUBCOLLECTION = void 0;
 exports.checkTypeToRecordMode = checkTypeToRecordMode;
+exports.guidanceRemindsPupil = guidanceRemindsPupil;
+exports.checkTargetName = checkTargetName;
+/** The subcollection and document id both private subdocuments use. One name, in
+ * core, so the web client and the backend cannot address different documents.
+ *
+ * `<parent>/{id}/private/staff` — staff-only fields split out of a document a pupil
+ * is allowed to read. Firestore has no field-level read, so the only way to withhold
+ * a field from a reader who may have the document is to put it in another one. */
+exports.PRIVATE_SUBCOLLECTION = "private";
+exports.PRIVATE_STAFF_DOC = "staff";
 /** Staff-facing labels for each entry type. In core because the web form, the setup
  * wizard and the backend CSV export all name them and must not drift. */
 exports.CAREERS_RECORD_TYPE_LABELS = {
@@ -43,4 +53,34 @@ function checkTypeToRecordMode(checkType) {
         default: return "inPerson";
     }
 }
+/**
+ * Whether the pupil is emailed before a 1:1 from this slot.
+ *
+ * The slot has the final say and the school's setting is the default, so a school can
+ * turn the whole thing on and still leave the assembly silent. Both absent means no:
+ * pupil email is opt-in, because the reminders this feature is built on were written
+ * for staff and a school running the programme has not thereby agreed to email its
+ * children.
+ *
+ * @param {Pick<GuidanceSlot, "remindPupil">} [slot] the slot the check came from.
+ * @param {Pick<GuidanceConfig, "remindPupils">} [config] the school's guidance setup.
+ * @return {boolean} whether to email the pupil.
+ */
+function guidanceRemindsPupil(slot, config) {
+    return slot?.remindPupil ?? config?.remindPupils ?? false;
+}
+/**
+ * Who a check is about, off the check itself.
+ *
+ * The name is denormalised onto the check precisely so a list of them needs no read
+ * per row — see ScheduledVisit.targetForename. Returns an empty string for a check
+ * written before that field existed, which is the caller's cue to fall back to
+ * whatever roster it already has rather than print a uid at a member of staff.
+ *
+ * @param {Pick<ScheduledVisit, "targetForename"|"targetSurname">} check the check.
+ * @return {string} their name, or "" when the check does not carry one.
+ */
+function checkTargetName(check) {
+    return `${check.targetForename ?? ""} ${check.targetSurname ?? ""}`.trim();
+}
 //# sourceMappingURL=typeDefinitions.js.map

package/lib/typeDefinitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"typeDefinitions.js","sourceRoot":"","sources":["../src/typeDefinitions.ts"],"names":[],"mappings":";;;AA66HA,sDASC;AA1CD;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"}
+{"version":3,"file":"typeDefinitions.js","sourceRoot":"","sources":["../src/typeDefinitions.ts"],"names":[],"mappings":";;;AAs/HA,sDASC;AAeD,oDAKC;AAaD,0CAEC;AA5kED;;;;;kFAKkF;AACrE,QAAA,qBAAqB,GAAG,SAAS,CAAC;AAClC,QAAA,iBAAiB,GAAG,OAAO,CAAC;AAw/DzC;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.1063",
+  "version": "1.400.1065",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/typeDefinitions.ts

@@ -1918,6 +1918,15 @@ export type ScheduledVisit = {
      * a new target type never needs a lookup table. */
     targetCollection: "placements"|"users",
     targetId: string,
+    /** The target's name, copied in at write time by whoever creates the check.
+     *
+     * Denormalised on purpose: a list of checks is a list of people, and reading the
+     * target doc per row costs one read per pupil every time a staff member opens a
+     * cohort's checks — a two-hundred-wide read for a name that never changes. Written
+     * by every generator and by the ad-hoc dialog; absent on checks written before
+     * this existed, so every reader falls back rather than showing a blank. */
+    targetForename?: string,
+    targetSurname?: string,
     date: string,                       // yyyy-mm-dd
     checkType: "call"|"in-person"|"video"|"email"|"other",
     createdByUid: string,
@@ -1937,9 +1946,25 @@ export type ScheduledVisit = {
     /** Snapshotted off `forms` when assigned, so editing the form later never
      * rewrites the questions on checks already answered. */
     formSchema?: CustomFormSchema,
-    /** Raised by the assignee on completion when something needs escalating. */
+    /** LEGACY. Escalation flags now live on the check's private subdocument — see
+     * ScheduledCheckPrivate. Still declared because docs written before the split
+     * carry it and the backfill has to read it; nothing writes it any more.
+     *
+     * It moved because Firestore rules are document-level: a guidance check is read
+     * by the pupil it is about, and a pupil learning that staff flagged a concern
+     * about them, with no context, is the harm the flag exists to avoid. Filtering
+     * it out in the component hides it visually and nothing else. */
     concern?: boolean,
 
+    /** Denormalised "a pupil may read this check".
+     *
+     * True only on careersGuidance checks. It exists because the rule that lets a
+     * pupil read their own 1:1s cannot tell a guidance check from a leaver check
+     * without it — and a blanket "read your own checks" rule would hand a SEND
+     * leaver the pastoral notes on their own transition calls. The client query
+     * carries the same filter, because Firestore requires it to. */
+    studentVisible?: boolean,
+
     // ── Booking (D9) ──
     /** The slot's booking window, on checks generated from a window-mode guidance
      * slot. Absent on fixed-date and ad-hoc checks, which are booked from birth.
@@ -1979,6 +2004,34 @@ export type ScheduledVisit = {
     missedAt?: string,
 }
 
+/** The subcollection and document id both private subdocuments use. One name, in
+ * core, so the web client and the backend cannot address different documents.
+ *
+ * `<parent>/{id}/private/staff` — staff-only fields split out of a document a pupil
+ * is allowed to read. Firestore has no field-level read, so the only way to withhold
+ * a field from a reader who may have the document is to put it in another one. */
+export const PRIVATE_SUBCOLLECTION = "private";
+export const PRIVATE_STAFF_DOC = "staff";
+
+/** Staff-only fields belonging to a scheduledChecks doc. See PRIVATE_SUBCOLLECTION. */
+export type ScheduledCheckPrivate = {
+    /** Raised by the assignee on completion when something needs escalating. */
+    concern?: boolean,
+    /** The series the parent check belongs to, copied in so a cycle's concern count
+     * is one collection-group query rather than a read per completed check. */
+    seriesId?: string,
+    oId: string,
+};
+
+/** Staff-only fields belonging to a careersRecord doc. See PRIVATE_SUBCOLLECTION. */
+export type CareersRecordPrivate = {
+    /** Never shown to the pupil. The safeguarding-adjacent context a member of staff
+     * writes about a meeting, kept in its own document so the entry the pupil reads
+     * cannot carry it. */
+    staffNotes?: string,
+    oId: string,
+};
+
 /**
  * One dated 1:1 in a school's careers programme — "Year 11 get an options
  * conversation in October and a personal guidance meeting in February".
@@ -2005,6 +2058,15 @@ export type GuidanceSlot = SurveySlot & {
     /** Window mode only: how long the window runs from the slot's resolved date.
      * Absent = up to the next slot. */
     windowDays?: number,
+
+    /** Whether the PUPIL is emailed before their booked meeting, overriding the
+     * school-wide GuidanceConfig.remindPupils for this slot. Per slot because the
+     * answer genuinely differs: a booked personal guidance meeting is an appointment
+     * the pupil is expected to turn up to, and a whole-cohort assembly is not.
+     *
+     * Absent falls back to the school's setting, which is itself off by default —
+     * see guidanceRemindsPupil. */
+    remindPupil?: boolean,
 };
 
 /**
@@ -2046,6 +2108,11 @@ export type GuidanceConfig = {
     slotsByYearGroup?: {[yearGroup: string]: GuidanceSlot[]},
     /** Named filtered cohorts whose slots supersede the year group's — see GuidanceGroup. */
     groups?: GuidanceGroup[],
+    /** Whether pupils are emailed before their booked 1:1s, school-wide. Off unless
+     * a careers leader turns it on: emailing a cohort of children is a decision for
+     * the school, not something that should arrive in a deploy. Individual slots may
+     * override it — see GuidanceSlot.remindPupil. */
+    remindPupils?: boolean,
     setupCompletedAt?: string,                  // ISO — stamped server-side on first save
     setupBy?: string,                           // staff uid — stamped server-side
     updatedAt?: string,
@@ -3958,7 +4025,13 @@ export type CareersRecordEntry = {
     /** Shared with the pupil. BM3 expects pupils to be able to access their record. */
     summary: string,
 
-    /** Never shown to the pupil. Kept separate so the summary can be surfaced safely. */
+    /** LEGACY. Staff notes now live on the entry's private subdocument — see
+     * CareersRecordPrivate. Still declared because entries written before the split
+     * carry it, the backfill has to read it, and the Compass exports assert it never
+     * leaves the platform.
+     *
+     * It moved because the pupil reads this document. Keeping the notes out of the
+     * component was never enough: the whole doc reaches the browser. */
     staffNotes?: string,
 
     /** "Any subsequent agreed decisions" — named in the benchmark, so evidence in its own right. */
@@ -4022,6 +4095,41 @@ export function checkTypeToRecordMode(checkType: ScheduledVisit["checkType"]): C
     }
 }
 
+/**
+ * Whether the pupil is emailed before a 1:1 from this slot.
+ *
+ * The slot has the final say and the school's setting is the default, so a school can
+ * turn the whole thing on and still leave the assembly silent. Both absent means no:
+ * pupil email is opt-in, because the reminders this feature is built on were written
+ * for staff and a school running the programme has not thereby agreed to email its
+ * children.
+ *
+ * @param {Pick<GuidanceSlot, "remindPupil">} [slot] the slot the check came from.
+ * @param {Pick<GuidanceConfig, "remindPupils">} [config] the school's guidance setup.
+ * @return {boolean} whether to email the pupil.
+ */
+export function guidanceRemindsPupil(
+    slot?: Pick<GuidanceSlot, "remindPupil">,
+    config?: Pick<GuidanceConfig, "remindPupils">,
+): boolean {
+    return slot?.remindPupil ?? config?.remindPupils ?? false;
+}
+
+/**
+ * Who a check is about, off the check itself.
+ *
+ * The name is denormalised onto the check precisely so a list of them needs no read
+ * per row — see ScheduledVisit.targetForename. Returns an empty string for a check
+ * written before that field existed, which is the caller's cue to fall back to
+ * whatever roster it already has rather than print a uid at a member of staff.
+ *
+ * @param {Pick<ScheduledVisit, "targetForename"|"targetSurname">} check the check.
+ * @return {string} their name, or "" when the check does not carry one.
+ */
+export function checkTargetName(check: Pick<ScheduledVisit, "targetForename"|"targetSurname">): string {
+    return `${check.targetForename ?? ""} ${check.targetSurname ?? ""}`.trim();
+}
+
 export type SuggestedFixRepo = "placementt-web"|"placementt-backend"|"placementt-core";
 
 export type SuggestedFix = {