@reform-society/agera-core 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as _$nanostores from "nanostores";
+import { z } from "zod";
 
 //#region src/types.d.ts
 type PredicateOp = "eq" | "neq" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "exists" | "truthy" | "falsy" | "contains" | "starts_with" | "ends_with";
@@ -218,6 +219,148 @@ type FetchBasinJWTOptions = {
 };
 declare function fetchBasinJWT(endpoint: string, storage: StorageAccessor, storageKey: string, options?: FetchBasinJWTOptions): Promise<string>;
 //#endregion
+//#region src/survey/types.d.ts
+type NavAction = {
+  kind: "next";
+} | {
+  kind: "goto";
+  target: string;
+} | {
+  kind: "redirect";
+  target: string;
+};
+type SurveyFieldRule = "required" | "email" | "name" | "phone" | "postal" | {
+  rule: "pattern" | "min" | "max";
+  arg: string;
+};
+type SurveyStepRule = {
+  rule: "required";
+} | {
+  rule: "minSelected" | "maxSelected";
+  arg: number;
+};
+type SurveyOption = {
+  value: string;
+  label?: string;
+  nav?: NavAction; /** Quiz: this option is a correct answer (feeds `expectedValues`). */
+  correct?: boolean; /** Quiz: weighted scoring contributions when selected (feeds `weightedScores`). */
+  weights?: Record<string, number>; /** Free-text "other" option; the typed text is stored under `<name>_other`. */
+  other?: boolean;
+};
+type SurveyField = {
+  name: string;
+  type: "text" | "email" | "tel" | "textarea" | "postal" | "address";
+  rules?: SurveyFieldRule[];
+};
+type SurveyStepQuiz = {
+  model: QuizQuestionModel;
+  section?: string;
+  scoring?: "exact" | "partial";
+};
+type SurveyStep = {
+  id: string;
+  kind: "content" | "single" | "multi" | "scale" | "fields"; /** Answer key; required for single / multi / scale. */
+  name?: string; /** Step is skipped on the path while this evaluates to false. */
+  showIf?: Predicate; /** Default true. */
+  back?: boolean; /** Advancing from this step submits the survey instead of moving on. */
+  terminal?: boolean; /** Step default navigation; a chosen option's `nav` overrides it. */
+  nav?: NavAction;
+  options?: SurveyOption[];
+  scale?: {
+    min: number;
+    max: number;
+    step?: number;
+  };
+  fields?: SurveyField[];
+  validate?: SurveyStepRule[];
+  quiz?: SurveyStepQuiz;
+};
+type SurveyDefinition = {
+  version: 1; /** Session storage key: `agera:survey:<id>`. */
+  id: string; /** Document order = linear order. */
+  steps: SurveyStep[]; /** Default "static" (matches the #145 fixture). */
+  progress?: "static" | "path";
+  quiz?: QuizConfig;
+  lang?: string;
+};
+type SurveyStatus = "idle" | "submitting" | "done" | "failed";
+type SurveyState = {
+  version: 1;
+  definitionId: string;
+  current: string;
+  path: string[]; /** single → string, multi → string[], scale → number, fields → flattened by field name. */
+  answers: Record<string, unknown>;
+  status: SurveyStatus;
+  sessionId: string;
+};
+type SurveyErrors = Record<string, string>;
+type SurveyView = {
+  step: SurveyStep;
+  index: number;
+  canBack: boolean;
+  isTerminal: boolean;
+  progress: ProgressModeInfo;
+  errors: SurveyErrors;
+  quiz: QuizResults | null;
+};
+/** What gets submitted: answers limited to steps on `path`, multi values joined with ", ". */
+type SurveySnapshot = {
+  definitionId: string;
+  sessionId: string;
+  current: string;
+  path: string[];
+  answers: Record<string, string>;
+};
+type NavResult = {
+  kind: "moved";
+  to: string;
+} | {
+  kind: "submit";
+  redirect?: string;
+} | {
+  kind: "blocked";
+  errors: SurveyErrors;
+} | {
+  kind: "stale";
+} | {
+  kind: "noop";
+};
+type SurveyValidator = (input: {
+  step: SurveyStep;
+  answers: Record<string, unknown>;
+  lang?: string;
+}) => SurveyErrors | null | Promise<SurveyErrors | null>;
+type SurveyEngineOptions = {
+  initialState?: SurveyState; /** Used when `initialState` is absent. */
+  sessionId?: string; /** Extra validation on top of the built-in step rules; async results are discarded when stale. */
+  validate?: SurveyValidator;
+};
+type SurveyEngine = {
+  getState(): SurveyState;
+  getView(): SurveyView;
+  subscribe(listener: () => void): () => void; /** Set an answer without navigating. */
+  answer(name: string, value: unknown): void; /** Atomic answer + navigation against one snapshot. */
+  choose(name: string, value: unknown, nav?: NavAction): Promise<NavResult>; /** Validate the current step, then follow `nav` (or the step / option / linear default). */
+  next(nav?: NavAction): Promise<NavResult>;
+  back(): NavResult;
+  goto(id: string): NavResult;
+  snapshot(): SurveySnapshot; /** Submission lifecycle is driven by the consumer; navigation is blocked while "submitting". */
+  setStatus(status: SurveyStatus): void;
+};
+//#endregion
+//#region src/basin-submission.d.ts
+type BasinFormDataInput = {
+  snapshot: SurveySnapshot;
+  step: number;
+  final: boolean;
+  jwt: string;
+  utms: Record<string, string>;
+  anonymousEmail: string;
+  stripFields?: Iterable<string>;
+};
+declare function hashSurveySnapshot(snapshot: SurveySnapshot): string;
+declare function buildBasinFormData(input: BasinFormDataInput): FormData;
+//#endregion
 //#region src/lifecycle.d.ts
 type NormalizedResult = {
   delivery: "observed" | "unobserved";
@@ -618,5 +761,52 @@ declare function assembleCrmRequest({
 //#region src/polling.d.ts
 declare function matchesFormat(example: unknown, value: unknown): boolean;
 //#endregion
-export { type AssembleCrmRequestParams, type AttemptStorage, type BandQuizResults, CRM_CONTACT_KEYS, type CompositePredicate, type CounterDisplayConfig, type CounterPayload, type CounterResponse, type CounterUpdateConfig, type CrmCommand, type CrmConfig, type CrmContactKey, type CrmDispatch, type CrmFetchOptions, type CrmFetchResult, type CrmFrontendKey, type CrmGateway, type CrmGatewayResult, type CrmGroupedAnswer, type CrmJsonGroups, type CrmOutcome, type CrmV2PatchRequest, type CrmV2Payload, type CrmV2Request, type DeviceInput, type DeviceType, type ErrorMessages, type EventSource, type EventSourceKind, type FetchBasinJWTOptions, type FlowAttempt, type InsertDirective, type JsonValue, type JwtPayload, type LifecycleEvent, type LifecycleType, type MemoryCache, type MemoryCacheOptions, type MemoryCacheSetOptions, type NormalizedResult, type PassQuizResults, type PlacesMessageKey, type PlacesMessages, type Predicate, type PredicateOp, type ProgressInfo, type ProgressModeInfo, type QuestionMetrics, type QuizBandDefinition, type QuizConfig, type QuizOutcomeModel, type QuizPassFailConfig, type QuizQuestionInput, type QuizQuestionModel, type QuizQuestionResult, type QuizQuestionState, type QuizResults, type QuizScoringModel, type QuizSectionConfig, type QuizSectionResults, type RequestSnapshot, type ResolveValueSources, type ScoreQuizResults, type SessionState, type ShareConfig, type SimplePredicate, type SplitConfig, type StepState, type StorageAccessor, type SurveyOptions, type TrackingConfig, type Utms, VISITOR_ID_STORAGE_KEY, type ValidationRule, type Validators, type ValueResolver, type WeightedQuizResults, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createAttemptStore, createLifecycleBus, createMemoryCache, createSessionStore, createStepsStore, createTrackingConsumer, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, firstDefined, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, mapTrackingEvent, matchesFormat, mergeAnswers, normalizeResult, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, snapshot, unknownResult, updateUrlWithParams, validators };
+//#region src/survey/engine.d.ts
+declare function createSurveyEngine(definition: SurveyDefinition, options?: SurveyEngineOptions): SurveyEngine;
+//#endregion
+//#region src/survey/progress.d.ts
+declare function computeProgress(definition: SurveyDefinition, state: SurveyState): ProgressModeInfo;
+//#endregion
+//#region src/survey/snapshot.d.ts
+declare function buildSurveySnapshot(definition: SurveyDefinition, state: SurveyState): SurveySnapshot;
+//#endregion
+//#region src/survey/quiz.d.ts
+declare function deriveQuizInputs(definition: SurveyDefinition, state: SurveyState): QuizQuestionInput[];
+//#endregion
+//#region src/survey/schema.d.ts
+declare const surveyDefinitionSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  id: z.ZodString;
+  steps: z.ZodArray<z.ZodType<SurveyStep, unknown, z.core.$ZodTypeInternals<SurveyStep, unknown>>>;
+  progress: z.ZodOptional<z.ZodEnum<{
+    path: "path";
+    static: "static";
+  }>>;
+  quiz: z.ZodOptional<z.ZodObject<{
+    passFail: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      percentGte: z.ZodNumber;
+    }, z.core.$strip>>>;
+    bands: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      label: z.ZodString;
+      minPercent: z.ZodOptional<z.ZodNumber>;
+      maxPercent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>>;
+    sections: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+      passFail: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        percentGte: z.ZodNumber;
+      }, z.core.$strip>>>;
+      bands: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        minPercent: z.ZodOptional<z.ZodNumber>;
+        maxPercent: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strip>>>>;
+    }, z.core.$strip>>>>;
+  }, z.core.$strip>>;
+  lang: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare function parseSurveyDefinition(input: unknown): SurveyDefinition;
+//#endregion
+export { type AssembleCrmRequestParams, type AttemptStorage, type BandQuizResults, CRM_CONTACT_KEYS, type CompositePredicate, type CounterDisplayConfig, type CounterPayload, type CounterResponse, type CounterUpdateConfig, type CrmCommand, type CrmConfig, type CrmContactKey, type CrmDispatch, type CrmFetchOptions, type CrmFetchResult, type CrmFrontendKey, type CrmGateway, type CrmGatewayResult, type CrmGroupedAnswer, type CrmJsonGroups, type CrmOutcome, type CrmV2PatchRequest, type CrmV2Payload, type CrmV2Request, type DeviceInput, type DeviceType, type ErrorMessages, type EventSource, type EventSourceKind, type FetchBasinJWTOptions, type FlowAttempt, type InsertDirective, type JsonValue, type JwtPayload, type LifecycleEvent, type LifecycleType, type MemoryCache, type MemoryCacheOptions, type MemoryCacheSetOptions, NavAction, NavResult, type NormalizedResult, type PassQuizResults, type PlacesMessageKey, type PlacesMessages, type Predicate, type PredicateOp, type ProgressInfo, type ProgressModeInfo, type QuestionMetrics, type QuizBandDefinition, type QuizConfig, type QuizOutcomeModel, type QuizPassFailConfig, type QuizQuestionInput, type QuizQuestionModel, type QuizQuestionResult, type QuizQuestionState, type QuizResults, type QuizScoringModel, type QuizSectionConfig, type QuizSectionResults, type RequestSnapshot, type ResolveValueSources, type ScoreQuizResults, type SessionState, type ShareConfig, type SimplePredicate, type SplitConfig, type StepState, type StorageAccessor, SurveyDefinition, SurveyEngine, SurveyEngineOptions, SurveyErrors, SurveyField, SurveyFieldRule, SurveyOption, type SurveyOptions, SurveySnapshot, SurveyState, SurveyStatus, SurveyStep, SurveyStepQuiz, SurveyStepRule, SurveyValidator, SurveyView, type TrackingConfig, type Utms, VISITOR_ID_STORAGE_KEY, type ValidationRule, type Validators, type ValueResolver, type WeightedQuizResults, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildBasinFormData, buildContext, buildCounterPayload, buildFcrmUtms, buildSurveySnapshot, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, computeProgress, createAttemptStore, createLifecycleBus, createMemoryCache, createSessionStore, createStepsStore, createSurveyEngine, createTrackingConsumer, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, deriveQuizInputs, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, firstDefined, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, hashSurveySnapshot, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, mapTrackingEvent, matchesFormat, mergeAnswers, normalizeResult, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, parseSurveyDefinition, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, snapshot, surveyDefinitionSchema, unknownResult, updateUrlWithParams, validators };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,6 @@
 import { atom } from "nanostores";
 import log from "loglevel";
