@teamscala/service-boot 0.23.395 → 0.23.397

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.395",
+  "version": "0.23.397",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -18,6 +18,7 @@
   "dependencies": {
     "@teamscala/agreement-generation": "*",
     "@teamscala/api-resend": "*",
+    "@teamscala/assessment-block": "*",
     "@teamscala/auth": "*",
     "@teamscala/cache": "*",
     "@teamscala/channel": "*",

package/src/fn-routers/public-assessment-router.test.ts

@@ -0,0 +1,277 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Locks the single-band-source contract of the Authority Index completion
+ * email (quiz-email-band-single-sourced): the band the email names, the tag
+ * it records and the report narrative it renders all derive from
+ * assessments.stage_bands through the same helpers the report page uses, so
+ * the email can no longer name a different band than the report for one
+ * score (the retired `<id>-bands` config row disagreed at 45 and 85), and an
+ * authored `{{score}}` placeholder never reaches the recipient unsubstituted.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { applyTemplateVars } from "@teamscala/email/templates/lookup";
+
+interface CapturedEmail {
+	to: string;
+	subject: string;
+	html: string;
+	text: string;
+}
+
+let capturedEmail: CapturedEmail | null = null;
+let emailResolve: ((email: CapturedEmail) => void) | null = null;
+let capturedEvent: { kind: string; payload: Record<string, unknown> } | null = null;
+
+const noopLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+};
+
+mock.module("@teamscala/logger/app-loggers", () => ({
+	getAppLogger: () => noopLogger,
+}));
+
+mock.module("@teamscala/api-resend/send-email", () => ({
+	initResendClient: () => {},
+	sendEmail: async (args: CapturedEmail) => {
+		capturedEmail = args;
+		emailResolve?.(args);
+		return { success: true as const, id: "re_test_123" };
+	},
+}));
+
+// The row owns copy + layout; the test mirrors the authority-index-report
+// row's merge tokens so the substitution surface exercised is the real one.
+// applyTemplateVars stays the REAL implementation — only lookup is stubbed.
+mock.module("@teamscala/email/templates/lookup", () => ({
+	lookupTemplate: async () => ({
+		subject: "Your Authority Index — {{totalScore}}/100 ({{bandLabel}})",
+		bodyHtml:
+			"<h1>{{totalScore}}/100 — {{bandLabel}}</h1><h2>{{reportTitle}}</h2><p>{{tagline}}</p>{{narrativeHtml}}{{pillarNotesHtml}}{{priorityActionsHtml}}{{roadmapHtml}}{{strategicFocusHtml}}{{opportunitiesHtml}}{{twelveMonthTargetHtml}}",
+		bodyText:
+			"{{totalScore}}/100 — {{bandLabel}}\n{{reportTitle}}\n{{tagline}}\n{{narrativeText}}",
+	}),
+	applyTemplateVars,
+}));
+
+mock.module("@teamscala/db/registry/load-config", () => ({
+	loadRegistryConfig: async () => ({ token: "test-token" }),
+}));
+
+mock.module("@teamscala/encryption/crypto/secret-config", () => ({
+	decryptSecretConfig: (raw: unknown) => raw,
+}));
+
+mock.module("@teamscala/resolver-engine/data-resolvers/fetch-org-brand", () => ({
+	fetchOrgBrand: async () => null,
+}));
+
+mock.module("@teamscala/email/identity/resolve-email-sender", () => ({
+	resolveEmailSender: async () => ({
+		from: "Test <test@example.com>",
+		replyTo: undefined,
+		isOrgIdentity: false,
+		brand: {
+			orgName: "TestCo",
+			primaryColor: "#123456",
+			accentColor: "#abcdef",
+			logoUrl: null,
+		},
+	}),
+}));
+
+mock.module("@teamscala/event-log/record-event", () => ({
+	recordEvent: (e: { kind: string; payload: Record<string, unknown> }) => {
+		capturedEvent = e;
+	},
+}));
+
+const { publicAssessmentRouter } = await import("./public-assessment-router.ts");
+
+// Mirrors the authored assessments.stage_bands shape (ascending max, the last
+// band the catch-all) with the real threshold edges 20/40/60/80 — the band
+// set the report page renders.
+const STAGE_BANDS = {
+	bands: [
+		{
+			name: "Unknown",
+			max: 20,
+			tagline: "tagline-unknown",
+			executiveSummary: "You scored {{score}} — Unknown stage.",
+			pillarNotes: { seen: "seen-unknown" },
+			priorityActions: [{ title: "Act U1", description: "desc-u1" }],
+			roadmap: { month1: { focus: "Focus U", actions: ["u-a"] } },
+			strategicFocus: "focus-unknown",
+			opportunities: ["opp-u"],
+			twelveMonthTarget: "target-unknown",
+		},
+		{
+			name: "Testing",
+			max: 40,
+			tagline: "tagline-testing",
+			executiveSummary: "You scored {{score}} — Testing stage.",
+			pillarNotes: { seen: "seen-testing" },
+			priorityActions: [{ title: "Act T1", description: "desc-t1" }],
+			roadmap: { month1: { focus: "Focus T", actions: ["t-a"] } },
+			strategicFocus: "focus-testing",
+			opportunities: ["opp-t"],
+			twelveMonthTarget: "target-testing",
+		},
+		{
+			name: "Experimenting",
+			max: 60,
+			tagline: "tagline-experimenting",
+			executiveSummary: "You scored {{score}} — Experimenting stage.",
+			pillarNotes: { seen: "seen-experimenting", heard: "heard-experimenting" },
+			priorityActions: [
+				{ title: "Act E1", description: "desc-e1" },
+				{ title: "Act E2", description: "desc-e2" },
+			],
+			roadmap: {
+				month1: { focus: "Focus E1", actions: ["e1-a"] },
+				month2: { focus: "Focus E2", actions: ["e2-a"] },
+			},
+			strategicFocus: "focus-experimenting",
+			opportunities: ["opp-e"],
+			twelveMonthTarget: "target-experimenting",
+		},
+		{
+			name: "Recognised",
+			max: 80,
+			tagline: "tagline-recognised",
+			executiveSummary: "You scored {{score}} — Recognised stage.",
+			pillarNotes: {},
+			priorityActions: [],
+			strategicFocus: "focus-recognised",
+			twelveMonthTarget: "target-recognised",
+		},
+		{
+			name: "Industry Influencer",
+			tagline: "tagline-influencer",
+			executiveSummary: "You scored {{score}} — Influencer stage.",
+			pillarNotes: {},
+			priorityActions: [],
+			strategicFocus: "focus-influencer",
+			twelveMonthTarget: "target-influencer",
+		},
+	],
+};
+
+function makeFakePrisma() {
+	return {
+		assessments: {
+			findUnique: async () => ({
+				id: "asmt-1",
+				organisation_id: "org-1",
+				questions: Array.from({ length: 20 }, (_, i) => ({
+					id: `q${i + 1}`,
+					type: "scale",
+					category: `Pillar ${(i % 4) + 1}`,
+				})),
+				cta_url: "https://book.example/session",
+				slug: "authority-index",
+				stage_bands: STAGE_BANDS,
+				report_title: "Personalised Authority Blueprint",
+			}),
+		},
+		// client_database deliberately absent — the quiz prisma client is
+		// scoped without it, so the CRM branch must skip without error.
+		assessment_responses: {
+			create: async () => ({ id: "resp-1" }),
+		},
+		email_send_log: {
+			create: async () => ({}),
+		},
+	};
+}
+
+/** 20 scale questions (max 80); 9 answered 5 (earned 36) + 11 answered 1 (earned 0) → 45%. */
+function answersForScore45() {
+	return Array.from({ length: 20 }, (_, i) => ({
+		questionId: `q${i + 1}`,
+		scaleValue: i < 9 ? 5 : 1,
+	}));
+}
+
+type SubmitHandler = (opts: {
+	input: Record<string, unknown>;
+	context: { prisma: unknown; headers: Headers };
+}) => Promise<Record<string, unknown>>;
+
+async function submitWith45() {
+	// The raw handler under ~orpc only reads { input, context }; the other
+	// ProcedureHandlerOptions fields are middleware plumbing this procedure
+	// (no middlewares) never touches, so the narrowed call shape is cast.
+	const handler = publicAssessmentRouter.submit["~orpc"].handler as unknown as SubmitHandler;
+	return handler({
+		input: {
+			assessmentId: "asmt-1",
+			firstName: "Alex Reader",
+			email: "alex@example.com",
+			answers: answersForScore45(),
+		},
+		context: { prisma: makeFakePrisma(), headers: new Headers() },
+	});
+}
+
+beforeEach(() => {
+	capturedEmail = null;
+	capturedEvent = null;
+});
+
+describe("publicAssessment.submit — email band single-sourced from stage_bands", () => {
+	test("score 45 names the stage_bands band (Experimenting), not the retired config band (Testing)", async () => {
+		const result = await submitWith45();
+		expect(result.totalScore).toBe(45);
+		expect(result.band).toBe("Experimenting");
+	});
+
+	test("the email arrives naming the same band, with the narrative substituted and no literal {{score}}", async () => {
+		const emailPromise = new Promise<CapturedEmail>((resolve) => {
+			emailResolve = resolve;
+		});
+		await submitWith45();
+		const email = await emailPromise;
+
+		expect(email.subject).toContain("45/100");
+		expect(email.subject).toContain("Experimenting");
+		expect(email.html).toContain("45/100 — Experimenting");
+		expect(email.html).toContain("You scored 45 — Experimenting stage.");
+		expect(email.html).not.toContain("{{score}}");
+		expect(email.text).toContain("You scored 45 — Experimenting stage.");
+		expect(email.text).not.toContain("{{score}}");
+	});
+
+	test("report sections render from the same band the header names", async () => {
+		const emailPromise = new Promise<CapturedEmail>((resolve) => {
+			emailResolve = resolve;
+		});
+		await submitWith45();
+		const email = await emailPromise;
+
+		expect(email.html).toContain("Personalised Authority Blueprint");
+		expect(email.html).toContain("tagline-experimenting");
+		expect(email.html).toContain("Act E1");
+		expect(email.html).toContain("desc-e1");
+		expect(email.html).toContain("Focus E1");
+		expect(email.html).toContain("focus-experimenting");
+		expect(email.html).toContain("opp-e");
+		expect(email.html).toContain("target-experimenting");
+		// other bands' copy must not leak into this band's email
+		expect(email.html).not.toContain("Act T1");
+		expect(email.html).not.toContain("Act U1");
+		expect(email.html).not.toContain("Recognised stage");
+	});
+
+	test("the event tag slug derives from the authored band name", async () => {
+		await submitWith45();
+		expect(capturedEvent?.kind).toBe("assessment.authority.completed");
+		expect(capturedEvent?.payload.band).toBe("experimenting");
+	});
+});

