@teamscala/service-boot 0.23.415 → 0.23.417

package/src/fn-routers/assessment-report-email.ts

@@ -0,0 +1,254 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Best-effort branded Authority Index Report email for a public assessment
+ * submit: org brand tokens, the email_template row's copy/layout, per-stage
+ * report sections, Resend send with platform-sender fallback, and the
+ * email_send_log audit row.
+ *
+ * Split out of fn-routers/public-assessment-router.ts (591 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+import * as v from "valibot";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { sendResendEmail } from "./resend-client.ts";
+import { applyTemplateVars, lookupTemplate } from "@teamscala/email/templates/lookup";
+import { resolveEmailSender } from "@teamscala/email/identity/resolve-email-sender";
+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,
+} from "@teamscala/assessment-block/report-data";
+
+export async function sendAuthorityReportEmail(opts: {
+	to: string;
+	firstName: string;
+	totalScore: number;
+	bandLabel: string;
+	stageBand: StageBand | null;
+	reportTitle: string;
+	categoryScores: Record<string, number>;
+	ctaUrl?: string;
+	organisationId?: string | null;
+	prisma: any;
+	/**
+	 * Absolute origin (e.g. "https://quiz.scala.business") of the service that
+	 * received the submit — the origin that serves /api/assets. Mail clients
+	 * cannot resolve a relative src, so an org logo stored as a relative path
+	 * only renders when this is provided. Null → a relative logo stays absent
+	 * (previous behaviour) rather than emitting a broken src.
+	 */
+	publicBaseUrl?: string | null;
+}): Promise<void> {
+	const log = getAppLogger();
+	const rawSecret = await loadRegistryConfig(
+		"secret",
+		"resend-api-key",
+		v.looseObject({ token: v.optional(v.string()) }),
+	).catch(() => null);
+	const decrypted = rawSecret
+		? (decryptSecretConfig(rawSecret as never) as { token?: string })
+		: null;
+	if (!decrypted?.token) {
+		log.warn("[authority-report-email] Resend token unavailable — skipping");
+		return;
+	}
+
+	const brandRow =
+		opts.organisationId && opts.prisma
+			? await fetchOrgBrand(
+					opts.prisma as Parameters<typeof fetchOrgBrand>[0],
+					opts.organisationId,
+				).catch(() => null)
+			: null;
+	// Brand assets are stored as service-relative paths ("/api/assets/…") —
+	// the same origin that served the submit request serves them, so the email
+	// derives the absolute URL from that origin at resolve time instead of the
+	// profile row being mutated per consumer. Already-absolute logos pass through.
+	const absolutizeAssetUrl = (url: string | null): string | null => {
+		if (!url) return null;
+		if (/^https?:\/\//.test(url)) return url;
+		if (url.startsWith("/") && opts.publicBaseUrl) return `${opts.publicBaseUrl}${url}`;
+		return null;
+	};
+	const sender = await resolveEmailSender(opts.organisationId ?? null, {
+		brand: brandRow
+			? {
+					// The FRIENDLY name is the customer-facing one; company_name is the
+					// legal entity. Recipients were getting "GMG APAC: your Authority
+					// Index" and alt="GMG APAC" on the logo, for an org whose brand is
+					// Launcha. Same precedence the platform already uses in
+					// agreement-gate (friendly ?? legal), so an org that never set a
+					// friendly name is unchanged.
+					orgName: brandRow.companyFriendlyName || brandRow.companyName || "",
+					primaryColor: brandRow.primaryColor,
+					accentColor: brandRow.accentColor ?? null,
+					logoUrl: absolutizeAssetUrl(brandRow.logo.light),
+				}
+			: undefined,
+	});
+	const primary = sender.brand.primaryColor;
+	const muted = "#6b7280"; // structural neutral for body labels
+	const logoUrl = sender.brand.logoUrl;
+	const logoHtml =
+		logoUrl && /^https?:\/\//.test(logoUrl)
+			? `<p style="margin:0 0 20px"><img src="${logoUrl}" alt="${sender.brand.orgName || ""}" style="max-height:56px;display:block"></p>`
+			: "";
+
+	// Subject + body from the `authority-index-report` email_template row, not
+	// literals here (email-template-registry-type). Dynamic markup is rendered
+	// here and passed as merge vars — the row owns copy + layout; colours +
+	// logo come from the org brand tokens, NOT inline literals.
+	const pillarRows = (
+		Object.entries(opts.categoryScores) as Array<[string, number]>
+	)
+		.map(
+			([name, score]) =>
+				`<tr><td style="padding:6px 0;color:${muted}">${name}</td><td style="padding:6px 0;text-align:right;font-weight:600;color:${primary}">${score} / 100</td></tr>`,
+		)
+		.join("");
+	const pillarsText = (
+		Object.entries(opts.categoryScores) as Array<[string, number]>
+	)
+		.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:16px;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="font-size:14px;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="font-size:14px;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="font-size:14px;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,
+		orgName: sender.brand.orgName,
+		ctaHtml: opts.ctaUrl
+			? `<p style="margin:24px 0 0"><a href="${opts.ctaUrl}" style="display:inline-block;background:${primary};color:#ffffff;text-decoration:none;font-weight:600;padding:12px 22px;border-radius:8px">Book your Authority Growth Session</a></p>`
+			: "",
+		ctaText: opts.ctaUrl ? `\nBook your Authority Growth Session: ${opts.ctaUrl}` : "",
+	});
+
+	const sendOnce = async (fromHeader: string, replyToHeader: string | undefined) =>
+		sendResendEmail(decrypted.token, {
+			from: fromHeader,
+			to: opts.to,
+			subject: tpl.subject,
+			html: tpl.bodyHtml,
+			text: tpl.bodyText,
+			reply_to: replyToHeader,
+		});
+
+	let res = await sendOnce(sender.from, sender.replyTo);
+	let usedFrom = sender.from;
+	if (!res.success) {
+		// Resend refused the org sender (likely unverified domain). Fall back
+		// to the platform sender; never fail because a verification lookup
+		// failed — the resolver returns the row, the failure is at Resend.
+		const platformRow = await loadRegistryConfig(
+			"config",
+			"email-defaults",
+			v.looseObject({ default_sender: v.optional(v.string()) }),
+		).catch(() => null);
+		const fallbackFrom =
+			(platformRow?.default_sender as string | undefined)?.trim() ||
+			"scala <noreply@gateway.scala.business>";
+		log.warn(
+			`[authority-report-email] org sender ${sender.from} refused by Resend (${res.error ?? "unknown"}); falling back to platform ${fallbackFrom}`,
+		);
+		res = await sendOnce(fallbackFrom, undefined);
+		usedFrom = fallbackFrom;
+	}
+
+	if (res.success) {
+		log.info(
+			`[authority-report-email] sent to ${opts.to}${res.id ? ` (id ${res.id})` : ""} from=${usedFrom}${sender.isOrgIdentity ? "" : " (platform fallback)"}`,
+		);
+	} else {
+		log.error(
+			`[authority-report-email] failed to ${opts.to}: ${res.error ?? "unknown"}`,
+		);
+	}
+
+	// email-send-audited: best-effort audit row. Guarded so a stale prisma
+	// client (scala-quiz schema predates email_send_log) skips cleanly.
+	try {
+		const auditPrisma = opts.prisma as {
+			email_send_log?: { create: (args: unknown) => Promise<unknown> };
+		};
+		if (auditPrisma?.email_send_log) {
+			await auditPrisma.email_send_log.create({
+				data: {
+					to_address: opts.to,
+					template_slug: "authority-index-report",
+					status: res.success ? "sent" : "failed",
+					provider_message_id: res.id ?? null,
+					error: res.success ? null : (res.error ?? "unknown"),
+					from_address: usedFrom,
+				},
+			});
+		}
+	} catch (auditErr) {
+		log.warn(
+			`[authority-report-email] audit row write failed: ${auditErr instanceof Error ? auditErr.message : String(auditErr)}`,
+		);
+	}
+}

