@reform-society/agera-core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -204,6 +204,8 @@ declare function calculateSectionResults(questions: QuizQuestionInput[], questio
 declare function scoreQuiz(questions: QuizQuestionInput[], config?: QuizConfig): QuizResults;
 //#endregion
 //#region src/basin-client.d.ts
+type JwtPayload = Record<string, unknown>;
+declare function decodeJwtPayload(jwt: string): JwtPayload | null;
 /** Check if JWT is expired (with 60s buffer) */
 declare function isJwtExpired(jwt: string): boolean;
 type StorageAccessor = {
@@ -211,7 +213,10 @@ type StorageAccessor = {
   setItem(key: string, value: string): void;
   removeItem(key: string): void;
 };
-declare function fetchBasinJWT(endpoint: string, storage: StorageAccessor, storageKey: string): Promise<string>;
+type FetchBasinJWTOptions = {
+  isCachedJwtValid?: (jwt: string) => boolean;
+};
+declare function fetchBasinJWT(endpoint: string, storage: StorageAccessor, storageKey: string, options?: FetchBasinJWTOptions): Promise<string>;
 //#endregion
 //#region src/crm-types.d.ts
 type CounterUpdateConfig = {
@@ -262,11 +267,55 @@ type CrmV2Request = {
 type CrmV2PatchRequest = CrmV2Request & {
   response: Record<string, unknown>;
 };
+type CrmV2Payload = CrmV2Request & {
+  response?: Record<string, unknown>;
+};
 type CrmFetchResult = {
   ok: boolean;
   status: number;
   data: Record<string, unknown> | null;
 };
+type CrmCommand = {
+  client: string;
+  payload: CrmV2Payload;
+  method?: "POST" | "PUT" | "PATCH";
+  delivery?: "wait" | "background";
+};
+type CrmDispatch = {
+  client: string;
+  method: "POST" | "PUT" | "PATCH";
+  delivery: "wait" | "background";
+  payload: CrmV2Payload;
+  signal?: AbortSignal;
+};
+type CrmGatewayResult = {
+  kind: "response";
+  response: CrmFetchResult;
+} | {
+  kind: "accepted";
+};
+type CrmGateway = (dispatch: CrmDispatch) => Promise<CrmGatewayResult>;
+type CrmOutcome = {
+  status: "succeeded";
+  httpStatus: number;
+  response: Record<string, unknown> | null;
+} | {
+  status: "accepted";
+} | {
+  status: "rejected";
+  httpStatus: number;
+  response: Record<string, unknown> | null;
+} | {
+  status: "failed";
+  cause: unknown;
+} | {
+  status: "aborted";
+};
+//#endregion
+//#region src/crm-submission.d.ts
+declare function executeCrm(gateway: CrmGateway, command: CrmCommand, options?: {
+  signal?: AbortSignal;
+}): Promise<CrmOutcome>;
 //#endregion
 //#region src/utm.d.ts
 declare const UTM_KEYS: readonly ["source", "campaign", "medium", "content", "term", "wec"];
@@ -347,6 +396,19 @@ type DeviceInput = {
 };
 declare function detectDeviceType(input: DeviceInput): DeviceType;
 //#endregion
+//#region src/visitor.d.ts
+declare const VISITOR_ID_STORAGE_KEY = "agera:vid";
+/**
+ * Read the semi-persistent pseudonymous visitor id from storage, generating
+ * and persisting a new one when absent. Used only to correlate requests from
+ * the same browser in crm-api logs — never stored server-side.
+ *
+ * Returns null when storage can't be read or written (private mode, quota,
+ * blocked storage): an unpersisted id would look like a new visitor on every
+ * page load, so callers omit the header instead.
+ */
+declare function getOrCreateVisitorId(storage: StorageAccessor): string | null;
+//#endregion
 //#region src/crm-fetch.d.ts
 type CrmFetchOptions = {
   waitForResponse?: boolean;
@@ -356,6 +418,22 @@ type CrmFetchOptions = {
 };
 declare function crmFetch(url: string, payload: Record<string, unknown> | object, options?: CrmFetchOptions): Promise<CrmFetchResult>;
 //#endregion
+//#region src/crm-fields.d.ts
+declare const CRM_CONTACT_KEYS: readonly ["given-name", "family-name", "email", "tel", "street-address", "address-level2", "postal-code", "country"];
+type CrmContactKey = (typeof CRM_CONTACT_KEYS)[number];
+declare function isCrmContactKey(key: string): key is CrmContactKey;
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
+type CrmGroupedAnswer = {
+  group: string;
+  name: string;
+  value: JsonValue;
+};
+type CrmJsonGroups = Record<string, Record<string, JsonValue>>;
+declare function groupCrmAnswers(answers: readonly CrmGroupedAnswer[]): CrmJsonGroups;
+declare function serializeCrmJsonGroups(groups: CrmJsonGroups): string | undefined;
+//#endregion
 //#region src/crm-request.d.ts
 type AssembleCrmRequestParams = {
   body: Record<string, unknown>;
@@ -365,7 +443,7 @@ type AssembleCrmRequestParams = {
   queryParams: Record<string, string>;
   sourceUrl: string;
   counters?: CounterUpdateConfig[];
-  jsonGroups?: Record<string, Record<string, string>>;
+  jsonGroups?: CrmJsonGroups;
 };
 declare function assembleCrmRequest({
   body: rawBody,
@@ -381,5 +459,5 @@ declare function assembleCrmRequest({
 //#region src/polling.d.ts
 declare function matchesFormat(example: unknown, value: unknown): boolean;
 //#endregion
-export { type AssembleCrmRequestParams, type BandQuizResults, type CompositePredicate, type CounterDisplayConfig, type CounterPayload, type CounterResponse, type CounterUpdateConfig, type CrmConfig, type CrmFetchOptions, type CrmFetchResult, type CrmFrontendKey, type CrmV2PatchRequest, type CrmV2Request, type DeviceInput, type DeviceType, type ErrorMessages, type InsertDirective, type MemoryCache, type MemoryCacheOptions, type MemoryCacheSetOptions, 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 ResolveValueSources, type ScoreQuizResults, type SessionState, type ShareConfig, type SimplePredicate, type SplitConfig, type StepState, type StorageAccessor, type SurveyOptions, type Utms, type ValidationRule, type Validators, type WeightedQuizResults, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createMemoryCache, createSessionStore, createStepsStore, crmFetch, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, extractUtms, fetchBasinJWT, fetchCounter, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, inferCounterName, isCounterResponse, isJwtExpired, isSafeRedirectUrl, matchesFormat, mergeAnswers, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, updateUrlWithParams, validators };
+export { type AssembleCrmRequestParams, 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 FetchBasinJWTOptions, type InsertDirective, type JsonValue, type JwtPayload, type MemoryCache, type MemoryCacheOptions, type MemoryCacheSetOptions, 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 ResolveValueSources, type ScoreQuizResults, type SessionState, type ShareConfig, type SimplePredicate, type SplitConfig, type StepState, type StorageAccessor, type SurveyOptions, type Utms, VISITOR_ID_STORAGE_KEY, type ValidationRule, type Validators, type WeightedQuizResults, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createMemoryCache, createSessionStore, createStepsStore, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, matchesFormat, mergeAnswers, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, updateUrlWithParams, validators };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -111,9 +111,26 @@ function evaluatePredicate(predicate, answers, sources) {
 	}
 	return false;
 }
+/**
+* Parse predicate JSON, tolerating single-quoted JSON.
+*
+* Webflow's Designer API (setCustomAttribute) forbids double quotes in
+* attribute values, so predicates authored via the chat/Logic tab use single
+* quotes — e.g. {'field':'plan','op':'eq','value':'pro'}. Strict JSON is tried
+* first (fully backwards compatible); single-quote normalization is a fallback.
+*/
+function parsePredicateJson(json) {
+	try {
+		return JSON.parse(json);
+	} catch {
+		const sentinel = String.fromCharCode(0);
+		const normalized = json.replace(/\\'/g, sentinel).replace(/'/g, "\"").split(sentinel).join("'");
+		return JSON.parse(normalized);
+	}
+}
 function evaluateShowIf(predicateJson, answers, sources) {
 	try {
-		return evaluatePredicate(JSON.parse(predicateJson), answers, sources);
+		return evaluatePredicate(parsePredicateJson(predicateJson), answers, sources);
 	} catch (error) {
 		log.error("[conditions] Invalid predicate JSON:", error);
 		return false;
@@ -121,7 +138,7 @@ function evaluateShowIf(predicateJson, answers, sources) {
 }
 function evaluateNextMap(nextMapJson, answers, sources) {
 	try {
-		const nextMap = JSON.parse(nextMapJson);
+		const nextMap = parsePredicateJson(nextMapJson);
 		for (const rule of nextMap) if (evaluatePredicate(rule.if, answers, sources)) return rule.then;
 		return null;
 	} catch (error) {
@@ -664,21 +681,55 @@ function scoreQuiz(questions, config = {}) {
 }
 //#endregion
 //#region src/basin-client.ts
-/** Check if JWT is expired (with 60s buffer) */
-function isJwtExpired(jwt) {
+function decodeBase64Url(value) {
+	const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+	return atob(padded);
+}
+function decodeJwtPayload(jwt) {
 	try {
 		const payload = jwt.split(".")[1];
-		if (!payload) return true;
-		const { exp } = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
-		return typeof exp === "number" && exp <= Date.now() / 1e3 + 60;
+		if (!payload) return null;
+		const parsed = JSON.parse(decodeBase64Url(payload));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		return parsed;
 	} catch {
-		return true;
+		return null;
+	}
+}
+/** Check if JWT is expired (with 60s buffer) */
+function isJwtExpired(jwt) {
+	const payload = decodeJwtPayload(jwt);
+	if (!payload) return true;
+	if (typeof payload.exp !== "number") return true;
+	return payload.exp <= Date.now() / 1e3 + 60;
+}
+function getStoredJwt(storage, storageKey) {
+	try {
+		return storage.getItem(storageKey);
+	} catch (error) {
+		log.debug("[basin] Failed to read cached JWT:", error);
+		return null;
+	}
+}
+function removeStoredJwt(storage, storageKey) {
+	try {
+		storage.removeItem(storageKey);
+	} catch (error) {
+		log.debug("[basin] Failed to remove cached JWT:", error);
+	}
+}
+function setStoredJwt(storage, storageKey, jwt) {
+	try {
+		storage.setItem(storageKey, jwt);
+	} catch (error) {
+		log.debug("[basin] Failed to cache JWT:", error);
 	}
 }
-async function fetchBasinJWT(endpoint, storage, storageKey) {
-	const cached = storage.getItem(storageKey);
-	if (cached && !isJwtExpired(cached)) return cached;
-	if (cached) storage.removeItem(storageKey);
+async function fetchBasinJWT(endpoint, storage, storageKey, options = {}) {
+	const cached = getStoredJwt(storage, storageKey);
+	if (cached && !isJwtExpired(cached) && (options.isCachedJwtValid?.(cached) ?? true)) return cached;
+	if (cached) removeStoredJwt(storage, storageKey);
 	try {
 		const res = await fetch(`${endpoint}/generate_jwt`, {
 			method: "GET",
@@ -693,7 +744,7 @@ async function fetchBasinJWT(endpoint, storage, storageKey) {
 		}
 		const data = await res.json();
 		if (data.jwt) {
-			storage.setItem(storageKey, data.jwt);
+			setStoredJwt(storage, storageKey, data.jwt);
 			return data.jwt;
 		}
 		return "";
@@ -703,6 +754,41 @@ async function fetchBasinJWT(endpoint, storage, storageKey) {
 	}
 }
 //#endregion
+//#region src/crm-submission.ts
+function isAbortError(error) {
+	return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+async function executeCrm(gateway, command, options = {}) {
+	const { signal } = options;
+	if (signal?.aborted) return { status: "aborted" };
+	try {
+		const result = await gateway({
+			client: command.client,
+			method: command.method ?? "POST",
+			delivery: command.delivery ?? "wait",
+			payload: command.payload,
+			signal
+		});
+		if (result.kind === "accepted") return { status: "accepted" };
+		const { ok, status, data } = result.response;
+		return ok ? {
+			status: "succeeded",
+			httpStatus: status,
+			response: data
+		} : {
+			status: "rejected",
+			httpStatus: status,
+			response: data
+		};
+	} catch (error) {
+		if (signal?.aborted || isAbortError(error)) return { status: "aborted" };
+		return {
+			status: "failed",
+			cause: error
+		};
+	}
+}
+//#endregion
 //#region src/utm.ts
 const UTM_KEYS = [
 	"source",
@@ -1029,6 +1115,32 @@ function detectDeviceType(input) {
 	return "desktop";
 }
 //#endregion
+//#region src/visitor.ts
+const VISITOR_ID_STORAGE_KEY = "agera:vid";
+function generateVisitorId() {
+	return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+* Read the semi-persistent pseudonymous visitor id from storage, generating
+* and persisting a new one when absent. Used only to correlate requests from
+* the same browser in crm-api logs — never stored server-side.
+*
+* Returns null when storage can't be read or written (private mode, quota,
+* blocked storage): an unpersisted id would look like a new visitor on every
+* page load, so callers omit the header instead.
+*/
+function getOrCreateVisitorId(storage) {
+	try {
+		const existing = storage.getItem(VISITOR_ID_STORAGE_KEY);
+		if (existing) return existing;
+		const id = generateVisitorId();
+		storage.setItem(VISITOR_ID_STORAGE_KEY, id);
+		return id;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/crm-fetch.ts
 const noop = () => {};
 async function crmFetch(url, payload, options = {}) {
@@ -1076,14 +1188,45 @@ async function crmFetch(url, payload, options = {}) {
 	}
 }
 //#endregion
+//#region src/crm-fields.ts
+const CRM_CONTACT_KEYS = [
+	"given-name",
+	"family-name",
+	"email",
+	"tel",
+	"street-address",
+	"address-level2",
+	"postal-code",
+	"country"
+];
+const crmContactKeySet = new Set(CRM_CONTACT_KEYS);
+function isCrmContactKey(key) {
+	return crmContactKeySet.has(key);
+}
+function groupCrmAnswers(answers) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const { group, name, value } of answers) {
+		if (group === "" || name === "") continue;
+		const fields = groups.get(group) ?? /* @__PURE__ */ new Map();
+		fields.set(name, value);
+		groups.set(group, fields);
+	}
+	return Object.fromEntries([...groups].map(([group, fields]) => [group, Object.fromEntries(fields)]));
+}
+function serializeCrmJsonGroups(groups) {
+	const groupEntries = Object.entries(groups);
+	if (groupEntries.length === 0) return void 0;
+	return JSON.stringify(groupEntries.map(([key, fields]) => ({ [key]: fields })));
+}
+//#endregion
 //#region src/crm-request.ts
 function assembleCrmRequest({ body: rawBody, config, frontendKeys, utms, queryParams, sourceUrl, counters, jsonGroups }) {
 	const configuredCounters = Array.isArray(config.counter_update) ? config.counter_update : void 0;
 	const resolvedCounters = counters ?? configuredCounters;
 	const body = { ...rawBody };
 	if (jsonGroups) {
-		const groupEntries = Object.entries(jsonGroups);
-		if (groupEntries.length > 0) body["json-groups"] = JSON.stringify(groupEntries.map(([key, fields]) => ({ [key]: fields })));
+		const serialized = serializeCrmJsonGroups(jsonGroups);
+		if (serialized !== void 0) body["json-groups"] = serialized;
 	}
 	return {
 		body,
@@ -1117,6 +1260,6 @@ function matchesFormat(example, value) {
 	return example === value;
 }
 //#endregion
-export { aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createMemoryCache, createSessionStore, createStepsStore, crmFetch, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, extractUtms, fetchBasinJWT, fetchCounter, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, inferCounterName, isCounterResponse, isJwtExpired, isSafeRedirectUrl, matchesFormat, mergeAnswers, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, updateUrlWithParams, validators };
+export { CRM_CONTACT_KEYS, VISITOR_ID_STORAGE_KEY, aggregateWeightedScores, answersChanged, assembleCrmRequest, buildContext, buildCounterPayload, buildFcrmUtms, calculateScoreResults, calculateSectionResults, calculateWinner, computeAutoTarget, createMemoryCache, createSessionStore, createStepsStore, crmFetch, decodeJwtPayload, deriveBandResults, derivePassResults, deriveQuestionState, detectDeviceType, errorMessages, evaluateNextMap, evaluatePredicate, evaluateShowIf, executeCrm, extractUtms, fetchBasinJWT, fetchCounter, flattenObject, formatCounterValue, getErrorMessagesForLanguage, getOrCreateVisitorId, getPhoneExample, getPlacesMessagesForLanguage, getPostalExample, groupCrmAnswers, inferCounterName, isCounterResponse, isCrmContactKey, isJwtExpired, isSafeRedirectUrl, matchesFormat, mergeAnswers, parseCounterUpdateAttr, parseInsertDirective, parseInsertDirectives, resolveValue, scoreExactQuestion, scorePartialQuestion, scoreQuiz, scoreQuizQuestions, serializeCrmJsonGroups, updateUrlWithParams, validators };
 
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reform-society/agera-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "DOM-free core logic for Agera",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/reform-society/agera-survey-app.git",
+    "url": "git+https://github.com/reform-society/agera.git",
     "directory": "packages/agera-core"
   },
   "author": "Reform Society",
@@ -34,12 +34,14 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "tsdown": "^0.21.8",
-    "vite": "^7.3.2",
-    "vitest": "^4.1.3"
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "tsdown": "^0.21.10",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "7.3.5",
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "loglevel": "^1.9.2",
-    "nanostores": "^1.1.0"
+    "nanostores": "^1.5.2"
   }
 }