+import { z } from "zod";
 //#region src/stores.ts
 function createSessionStore(initial) {
 	return atom({
@@ -754,6 +755,54 @@ async function fetchBasinJWT(endpoint, storage, storageKey, options = {}) {
 	}
 }
 //#endregion
+//#region src/basin-submission.ts
+function normalizePiiKey(key) {
+	const lower = key.toLowerCase();
+	return lower.endsWith("-display") ? lower.slice(0, -8) : lower;
+}
+function stableSerialize(value) {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`;
+	if (typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(String(value));
+}
+function hashSurveySnapshot(snapshot) {
+	const stable = stableSerialize({
+		current: snapshot.current,
+		path: snapshot.path,
+		answers: snapshot.answers
+	});
+	let hash = 2166136261;
+	for (let index = 0; index < stable.length; index += 1) {
+		hash ^= stable.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function buildBasinFormData(input) {
+	const formData = new FormData();
+	const stripFields = input.stripFields ? new Set(Array.from(input.stripFields, normalizePiiKey)) : null;
+	for (const [name, value] of Object.entries(input.snapshot.answers)) {
+		if (stripFields?.has(normalizePiiKey(name))) continue;
+		formData.append(name, value);
+	}
+	formData.append("frombasinjs", "true");
+	formData.append("_gotcha", "");
+	const email = formData.get("email");
+	if (typeof email !== "string" || email.trim() === "") formData.set("email", input.anonymousEmail);
+	for (const [name, value] of Object.entries(input.utms)) formData.append(name, value);
+	if (input.jwt.trim() !== "") formData.append("basinjwt", input.jwt);
+	formData.append("basinjsmultistep", "true");
+	formData.append("basinjsdraft", input.final ? "false" : "true");
+	if (!input.final) formData.append("basinjsstep", String(input.step));
+	return formData;
+}
+//#endregion
 //#region src/lifecycle.ts
 function unknownResult(delivery = "unobserved") {
 	return {
@@ -1566,6 +1615,719 @@ function matchesFormat(example, value) {
 	return example === value;
 }
 //#endregion
-export { CRM_CONTACT_KEYS, VISITOR_ID_STORAGE_KEY, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createAttemptStore, createLifecycleBus, createMemoryCache, createSessionStore, createStepsStore, createTrackingConsumer, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, firstDefined, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, mapTrackingEvent, matchesFormat, mergeAnswers, normalizeResult, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, snapshot, unknownResult, updateUrlWithParams, validators };
+//#region src/survey/progress.ts
+function stepPassesShowIf(step, answers) {
+	return step.showIf === void 0 || evaluatePredicate(step.showIf, answers);
+}
+function percent(current, total) {
+	if (total === 0) return 0;
+	return Math.round(current / total * 100);
+}
+function computeProgress(definition, state) {
+	if ((definition.progress ?? "static") === "path") {
+		const currentIndex = definition.steps.findIndex((step) => step.id === state.current);
+		const stepsAfterCurrent = currentIndex < 0 ? [] : definition.steps.slice(currentIndex + 1).filter((step) => stepPassesShowIf(step, state.answers));
+		const current = state.path.length;
+		const total = current + stepsAfterCurrent.length;
+		return {
+			current,
+			total,
+			percent: percent(current, total)
+		};
+	}
+	const documentIndex = definition.steps.findIndex((step) => step.id === state.current);
+	const current = documentIndex >= 0 ? documentIndex + 1 : 1;
+	const total = definition.steps.length;
+	return {
+		current,
+		total,
+		percent: percent(current, total)
+	};
+}
+//#endregion
+//#region src/survey/quiz.ts
+function answeredValuesForStep(step, state) {
+	if (!step.name) return [];
+	const answer = state.answers[step.name];
+	if (step.quiz?.model === "single_select") return typeof answer === "string" ? [answer] : [];
+	return Array.isArray(answer) ? answer.filter((value) => typeof value === "string") : [];
+}
+function weightedScoresForValues(values, step) {
+	const scores = {};
+	for (const value of values) {
+		const option = step.options?.find((candidate) => candidate.value === value);
+		if (!option?.weights) continue;
+		for (const [category, weight] of Object.entries(option.weights)) scores[category] = (scores[category] ?? 0) + weight;
+	}
+	return scores;
+}
+function labelsForValues(values, step) {
+	return values.map((value) => step.options?.find((option) => option.value === value)?.label ?? value);
+}
+function deriveQuizInputs(definition, state) {
+	const pathIds = new Set(state.path);
+	return definition.steps.flatMap((step) => {
+		if (!step.quiz) return [];
+		const answeredValues = answeredValuesForStep(step, state);
+		const correctOptions = (step.options ?? []).filter((option) => option.correct);
+		const expectedValues = correctOptions.length > 0 ? correctOptions.map((option) => option.value) : null;
+		const expectedLabels = correctOptions.length > 0 ? correctOptions.map((option) => option.label ?? option.value) : null;
+		return [{
+			key: step.name ?? step.id,
+			model: step.quiz.model,
+			section: step.quiz.section ?? null,
+			eligible: pathIds.has(step.id),
+			answeredValues,
+			answeredLabels: labelsForValues(answeredValues, step),
+			expectedValues,
+			expectedLabels,
+			scoringModel: step.quiz.scoring ?? (expectedValues ? "exact" : null),
+			usesWeightedScoring: (step.options ?? []).some((option) => option.weights !== void 0),
+			weightedScores: weightedScoresForValues(answeredValues, step)
+		}];
+	});
+}
+//#endregion
+//#region src/survey/snapshot.ts
+function stringifyAnswer(value) {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value.join(", ");
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "true" : "false";
+}
+function addAnswer(output, answers, name) {
+	const value = stringifyAnswer(answers[name]);
+	if (value !== void 0) output[name] = value;
+}
+function addStepAnswers(output, answers, step) {
+	if (step.kind === "fields") {
+		for (const field of step.fields ?? []) addAnswer(output, answers, field.name);
+		return;
+	}
+	if (step.name) {
+		addAnswer(output, answers, step.name);
+		if (step.kind === "single" || step.kind === "multi") {
+			const selected = answers[step.name];
+			const selectedValues = typeof selected === "string" ? [selected] : Array.isArray(selected) && selected.every((value) => typeof value === "string") ? selected : [];
+			const otherOption = step.options?.find((option) => option.other === true && selectedValues.includes(option.value));
+			const otherAnswer = answers[`${step.name}_other`];
+			if (otherOption && typeof otherAnswer === "string" && otherAnswer.trim() !== "") addAnswer(output, answers, `${step.name}_other`);
+		}
+	}
+}
+function buildSurveySnapshot(definition, state) {
+	const pathIds = new Set(state.path);
+	const answers = {};
+	for (const step of definition.steps) if (pathIds.has(step.id)) addStepAnswers(answers, state.answers, step);
+	return {
+		definitionId: state.definitionId,
+		sessionId: state.sessionId,
+		current: state.current,
+		path: [...state.path],
+		answers
+	};
+}
+//#endregion
+//#region src/survey/validate.ts
+function isEmpty(value) {
+	if (value === void 0 || value === null) return true;
+	if (typeof value === "string") return value.trim() === "";
+	return Array.isArray(value) && value.length === 0;
+}
+function asString(value) {
+	if (typeof value === "string") return value;
+	if (value === void 0 || value === null) return "";
+	return String(value);
+}
+function replaceMessage(template, replacements) {
+	return Object.entries(replacements).reduce((message, [key, replacement]) => message.replaceAll(`{${key}}`, replacement), template);
+}
+function getMessage(lang, key, replacements = {}) {
+	const messages = getErrorMessagesForLanguage(lang);
+	const fallbackKey = key === "postal" ? "pattern" : key;
+	return replaceMessage(messages[key] ?? messages[fallbackKey] ?? messages.required ?? "Invalid value", {
+		...key === "phone" ? { example: getPhoneExample() } : {},
+		...replacements
+	});
+}
+function addError(errors, key, message) {
+	if (errors[key] === void 0) errors[key] = message;
+}
+function validateRequired(value, key, lang, errors) {
+	if (isEmpty(value)) addError(errors, key, getMessage(lang, "required"));
+}
+function validateStepRule(rule, value, key, lang, errors) {
+	if (rule.rule === "required") {
+		validateRequired(value, key, lang, errors);
+		return;
+	}
+	const selectedCount = Array.isArray(value) ? value.length : 0;
+	if (rule.rule === "minSelected" && selectedCount < rule.arg) {
+		addError(errors, key, getMessage(lang, "minValue", { minValue: String(rule.arg) }));
+		return;
+	}
+	if (rule.rule === "maxSelected" && selectedCount > rule.arg) addError(errors, key, getMessage(lang, "maxValue", { maxValue: String(rule.arg) }));
+}
+function validateScale(step, value, key, lang, errors) {
+	if (!step.scale) return;
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		addError(errors, key, getMessage(lang, "minValue", { minValue: String(step.scale.min) }));
+		return;
+	}
+	if (value < step.scale.min) {
+		addError(errors, key, getMessage(lang, "minValue", { minValue: String(step.scale.min) }));
+		return;
+	}
+	if (value > step.scale.max) addError(errors, key, getMessage(lang, "maxValue", { maxValue: String(step.scale.max) }));
+}
+function phoneIsValid(value) {
+	const stripped = value.replace(/[\s()+-]/g, "");
+	return /^\d{6,15}$/.test(stripped);
+}
+function postalIsValid(value) {
+	return /^\d{4}$/.test(value);
+}
+function fieldRuleIsValid(rule, value) {
+	if (typeof rule === "string") {
+		const stringValue = asString(value);
+		switch (rule) {
+			case "required": return !isEmpty(value);
+			case "email": return validators.email(stringValue);
+			case "name": return validators.name(stringValue);
+			case "phone": return phoneIsValid(stringValue);
+			case "postal": return postalIsValid(stringValue);
+		}
+	}
+	const stringValue = asString(value);
+	return validators[rule.rule](stringValue, rule.arg);
+}
+function fieldRuleMessage(rule, lang) {
+	if (typeof rule === "string") return getMessage(lang, rule);
+	if (rule.rule === "pattern") return getMessage(lang, "pattern");
+	return getMessage(lang, rule.rule, { [rule.rule]: rule.arg });
+}
+function validateSurveyStep(step, answers, lang) {
+	const errors = {};
+	if (step.kind === "fields") {
+		for (const field of step.fields ?? []) {
+			const value = answers[field.name];
+			for (const rule of field.rules ?? []) {
+				if (fieldRuleIsValid(rule, value)) continue;
+				addError(errors, field.name, fieldRuleMessage(rule, lang));
+				break;
+			}
+		}
+		return Object.keys(errors).length > 0 ? errors : null;
+	}
+	const key = step.name;
+	if (!key) return null;
+	const value = answers[key];
+	for (const rule of step.validate ?? []) validateStepRule(rule, value, key, lang, errors);
+	if (step.kind === "scale") validateScale(step, value, key, lang, errors);
+	return Object.keys(errors).length > 0 ? errors : null;
+}
+//#endregion
+//#region src/survey/engine.ts
+function cloneValue(value, seen = /* @__PURE__ */ new WeakMap()) {
+	if (value === null || typeof value !== "object") return value;
+	const existing = seen.get(value);
+	if (existing !== void 0) return existing;
+	if (value instanceof Date) return new Date(value.getTime());
+	if (Array.isArray(value)) {
+		const copy = [];
+		seen.set(value, copy);
+		for (const item of value) copy.push(cloneValue(item, seen));
+		return copy;
+	}
+	const copy = {};
+	seen.set(value, copy);
+	for (const [key, item] of Object.entries(value)) copy[key] = cloneValue(item, seen);
+	return copy;
+}
+function cloneState(state) {
+	return {
+		version: state.version,
+		definitionId: state.definitionId,
+		current: state.current,
+		path: [...state.path],
+		answers: cloneValue(state.answers),
+		status: state.status,
+		sessionId: state.sessionId
+	};
+}
+function randomSessionId() {
+	const cryptoApi = globalThis.crypto;
+	if (cryptoApi && typeof cryptoApi.randomUUID === "function") return cryptoApi.randomUUID();
+	if (cryptoApi && typeof cryptoApi.getRandomValues === "function") {
+		const bytes = cryptoApi.getRandomValues(new Uint8Array(8));
+		return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	}
+	return Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+}
+function findStep(definition, id) {
+	return definition.steps.find((step) => step.id === id);
+}
+function getInitialStep(definition, answers) {
+	return definition.steps.find((step) => stepPassesShowIf(step, answers)) ?? definition.steps[0];
+}
+function restoreOrCreateState(definition, options, sessionId) {
+	const initialState = options.initialState;
+	if (initialState?.definitionId === definition.id && findStep(definition, initialState.current)) return {
+		...cloneState(initialState),
+		sessionId
+	};
+	const current = getInitialStep(definition, {});
+	return {
+		version: 1,
+		definitionId: definition.id,
+		current: current.id,
+		path: [current.id],
+		answers: {},
+		status: "idle",
+		sessionId
+	};
+}
+function findNextVisibleStep(definition, index, answers) {
+	return definition.steps.slice(index + 1).find((step) => stepPassesShowIf(step, answers));
+}
+function resolveDestination(definition, current, action, answers) {
+	if (action.kind === "goto") {
+		const target = findStep(definition, action.target);
+		if (!target) return { kind: "noop" };
+		if (current.terminal) return { kind: "submit" };
+		if (stepPassesShowIf(target, answers)) return {
+			kind: "step",
+			id: target.id,
+			truncate: true
+		};
+		const next = findNextVisibleStep(definition, definition.steps.findIndex((step) => step.id === target.id), answers);
+		return next ? {
+			kind: "step",
+			id: next.id,
+			truncate: false
+		} : { kind: "submit" };
+	}
+	if (action.kind === "redirect") return {
+		kind: "submit",
+		redirect: action.target
+	};
+	if (current.terminal) return { kind: "submit" };
+	const next = findNextVisibleStep(definition, definition.steps.findIndex((step) => step.id === current.id), answers);
+	return next ? {
+		kind: "step",
+		id: next.id,
+		truncate: false
+	} : { kind: "submit" };
+}
+function submissionResult(redirect) {
+	return redirect === void 0 ? { kind: "submit" } : {
+		kind: "submit",
+		redirect
+	};
+}
+function createSurveyEngine(definition, options = {}) {
+	if (definition.steps.length === 0) throw new Error("A survey definition must contain at least one step");
+	const ids = /* @__PURE__ */ new Set();
+	for (const step of definition.steps) {
+		if (ids.has(step.id)) throw new Error(`Duplicate survey step id: ${step.id}`);
+		ids.add(step.id);
+	}
+	let state = restoreOrCreateState(definition, options, options.sessionId ?? options.initialState?.sessionId ?? randomSessionId());
+	let errors = {};
+	let revision = 0;
+	const listeners = /* @__PURE__ */ new Set();
+	function notify() {
+		for (const listener of listeners) try {
+			listener();
+		} catch {}
+	}
+	function replaceState(next) {
+		state = cloneState(next);
+		revision += 1;
+		notify();
+	}
+	function replaceErrors(next) {
+		errors = { ...next };
+		notify();
+	}
+	function clearErrors() {
+		if (Object.keys(errors).length === 0) return;
+		errors = {};
+	}
+	function currentStep() {
+		return findStep(definition, state.current) ?? definition.steps[0];
+	}
+	function isNavigationBlocked() {
+		return state.status === "submitting" || state.status === "done";
+	}
+	function applyAnswer(name, value) {
+		clearErrors();
+		replaceState({
+			...state,
+			answers: {
+				...state.answers,
+				[name]: cloneValue(value)
+			}
+		});
+	}
+	function moveTo(id, truncate) {
+		const pathIndex = truncate ? state.path.lastIndexOf(id) : -1;
+		const path = pathIndex >= 0 ? state.path.slice(0, pathIndex + 1) : [...state.path, id];
+		if (state.current === id && path.length === state.path.length) return {
+			kind: "moved",
+			to: id
+		};
+		clearErrors();
+		replaceState({
+			...state,
+			current: id,
+			path
+		});
+		return {
+			kind: "moved",
+			to: id
+		};
+	}
+	function applyDestination(destination) {
+		if (destination.kind === "noop") return { kind: "noop" };
+		if (destination.kind === "submit") {
+			replaceState({
+				...state,
+				status: "submitting"
+			});
+			return submissionResult(destination.redirect);
+		}
+		return moveTo(destination.id, destination.truncate);
+	}
+	function resolveAction(step, value, explicitNav) {
+		if (explicitNav) return explicitNav;
+		if (step.kind === "single" && typeof value === "string") {
+			const optionNav = step.options?.find((option) => option.value === value)?.nav;
+			if (optionNav) return optionNav;
+		}
+		return step.nav ?? { kind: "next" };
+	}
+	async function validateBeforeMove(step, answers) {
+		const builtInErrors = validateSurveyStep(step, answers, definition.lang);
+		if (builtInErrors) return builtInErrors;
+		if (!options.validate) return null;
+		return options.validate({
+			step: cloneValue(step),
+			answers: cloneValue(answers),
+			lang: definition.lang
+		});
+	}
+	async function next(nav) {
+		if (isNavigationBlocked()) return { kind: "noop" };
+		const step = currentStep();
+		const answers = cloneValue(state.answers);
+		const capturedRevision = revision;
+		const validationErrors = await validateBeforeMove(step, answers);
+		if (revision !== capturedRevision) return { kind: "stale" };
+		if (validationErrors && Object.keys(validationErrors).length > 0) {
+			replaceErrors(validationErrors);
+			return {
+				kind: "blocked",
+				errors: { ...validationErrors }
+			};
+		}
+		return applyDestination(resolveDestination(definition, step, resolveAction(step, step.name ? answers[step.name] : void 0, nav), answers));
+	}
+	async function choose(name, value, nav) {
+		if (isNavigationBlocked()) return { kind: "noop" };
+		const step = currentStep();
+		applyAnswer(name, value);
+		const answers = cloneValue(state.answers);
+		const capturedRevision = revision;
+		const validationErrors = await validateBeforeMove(step, answers);
+		if (revision !== capturedRevision) return { kind: "stale" };
+		if (validationErrors && Object.keys(validationErrors).length > 0) {
+			replaceErrors(validationErrors);
+			return {
+				kind: "blocked",
+				errors: { ...validationErrors }
+			};
+		}
+		return applyDestination(resolveDestination(definition, step, resolveAction(step, value, nav), answers));
+	}
+	function back() {
+		if (isNavigationBlocked()) return { kind: "noop" };
+		if (currentStep().back === false || state.path.length <= 1) return { kind: "noop" };
+		const path = state.path.slice(0, -1);
+		const previous = path[path.length - 1];
+		if (!previous) return { kind: "noop" };
+		clearErrors();
+		replaceState({
+			...state,
+			current: previous,
+			path
+		});
+		return {
+			kind: "moved",
+			to: previous
+		};
+	}
+	function goto(id) {
+		if (isNavigationBlocked()) return { kind: "noop" };
+		const step = currentStep();
+		const answers = cloneValue(state.answers);
+		return applyDestination(resolveDestination(definition, step, {
+			kind: "goto",
+			target: id
+		}, answers));
+	}
+	function getState() {
+		return cloneState(state);
+	}
+	function getView() {
+		const step = currentStep();
+		const inputs = deriveQuizInputs(definition, state);
+		return {
+			step: cloneValue(step),
+			index: definition.steps.findIndex((candidate) => candidate.id === step.id),
+			canBack: !isNavigationBlocked() && state.path.length > 1 && step.back !== false,
+			isTerminal: step.terminal === true,
+			progress: computeProgress(definition, state),
+			errors: { ...errors },
+			quiz: inputs.length > 0 ? scoreQuiz(inputs, definition.quiz ?? {}) : null
+		};
+	}
+	function subscribe(listener) {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	function answer(name, value) {
+		applyAnswer(name, value);
+	}
+	function snapshot() {
+		return buildSurveySnapshot(definition, state);
+	}
+	function setStatus(status) {
+		replaceState({
+			...state,
+			status
+		});
+	}
+	return {
+		getState,
+		getView,
+		subscribe,
+		answer,
+		choose,
+		next,
+		back,
+		goto,
+		snapshot,
+		setStatus
+	};
+}
+//#endregion
+//#region src/survey/schema.ts
+const predicateOpSchema = z.enum([
+	"eq",
+	"neq",
+	"in",
+	"nin",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"exists",
+	"truthy",
+	"falsy",
+	"contains",
+	"starts_with",
+	"ends_with"
+]);
+const predicateSchema = z.lazy(() => z.union([z.object({
+	field: z.string(),
+	op: predicateOpSchema,
+	value: z.unknown().optional()
+}), z.object({
+	all: z.array(predicateSchema).optional(),
+	any: z.array(predicateSchema).optional(),
+	not: predicateSchema.optional()
+}).refine((predicate) => predicate.all !== void 0 || predicate.any !== void 0 || predicate.not !== void 0)]));
+const navActionSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("next") }),
+	z.object({
+		kind: z.literal("goto"),
+		target: z.string()
+	}),
+	z.object({
+		kind: z.literal("redirect"),
+		target: z.string()
+	})
+]);
+const surveyOptionSchema = z.object({
+	value: z.string(),
+	label: z.string().optional(),
+	nav: navActionSchema.optional(),
+	correct: z.boolean().optional(),
+	weights: z.record(z.string(), z.number()).optional(),
+	other: z.boolean().optional()
+});
+const surveyFieldRuleSchema = z.union([z.enum([
+	"required",
+	"email",
+	"name",
+	"phone",
+	"postal"
+]), z.object({
+	rule: z.enum([
+		"pattern",
+		"min",
+		"max"
+	]),
+	arg: z.string()
+})]);
+const surveyFieldSchema = z.object({
+	name: z.string(),
+	type: z.enum([
+		"text",
+		"email",
+		"tel",
+		"textarea",
+		"postal",
+		"address"
+	]),
+	rules: z.array(surveyFieldRuleSchema).optional()
+});
+const surveyStepRuleSchema = z.union([z.object({ rule: z.literal("required") }), z.object({
+	rule: z.enum(["minSelected", "maxSelected"]),
+	arg: z.number()
+})]);
+const surveyStepQuizSchema = z.object({
+	model: z.enum(["single_select", "multi_select"]),
+	section: z.string().optional(),
+	scoring: z.enum(["exact", "partial"]).optional()
+});
+const quizPassFailSchema = z.object({ percentGte: z.number() });
+const quizBandSchema = z.object({
+	id: z.string(),
+	label: z.string(),
+	minPercent: z.number().optional(),
+	maxPercent: z.number().optional()
+});
+const quizSectionSchema = z.object({
+	passFail: quizPassFailSchema.nullable().optional(),
+	bands: z.array(quizBandSchema).nullable().optional()
+});
+const quizConfigSchema = z.object({
+	passFail: quizPassFailSchema.nullable().optional(),
+	bands: z.array(quizBandSchema).nullable().optional(),
+	sections: z.record(z.string(), quizSectionSchema).nullable().optional()
+});
+const surveyStepSchema = z.object({
+	id: z.string(),
+	kind: z.enum([
+		"content",
+		"single",
+		"multi",
+		"scale",
+		"fields"
+	]),
+	name: z.string().optional(),
+	showIf: predicateSchema.optional(),
+	back: z.boolean().optional(),
+	terminal: z.boolean().optional(),
+	nav: navActionSchema.optional(),
+	options: z.array(surveyOptionSchema).optional(),
+	scale: z.object({
+		min: z.number(),
+		max: z.number(),
+		step: z.number().optional()
+	}).optional(),
+	fields: z.array(surveyFieldSchema).optional(),
+	validate: z.array(surveyStepRuleSchema).optional(),
+	quiz: surveyStepQuizSchema.optional()
+});
+const surveyDefinitionSchema = z.object({
+	version: z.literal(1),
+	id: z.string(),
+	steps: z.array(surveyStepSchema),
+	progress: z.enum(["static", "path"]).optional(),
+	quiz: quizConfigSchema.optional(),
+	lang: z.string().optional()
+}).superRefine((definition, context) => {
+	const ids = /* @__PURE__ */ new Set();
+	definition.steps.forEach((step, index) => {
+		if (ids.has(step.id)) context.addIssue({
+			code: "custom",
+			message: `Duplicate step id: ${step.id}`,
+			path: [
+				"steps",
+				index,
+				"id"
+			]
+		});
+		ids.add(step.id);
+		if ((step.kind === "single" || step.kind === "multi" || step.kind === "scale") && !step.name) context.addIssue({
+			code: "custom",
+			message: `Step "${step.id}" requires a name`,
+			path: [
+				"steps",
+				index,
+				"name"
+			]
+		});
+		if ((step.kind === "single" || step.kind === "multi") && step.options === void 0) context.addIssue({
+			code: "custom",
+			message: `Step "${step.id}" requires options`,
+			path: [
+				"steps",
+				index,
+				"options"
+			]
+		});
+		if (step.kind === "scale" && step.scale === void 0) context.addIssue({
+			code: "custom",
+			message: `Step "${step.id}" requires scale`,
+			path: [
+				"steps",
+				index,
+				"scale"
+			]
+		});
+		if (step.kind === "fields" && step.fields === void 0) context.addIssue({
+			code: "custom",
+			message: `Step "${step.id}" requires fields`,
+			path: [
+				"steps",
+				index,
+				"fields"
+			]
+		});
+	});
+	const knownIds = new Set(definition.steps.map((step) => step.id));
+	const checkNav = (nav, path) => {
+		if (nav?.kind === "goto" && !knownIds.has(nav.target)) context.addIssue({
+			code: "custom",
+			message: `Unknown goto target: ${nav.target}`,
+			path
+		});
+	};
+	definition.steps.forEach((step, index) => {
+		checkNav(step.nav, [
+			"steps",
+			index,
+			"nav"
+		]);
+		for (const [optionIndex, option] of (step.options ?? []).entries()) checkNav(option.nav, [
+			"steps",
+			index,
+			"options",
+			optionIndex,
+			"nav"
+		]);
+	});
+});
+function parseSurveyDefinition(input) {
+	return surveyDefinitionSchema.parse(input);
+}
+//#endregion
+export { CRM_CONTACT_KEYS, VISITOR_ID_STORAGE_KEY, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildBasinFormData, buildContext, buildCounterPayload, buildFcrmUtms, buildSurveySnapshot, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, computeProgress, createAttemptStore, createLifecycleBus, createMemoryCache, createSessionStore, createStepsStore, createSurveyEngine, createTrackingConsumer, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, deriveQuizInputs, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, firstDefined, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, hashSurveySnapshot, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, mapTrackingEvent, matchesFormat, mergeAnswers, normalizeResult, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, parseSurveyDefinition, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, snapshot, surveyDefinitionSchema, unknownResult, updateUrlWithParams, validators };
 
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@reform-society/agera-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "DOM-free core logic for Agera",
   "type": "module",
+  "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -42,6 +43,7 @@
   },
   "dependencies": {
     "loglevel": "^1.9.2",
-    "nanostores": "^1.5.2"
+    "nanostores": "^1.5.2",
+    "zod": "^4.1.0"
   }
 }