package/src/fn-routers/assessment-scoring.ts

@@ -0,0 +1,105 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Public assessment (quiz) scoring: the stored-question shape, the scale/choice
+ * earned-vs-max rules, per-category + total scores, and the stable stage-band
+ * slug derivation.
+ *
+ * Scoring (recovered from live data, 2026-06-13): each scale answer contributes
+ * (scaleValue - 1) earned out of 4 max (1–5 scale → 0–4); choice answers
+ * contribute the selected option's points out of the question's max option
+ * points. A category's score is round(100 * earned / max) over that category's
+ * questions; the overall total is the same over all questions. Unanswered
+ * questions count toward the denominator (contribute 0) — matches the historical
+ * rows (e.g. Σ(v-1)=78 over 36 questions → 78/144 = 54).
+ *
+ * Split out of fn-routers/public-assessment-router.ts (591 lines) —
+ * byte-for-byte move; import paths adjusted only.
+ */
+
+export interface StoredQuestion {
+	id: string;
+	category?: string | null;
+	type?: string | null;
+	weight?: number | null;
+	options?: Array<{ value: string; points: number }> | null;
+}
+
+/** Scale answers are 1–5; earned = value-1, max = 4. */
+const SCALE_MAX = 4;
+
+/**
+ * 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.
+ */
+export function toBandSlug(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+export function scoreAnswers(
+	questions: StoredQuestion[],
+	answers: Array<{
+		questionId: string;
+		scaleValue?: number;
+		choiceValue?: string;
+		choiceValues?: string[];
+	}>,
+): { totalScore: number; categoryScores: Record<string, number> } {
+	const answerByQ = new Map(answers.map((a) => [a.questionId, a]));
+	// Per-category and overall earned/max accumulators.
+	const cat = new Map<string, { earned: number; max: number }>();
+	let totalEarned = 0;
+	let totalMax = 0;
+
+	for (const q of questions) {
+		if (q.type === "text") continue; // text questions are qualitative — never scored
+		const category = q.category || "General";
+		const a = answerByQ.get(q.id);
+		let earned = 0;
+		let max = 0;
+
+		if (q.options && q.options.length > 0) {
+			// Choice question: max is the highest single option's points; earned is
+			// the selected option(s)' points (capped at max).
+			max = Math.max(0, ...q.options.map((o) => o.points || 0));
+			if (a?.choiceValue) {
+				earned = q.options.find((o) => o.value === a.choiceValue)?.points ?? 0;
+			} else if (a?.choiceValues?.length) {
+				earned = Math.min(
+					max,
+					a.choiceValues.reduce(
+						(s, val) =>
+							s + (q.options?.find((o) => o.value === val)?.points ?? 0),
+						0,
+					),
+				);
+			}
+		} else {
+			// Scale question (the common case): 1–5 → earned 0–4.
+			max = SCALE_MAX;
+			if (typeof a?.scaleValue === "number") {
+				earned = Math.max(0, Math.min(SCALE_MAX, a.scaleValue - 1));
+			}
+		}
+
+		if (max <= 0) continue; // text/unscored questions don't affect the score
+		const entry = cat.get(category) ?? { earned: 0, max: 0 };
+		entry.earned += earned;
+		entry.max += max;
+		cat.set(category, entry);
+		totalEarned += earned;
+		totalMax += max;
+	}
+
+	const categoryScores: Record<string, number> = {};
+	for (const [name, { earned, max }] of cat) {
+		categoryScores[name] = max > 0 ? Math.round((100 * earned) / max) : 0;
+	}
+	const totalScore = totalMax > 0 ? Math.round((100 * totalEarned) / totalMax) : 0;
+	return { totalScore, categoryScores };
+}