package/src/fn-routers/public-assessment-router.ts

@@ -29,6 +29,13 @@ import { resolveEmailSender } from "@teamscala/email/identity/resolve-email-send
 import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-org-brand";
+import type { StageBand } from "@teamscala/assessment-block/report-data";
+import {
+	generateNarrative,
+	orderRoadmap,
+	readStageBands,
+	selectStageBand,
+} from "@teamscala/assessment-block/report-data";
 import { recordEvent } from "@teamscala/event-log/record-event";
 
 interface Context {
@@ -72,36 +79,14 @@ interface StoredQuestion {
 const SCALE_MAX = 4;
 
 /**
- * Bands are DATA, not code: each assessment that wants score-bands declares them
- * in a `config` registry row named `<assessment-slug>-bands` (shape:
- * `{bands: [{max, slug, label}, …]}`). An assessment with no such row is scored
- * but not banded — so the Authority Index bands without affecting other quizzes.
- * The band NARRATIVE is generated by the Strategist agent from its system prompt.
+ * A stage band names itself; the event tag needs a stable slug. Derived from
+ * the authored name rather than stored beside it, so the two cannot drift.
  */
-const bandsRowSchema = v.looseObject({
-	bands: v.array(
-		v.object({ max: v.number(), slug: v.string(), label: v.string() }),
-	),
-});
-
-async function getBands(
-	assessmentId: string | null | undefined,
-): Promise<Array<{ max: number; slug: string; label: string }> | null> {
-	if (!assessmentId) return null;
-	const row = await loadRegistryConfig(
-		"config",
-		`${assessmentId}-bands`,
-		bandsRowSchema,
-	).catch(() => null);
-	if (!row || !Array.isArray(row.bands) || row.bands.length === 0) return null;
-	return row.bands;
-}
-
-function bandForScore(
-	total: number,
-	bands: Array<{ max: number; slug: string; label: string }>,
-): { slug: string; label: string } {
-	return bands.find((b) => total <= b.max) ?? bands[bands.length - 1];
+function toBandSlug(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
 }
 
 
@@ -116,6 +101,8 @@ async function sendAuthorityReportEmail(opts: {
 	firstName: string;
 	totalScore: number;
 	bandLabel: string;
+	stageBand: StageBand | null;
+	reportTitle: string;
 	categoryScores: Record<string, number>;
 	ctaUrl?: string;
 	organisationId?: string | null;
@@ -178,12 +165,65 @@ async function sendAuthorityReportEmail(opts: {
 	)
 		.map(([name, score]) => `${name}: ${score} / 100`)
 		.join("\n");
+	// REPORT SECTIONS. Authored per stage on assessments.stage_bands and rendered
+	// here as markup, so the template row stays copy + layout. Every section is
+	// optional: a stage that has not authored one yields an empty string and the
+	// row simply renders nothing for it.
+	const b = opts.stageBand;
+	const sectionHtml = (heading: string, inner: string) =>
+		inner
+			? `<h3 style="margin:24px 0 8px;font-size:15px;font-weight:700;color:${primary}">${heading}</h3>${inner}`
+			: "";
+	const paraHtml = (text?: string) =>
+		text ? `<p style="margin:0 0 12px;color:${muted}">${text}</p>` : "";
+	const bulletsHtml = (items?: string[]) =>
+		Array.isArray(items) && items.length > 0
+			? `<ul style="margin:0 0 12px;padding-left:20px;color:${muted}">${items
+					.map((i) => `<li style="margin:0 0 4px">${i}</li>`)
+					.join("")}</ul>`
+			: "";
+	const actionsHtml =
+		Array.isArray(b?.priorityActions) && b.priorityActions.length > 0
+			? b.priorityActions
+					.map(
+						(a) =>
+							`<p style="margin:0 0 10px"><strong style="color:${primary}">${a.title}</strong><br><span style="color:${muted}">${a.description ?? ""}</span></p>`,
+					)
+					.join("")
+			: "";
+	const roadmapHtml = orderRoadmap(b?.roadmap)
+		.map(
+			(phase) =>
+				`<p style="margin:0 0 10px"><strong style="color:${primary}">${phase.focus ?? ""}</strong><br><span style="color:${muted}">${(phase.actions ?? []).join(" · ")}</span></p>`,
+		)
+		.join("");
+	const notes = b?.pillarNotes ?? {};
+	const pillarNotesHtml = Object.keys(notes).length
+		? Object.entries(notes)
+				.map(
+					([k, v]) =>
+						`<p style="margin:0 0 8px;color:${muted}"><strong style="color:${primary};text-transform:capitalize">${k}</strong> — ${v}</p>`,
+				)
+				.join("")
+		: "";
+	const narrative = generateNarrative(opts.totalScore, b ?? null);
+
 	const tpl = applyTemplateVars(await lookupTemplate("authority-index-report"), {
 		firstName: opts.firstName || "there",
 		totalScore: String(opts.totalScore),
 		bandLabel: opts.bandLabel,
 		pillarRows,
 		pillarsText,
+		reportTitle: opts.reportTitle,
+		tagline: b?.tagline ?? "",
+		narrativeHtml: paraHtml(narrative),
+		pillarNotesHtml: sectionHtml("Where you stand", pillarNotesHtml),
+		priorityActionsHtml: sectionHtml("Your priority actions", actionsHtml),
+		roadmapHtml: sectionHtml("Your next 90 days", roadmapHtml),
+		strategicFocusHtml: sectionHtml("Strategic focus", paraHtml(b?.strategicFocus)),
+		opportunitiesHtml: sectionHtml("Opportunities", bulletsHtml(b?.opportunities)),
+		twelveMonthTargetHtml: sectionHtml("Twelve-month target", paraHtml(b?.twelveMonthTarget)),
+		narrativeText: narrative,
 		brandPrimaryColor: primary,
 		brandAccentColor: sender.brand.accentColor ?? primary,
 		brandLogoHtml: logoHtml,
@@ -338,6 +378,8 @@ export const publicAssessmentRouter = {
 					questions: true,
 					cta_url: true,
 					slug: true,
+					stage_bands: true,
+					report_title: true,
 				},
 			});
 			if (!assessment) return { error: "Assessment not found" } as const;
@@ -349,8 +391,16 @@ export const publicAssessmentRouter = {
 				questions,
 				input.answers,
 			);
-			const bands = await getBands(assessment.id);
-			const band = bands ? bandForScore(totalScore, bands) : null;
+			// ONE BAND SOURCE. The report page selects from assessments.stage_bands;
+			// the email used to select from a parallel `<id>-bands` config row whose
+			// thresholds disagreed (45 was Testing to the email and Experimenting to
+			// the report). Both now read the authored bands, so the band named in the
+			// email is by construction the band the report shows.
+			const stageBands = readStageBands(assessment);
+			const stageBand = selectStageBand(stageBands, totalScore);
+			const band = stageBand
+				? { label: stageBand.name, slug: toBandSlug(stageBand.name) }
+				: null;
 
 			// Find-or-create the contact in client_database (the single contact
 			// store) — same shape as publicGptSession's gate. OPTIONAL: only
@@ -461,6 +511,10 @@ export const publicAssessmentRouter = {
 					firstName,
 					totalScore,
 					bandLabel: band.label,
+					stageBand,
+					reportTitle:
+						(typeof assessment.report_title === "string" && assessment.report_title) ||
+						"Your report",
 					categoryScores,
 					ctaUrl,
 					organisationId: orgId,