@teamscala/service-boot 0.23.284

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

@@ -0,0 +1,421 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Public ORPC procedure for submitting a public assessment (quiz) response.
+ * Mirrors public-gpt-session-router: a public, system-trusted write path for an
+ * anonymous/guest visitor — find-or-create the contact in client_database, score
+ * the answers, and persist an assessment_responses row. This is the submit path
+ * the deleted public-assessment wrapper used to provide via an injected onSubmit;
+ * recovering it here brings the quiz in line with the shared machinery (the GPT's
+ * publicGptSession is the sibling pattern) instead of a per-page bespoke handler.
+ *
+ * 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).
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { sendEmail, initResendClient } from "@teamscala/api-resend/send-email";
+import { applyTemplateVars, lookupTemplate } from "@teamscala/email/templates/lookup";
+import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getDefaultEmailSender } from "./email-defaults.ts";
+
+interface Context {
+	prisma: any;
+	headers: Headers;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+}
+
+const pub = os.$context<Context>();
+
+const submitSchema = v.object({
+	assessmentId: v.string(),
+	firstName: v.string(),
+	email: v.string(),
+	company: v.optional(v.string()),
+	phone: v.optional(v.string()),
+	website: v.optional(v.string()),
+	industry: v.optional(v.string()),
+	teamSize: v.optional(v.string()),
+	revenueRange: v.optional(v.string()),
+	answers: v.array(
+		v.object({
+			questionId: v.string(),
+			scaleValue: v.optional(v.number()),
+			textValue: v.optional(v.string()),
+			choiceValue: v.optional(v.string()),
+			choiceValues: v.optional(v.array(v.string())),
+		}),
+	),
+});
+
+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;
+
+/**
+ * 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.
+ */
+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];
+}
+
+
+/**
+ * Best-effort branded Authority Index Report email. Self-contained: loads its
+ * own Resend secret, swallows every error — a send failure is logged and NEVER
+ * undoes the submit (the agreement-completion-email pattern). Fire-and-forget
+ * from the submit handler.
+ */
+async function sendAuthorityReportEmail(opts: {
+	to: string;
+	firstName: string;
+	totalScore: number;
+	bandLabel: string;
+	categoryScores: Record<string, number>;
+	ctaUrl?: string;
+}): 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;
+	}
+	initResendClient(decrypted.token);
+	const from = await getDefaultEmailSender();
+	// Subject + body from the `authority-index-report` email_template row, not
+	// literals here (email-template-registry-type). The per-pillar rows and the
+	// optional CTA are the only DYNAMIC markup, so they are rendered here and
+	// passed as merge vars — the row still owns all the copy and the layout.
+	const pillarRows = (
+		Object.entries(opts.categoryScores) as Array<[string, number]>
+	)
+		.map(
+			([name, score]) =>
+				`<tr><td style="padding:6px 0;color:#374151">${name}</td><td style="padding:6px 0;text-align:right;font-weight:600;color:#111827">${score} / 100</td></tr>`,
+		)
+		.join("");
+	const pillarsText = (
+		Object.entries(opts.categoryScores) as Array<[string, number]>
+	)
+		.map(([name, score]) => `${name}: ${score} / 100`)
+		.join("\n");
+	const tpl = applyTemplateVars(await lookupTemplate("authority-index-report"), {
+		firstName: opts.firstName || "there",
+		totalScore: String(opts.totalScore),
+		bandLabel: opts.bandLabel,
+		pillarRows,
+		pillarsText,
+		ctaHtml: opts.ctaUrl
+			? `<p style="margin:24px 0 0"><a href="${opts.ctaUrl}" style="display:inline-block;background:#111827;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 res = await sendEmail({
+		from,
+		to: opts.to,
+		subject: tpl.subject,
+		html: tpl.bodyHtml,
+		text: tpl.bodyText,
+	});
+	if (res.success) {
+		log.info(
+			`[authority-report-email] sent to ${opts.to}${res.id ? ` (id ${res.id})` : ""}`,
+		);
+	} else {
+		log.error(
+			`[authority-report-email] failed to ${opts.to}: ${res.error ?? "unknown"}`,
+		);
+	}
+}
+
+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 };
+}
+
+export const publicAssessmentRouter = {
+	submit: pub.input(submitSchema).handler(async ({ input, context }) => {
+		const prisma = context.prisma;
+		const log = getAppLogger();
+		const email = (input.email ?? "").trim().toLowerCase();
+
+		try {
+			const assessment = await prisma.assessments.findUnique({
+				where: { id: input.assessmentId },
+				select: {
+					id: true,
+					organisation_id: true,
+					questions: true,
+					cta_url: true,
+					slug: true,
+				},
+			});
+			if (!assessment) return { error: "Assessment not found" } as const;
+
+			const questions = (Array.isArray(assessment.questions)
+				? assessment.questions
+				: []) as StoredQuestion[];
+			const { totalScore, categoryScores } = scoreAnswers(
+				questions,
+				input.answers,
+			);
+			const bands = await getBands(assessment.id);
+			const band = bands ? bandForScore(totalScore, bands) : null;
+
+			// Find-or-create the contact in client_database (the single contact
+			// store) — same shape as publicGptSession's gate. OPTIONAL: only
+			// services whose prisma client includes client_database (e.g. the GPT)
+			// link a CRM contact here. The quiz service's client is scoped without
+			// it, so skip gracefully — the assessment_responses row below already
+			// captures name/last_name/email/company, matching the historical quiz
+			// (which never wrote CRM contacts either).
+			const nameParts = (input.firstName ?? "").trim().split(/\s+/);
+			const firstName = nameParts[0] || "Unknown";
+			const lastName = nameParts.slice(1).join(" ") || "-";
+			const orgId = assessment.organisation_id;
+			const bandTag = band ? `authority:${band.slug}` : null;
+			const firmographicTags = [
+				input.industry ? `industry:${input.industry}` : null,
+				input.teamSize ? `team-size:${input.teamSize}` : null,
+				input.revenueRange ? `revenue:${input.revenueRange}` : null,
+			].filter((t): t is string => t !== null);
+			const assignedTags = [bandTag, ...firmographicTags].filter(
+				(t): t is string => t !== null,
+			);
+			const assignedPrefixes = [
+				"authority:",
+				"industry:",
+				"team-size:",
+				"revenue:",
+			];
+			if (orgId && prisma.client_database) {
+				const existing = await prisma.client_database.findFirst({
+					where: { organisation_id: orgId, primary_email: email },
+					select: { id: true, tags: true },
+				});
+				const websiteData = input.website
+					? { company_website: input.website }
+					: {};
+				if (existing) {
+					// Replace any prior assessment-assigned tags with the new set.
+					const nextTags = [
+						...(existing.tags ?? []).filter(
+							(t: string) => !assignedPrefixes.some((p) => t.startsWith(p)),
+						),
+						...assignedTags,
+					];
+					await prisma.client_database.update({
+						where: { id: existing.id },
+						data: {
+							first_name: firstName,
+							last_name: lastName,
+							...(input.phone ? { mobile_phone: input.phone } : {}),
+							...(input.company ? { company_name: input.company } : {}),
+							...websiteData,
+							tags: nextTags,
+							last_updated_by: "assessment-gate",
+						},
+					});
+				} else {
+					await prisma.client_database.create({
+						data: {
+							organisation_id: orgId,
+							first_name: firstName,
+							last_name: lastName,
+							primary_email: email,
+							mobile_phone: input.phone ?? null,
+							company_name: input.company ?? null,
+							...websiteData,
+							lead_source: "assessment-gate",
+							data_source: "public-form",
+							referral_source: input.assessmentId,
+							lifecycle_stage: "lead",
+							tags: assignedTags,
+							created_by: "assessment-gate",
+							last_updated_by: "assessment-gate",
+						},
+					});
+				}
+			}
+
+			const response = await prisma.assessment_responses.create({
+				data: {
+					assessment_id: input.assessmentId,
+					email,
+					first_name: firstName,
+					last_name: lastName,
+					company: input.company ?? null,
+					total_score: totalScore,
+					category_scores: categoryScores,
+					answers: input.answers.map((a) => ({
+						question_id: a.questionId,
+						scale_value: a.scaleValue ?? null,
+						text_value: a.textValue ?? null,
+						choice_value: a.choiceValue ?? null,
+						choice_values: a.choiceValues ?? null,
+					})),
+					organisation_id: orgId,
+					completed_at: new Date(),
+				},
+				select: { id: true },
+			});
+
+			// Detached post-submit automation: branded report email + sales notify.
+			// Failures are logged and never undo the submit.
+			const ctaUrl =
+				(typeof assessment.cta_url === "string" && assessment.cta_url) ||
+				undefined;
+			if (band) {
+				void sendAuthorityReportEmail({
+					to: email,
+					firstName,
+					totalScore,
+					bandLabel: band.label,
+					categoryScores,
+					ctaUrl,
+				}).catch((e) =>
+					log.error(
+						`[publicAssessment.submit] report email non-fatal: ${e instanceof Error ? e.message : String(e)}`,
+					),
+				);
+			}
+			if (orgId) {
+				recordEvent({
+					kind: "assessment.authority.completed",
+					payload: {
+						assessment_id: input.assessmentId,
+						response_id: response.id,
+						email,
+						organisation_id: orgId,
+						total_score: totalScore,
+						band: band?.slug ?? null,
+						category_scores: categoryScores,
+					},
+				});
+			}
+
+			return {
+				success: true as const,
+				responseId: response.id,
+				reportUrl: `/report/${response.id}`,
+				totalScore,
+				categoryScores,
+				...(band ? { band: band.label } : {}),
+			};
+		} catch (err) {
+			log.error(
+				`[publicAssessment.submit] failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			throw err;
+		}
+	}),
+};