@fire-spark/analytics 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+//#region src/types.d.ts
+declare const FUNNEL_EVENTS: readonly ["menu_viewed", "product_viewed", "cart_item_added", "order_placed"];
+declare const INTERACTION_EVENTS: readonly ["product_visited", "category_visited"];
+type FunnelEventName = (typeof FUNNEL_EVENTS)[number];
+type InteractionEventName = (typeof INTERACTION_EVENTS)[number];
+type AnalyticsPlatform = "web" | "ios" | "android";
+type AnalyticsCustomer = {
+  id: string;
+  is_anonymous: boolean;
+};
+type AnalyticsContext = {
+  os_name?: string;
+  os_version?: string;
+  app_version?: string;
+  app_build?: string;
+  device_type?: string;
+  device_model?: string;
+  browser?: string;
+  browser_version?: string;
+  locale?: string;
+  timezone?: string;
+};
+type AnalyticsScope = {
+  store_id?: string;
+  channel_id?: string;
+  brand_id?: string;
+  fulfillment_id?: string;
+};
+type MenuViewedEvent = {
+  name: "menu_viewed";
+  properties?: Record<string, unknown>;
+};
+type ProductViewedEvent = {
+  name: "product_viewed";
+  properties: {
+    product_id: string;
+  };
+};
+type CartItemAddedEvent = {
+  name: "cart_item_added";
+  properties: {
+    product_id: string;
+    quantity: number;
+  };
+};
+type OrderPlacedEvent = {
+  name: "order_placed";
+  properties: {
+    order_id: string;
+    total?: number;
+  };
+};
+type ProductVisitedEvent = {
+  name: "product_visited";
+  properties: {
+    product_id: string;
+    category_id?: string;
+    attribution_source?: string;
+    attribution_id?: string;
+  };
+};
+type CategoryVisitedEvent = {
+  name: "category_visited";
+  properties: {
+    category_id: string;
+  };
+};
+type FunnelTrackEvent = MenuViewedEvent | ProductViewedEvent | CartItemAddedEvent | OrderPlacedEvent;
+type InteractionTrackEvent = ProductVisitedEvent | CategoryVisitedEvent;
+type FreeTrackEvent = {
+  name: string;
+  properties?: Record<string, unknown>;
+};
+type TrackEvent = FunnelTrackEvent | InteractionTrackEvent | FreeTrackEvent;
+type AnalyticsStorage = {
+  getItem: (key: string) => string | null | Promise<string | null>;
+  setItem: (key: string, value: string) => void | Promise<void>;
+  removeItem: (key: string) => void | Promise<void>;
+};
+type AnalyticsLimits = {
+  maxEvents?: number;
+  maxAgeMs?: number;
+  maxBytes?: number;
+};
+type AnalyticsConfigureOptions = {
+  baseUrl?: string;
+  getAccessToken?: () => Promise<string>;
+  storage: AnalyticsStorage;
+  getCustomer: () => AnalyticsCustomer | null;
+  getScope?: () => AnalyticsScope;
+  platform: AnalyticsPlatform;
+  context?: AnalyticsContext;
+  isOnline?: () => boolean | Promise<boolean>;
+  limits?: AnalyticsLimits;
+  fetchImpl?: typeof fetch;
+  sessionMs?: number;
+};
+type AnalyticsConfig = {
+  session: {
+    value: number;
+    unit: "s" | "min" | "h";
+  };
+  session_ms: number;
+};
+declare const isFunnelEventName: (name: string) => name is FunnelEventName;
+declare const isInteractionEventName: (name: string) => name is InteractionEventName;
+//#endregion
+//#region src/flush.d.ts
+declare const flush: () => Promise<void>;
+//#endregion
+//#region src/index.d.ts
+declare const configure: (options: AnalyticsConfigureOptions) => Promise<void>;
+declare const track: (event: TrackEvent) => Promise<void>;
+declare const endSession: () => Promise<void>;
+declare const reset: () => Promise<void>;
+declare const analytics: {
+  configure: typeof configure;
+  track: typeof track;
+  flush: typeof flush;
+  endSession: typeof endSession;
+  reset: typeof reset;
+};
+//#endregion
+export { type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsPlatform, type AnalyticsScope, type AnalyticsStorage, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type TrackEvent, analytics, configure, endSession, isFunnelEventName, isInteractionEventName, reset, track };

package/dist/index.js

@@ -0,0 +1,557 @@
+import { StorefrontHttpError, storefrontJson } from "@fire-spark/core";
+//#region src/context.ts
+const SDK_VERSION = "0.0.1";
+const intlContext = () => {
+	try {
+		const options = Intl.DateTimeFormat().resolvedOptions();
+		return {
+			locale: options.locale,
+			timezone: options.timeZone
+		};
+	} catch {
+		return {};
+	}
+};
+const compact = (context) => {
+	const next = {};
+	for (const [key, raw] of Object.entries(context)) {
+		if (typeof raw !== "string") continue;
+		const value = raw.trim().slice(0, 64);
+		if (value) next[key] = value;
+	}
+	return next;
+};
+const buildEventContext = (context) => {
+	const merged = {
+		...intlContext(),
+		...context
+	};
+	return {
+		...compact(merged),
+		sdk_version: SDK_VERSION
+	};
+};
+//#endregion
+//#region src/retry.ts
+const defaultSleep = (ms) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+};
+/** 1 attempt + `extraAttempts` retries with exponential backoff. */
+const withExponentialRetry = async (run, options = {}) => {
+	const extraAttempts = options.extraAttempts ?? 3;
+	const baseDelayMs = options.baseDelayMs ?? 100;
+	const sleep = options.sleep ?? defaultSleep;
+	const shouldRetry = options.shouldRetry ?? (() => true);
+	let lastError;
+	for (let attempt = 0; attempt <= extraAttempts; attempt += 1) try {
+		return await run();
+	} catch (error) {
+		lastError = error;
+		if (attempt === extraAttempts) break;
+		if (!shouldRetry(error)) break;
+		await sleep(baseDelayMs * 2 ** attempt);
+	}
+	throw lastError;
+};
+//#endregion
+//#region src/types.ts
+const FUNNEL_EVENTS = [
+	"menu_viewed",
+	"product_viewed",
+	"cart_item_added",
+	"order_placed"
+];
+const INTERACTION_EVENTS = ["product_visited", "category_visited"];
+const isFunnelEventName = (name) => {
+	return FUNNEL_EVENTS.includes(name);
+};
+const isInteractionEventName = (name) => {
+	return INTERACTION_EVENTS.includes(name);
+};
+//#endregion
+//#region src/interactions.ts
+const INTERACTIONS_KEY = "firespark:analytics:interactions";
+const interactionKey = (name, entityId) => {
+	return `${name}:${entityId}`;
+};
+const parseInteractions = (raw) => {
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed?.session_id || !Array.isArray(parsed.keys)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+const bindInteractions = (state, sessionId) => {
+	if (!state || state.session_id !== sessionId) return {
+		session_id: sessionId,
+		keys: []
+	};
+	return state;
+};
+const shouldSkipInteraction = (state, name, entityId) => {
+	if (!isInteractionEventName(name) || !entityId) return false;
+	return state.keys.includes(interactionKey(name, entityId));
+};
+const markInteraction = (state, name, entityId) => {
+	if (!isInteractionEventName(name) || !entityId) return state;
+	const key = interactionKey(name, entityId);
+	if (state.keys.includes(key)) return state;
+	const keys = [...state.keys, key].slice(-500);
+	return {
+		...state,
+		keys
+	};
+};
+//#endregion
+//#region src/queue.ts
+const QUEUE_KEY = "firespark:analytics:queue";
+const parseQueue = (raw) => {
+	if (!raw) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((item) => item?.id && item.name && item.session_id);
+	} catch {
+		return [];
+	}
+};
+const eventAgeMs = (event, now) => {
+	const at = Date.parse(event.timestamp);
+	if (!Number.isFinite(at)) return Number.POSITIVE_INFINITY;
+	return now - at;
+};
+const pruneQueue = (events, now, limits) => {
+	let next = events.filter((event) => eventAgeMs(event, now) <= limits.maxAgeMs);
+	if (next.length > limits.maxEvents) next = next.slice(next.length - limits.maxEvents);
+	while (next.length > 0 && JSON.stringify(next).length > limits.maxBytes) next = next.slice(1);
+	return next;
+};
+const enqueueEvent = (events, event, now, limits) => {
+	return pruneQueue([...events, event], now, limits);
+};
+//#endregion
+//#region src/runtime.ts
+const CONFIG_KEY = "firespark:analytics:config";
+const DEFAULT_SESSION_MS = 1800 * 1e3;
+const RETRY_MS = 6e4;
+const runtime = {
+	options: null,
+	context: null,
+	sessionMs: DEFAULT_SESSION_MS,
+	session: null,
+	interactions: null,
+	queue: [],
+	hydrated: false,
+	sessionTimer: null,
+	retryTimer: null
+};
+const getLimits = () => {
+	const limits = runtime.options?.limits;
+	return {
+		maxEvents: limits?.maxEvents ?? 500,
+		maxAgeMs: limits?.maxAgeMs ?? 6048e5,
+		maxBytes: limits?.maxBytes ?? 1e6
+	};
+};
+const readStorage = async (key) => {
+	const storage = runtime.options?.storage;
+	if (!storage) return null;
+	return storage.getItem(key);
+};
+const writeStorage = async (key, value) => {
+	const storage = runtime.options?.storage;
+	if (!storage) return;
+	await storage.setItem(key, value);
+};
+const clearStorage = async (key) => {
+	const storage = runtime.options?.storage;
+	if (!storage) return;
+	await storage.removeItem(key);
+};
+const persistSession = async () => {
+	const key = "firespark:analytics:session";
+	if (!runtime.session) {
+		await clearStorage(key);
+		return;
+	}
+	const p1 = [key, JSON.stringify(runtime.session)];
+	await writeStorage(...p1);
+};
+const persistQueue = async () => {
+	const p1 = ["firespark:analytics:queue", JSON.stringify(runtime.queue)];
+	await writeStorage(...p1);
+};
+const persistConfig = async (sessionMs) => {
+	await writeStorage(CONFIG_KEY, JSON.stringify({ session_ms: sessionMs }));
+};
+const persistInteractions = async () => {
+	if (!runtime.interactions) {
+		await clearStorage(INTERACTIONS_KEY);
+		return;
+	}
+	const p1 = [INTERACTIONS_KEY, JSON.stringify(runtime.interactions)];
+	await writeStorage(...p1);
+};
+const clearTimer = (key) => {
+	const timer = runtime[key];
+	if (timer) clearTimeout(timer);
+	runtime[key] = null;
+};
+const resetRuntime = () => {
+	clearTimer("sessionTimer");
+	clearTimer("retryTimer");
+	runtime.options = null;
+	runtime.context = null;
+	runtime.sessionMs = DEFAULT_SESSION_MS;
+	runtime.session = null;
+	runtime.interactions = null;
+	runtime.queue = [];
+	runtime.hydrated = false;
+};
+//#endregion
+//#region src/flush.ts
+const isPoisonChunk = (error) => {
+	if (!(error instanceof StorefrontHttpError)) return false;
+	return error.status === 400 || error.status === 422;
+};
+const isTransientError = (error) => {
+	if (!(error instanceof StorefrontHttpError)) return true;
+	if (error.status === 429) return true;
+	return error.status >= 500;
+};
+const httpOptions = async () => {
+	const options = runtime.options;
+	if (!options) return {};
+	const accessToken = options.getAccessToken ? await options.getAccessToken() : void 0;
+	return {
+		baseUrl: options.baseUrl,
+		accessToken,
+		fetchImpl: options.fetchImpl
+	};
+};
+const isOnline = async () => {
+	const check = runtime.options?.isOnline;
+	if (!check) return true;
+	return check();
+};
+const postChunk = async (events) => {
+	const http = await httpOptions();
+	return storefrontJson(...[
+		"/api/storefront/v1/analytics/events",
+		{
+			method: "POST",
+			body: JSON.stringify({ events })
+		},
+		http
+	]);
+};
+const scheduleRetry = () => {
+	if (runtime.retryTimer || runtime.queue.length === 0) return;
+	runtime.retryTimer = setTimeout(() => {
+		runtime.retryTimer = null;
+		flush();
+	}, RETRY_MS);
+};
+const preferencesPath = () => {
+	const scope = runtime.options?.getScope?.() ?? {};
+	const params = new URLSearchParams();
+	if (scope.fulfillment_id) params.set("fulfillment_id", scope.fulfillment_id);
+	if (scope.store_id) params.set("store_id", scope.store_id);
+	if (scope.channel_id) params.set("channel_id", scope.channel_id);
+	if (scope.brand_id) params.set("brand_id", scope.brand_id);
+	const query = params.toString();
+	const path = "/api/storefront/v1/preferences";
+	return query ? `${path}?${query}` : path;
+};
+const fetchRemoteConfig = async () => {
+	const http = await httpOptions();
+	return (await storefrontJson(...[
+		preferencesPath(),
+		{ method: "GET" },
+		http
+	])).analytics;
+};
+let flushWait = null;
+const flushOnce = async () => {
+	if (!runtime.options || runtime.queue.length === 0) return;
+	if (!await isOnline()) {
+		scheduleRetry();
+		return;
+	}
+	while (runtime.queue.length > 0) {
+		const chunk = runtime.queue.slice(0, 200);
+		try {
+			await withExponentialRetry(() => postChunk(chunk), { shouldRetry: isTransientError });
+			runtime.queue = runtime.queue.slice(chunk.length);
+			await persistQueue();
+		} catch (error) {
+			if (isPoisonChunk(error)) {
+				runtime.queue = runtime.queue.slice(chunk.length);
+				await persistQueue();
+				continue;
+			}
+			scheduleRetry();
+			return;
+		}
+	}
+	clearTimer("retryTimer");
+};
+const flush = async () => {
+	if (flushWait) return flushWait;
+	flushWait = flushOnce().finally(() => {
+		flushWait = null;
+	});
+	return flushWait;
+};
+//#endregion
+//#region src/uuid.ts
+/** UUID v4 — works when `crypto.randomUUID` is missing (React Native / Hermes). */
+const randomUUID = () => {
+	const c = globalThis.crypto;
+	if (typeof c?.randomUUID === "function") return c.randomUUID();
+	if (typeof c?.getRandomValues !== "function") throw new Error("crypto.getRandomValues is required");
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	c.getRandomValues(bytes);
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const toHex = (b) => b.toString(16).padStart(2, "0");
+	const hex = Array.from(bytes, toHex).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+//#endregion
+//#region src/session.ts
+const SESSION_KEY = "firespark:analytics:session";
+const createSession = (now) => {
+	return {
+		id: randomUUID(),
+		started_at: now,
+		last_event_at: now,
+		seen: []
+	};
+};
+const parseSession = (raw) => {
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed?.id || typeof parsed.last_event_at !== "number") return null;
+		if (!Array.isArray(parsed.seen)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+const isSessionExpired = (session, now, timeoutMs) => {
+	return now - session.last_event_at > timeoutMs;
+};
+const touchSession = (session, now, timeoutMs) => {
+	if (!session || isSessionExpired(session, now, timeoutMs)) return createSession(now);
+	return {
+		...session,
+		last_event_at: now
+	};
+};
+const markSeen = (session, name) => {
+	if (!isFunnelEventName(name)) return session;
+	if (session.seen.includes(name)) return session;
+	return {
+		...session,
+		seen: [...session.seen, name]
+	};
+};
+const shouldSkipFunnelEvent = (session, name) => {
+	return isFunnelEventName(name) && session.seen.includes(name);
+};
+const shouldCarryMenuViewed = (prev, next) => {
+	if (!prev || prev.id === next.id) return false;
+	return prev.seen.includes("menu_viewed");
+};
+//#endregion
+//#region src/index.ts
+const entityIdFromEvent = (event) => {
+	const props = event.properties;
+	if (!props) return void 0;
+	if ("product_id" in props && typeof props.product_id === "string") return props.product_id;
+	if ("category_id" in props && typeof props.category_id === "string") return props.category_id;
+	if ("order_id" in props && typeof props.order_id === "string") return props.order_id;
+};
+const armSessionTimer = () => {
+	clearTimer("sessionTimer");
+	if (!runtime.session) return;
+	const last = runtime.session.last_event_at;
+	const delay = runtime.sessionMs - (Date.now() - last);
+	runtime.sessionTimer = setTimeout(() => {
+		runtime.sessionTimer = null;
+		endSession();
+	}, Math.max(delay, 0));
+};
+const loadPersisted = async () => {
+	if (runtime.hydrated) return;
+	runtime.hydrated = true;
+	runtime.session = parseSession(await readStorage(SESSION_KEY));
+	runtime.queue = parseQueue(await readStorage(QUEUE_KEY));
+	runtime.interactions = parseInteractions(await readStorage(INTERACTIONS_KEY));
+	const rawConfig = await readStorage(CONFIG_KEY);
+	if (!rawConfig) return;
+	try {
+		const parsed = JSON.parse(rawConfig);
+		if (typeof parsed.session_ms === "number" && parsed.session_ms > 0) runtime.sessionMs = parsed.session_ms;
+	} catch {}
+};
+const refreshConfig = async () => {
+	const provided = runtime.options?.sessionMs;
+	if (typeof provided === "number" && provided > 0) {
+		runtime.sessionMs = provided;
+		await persistConfig(runtime.sessionMs);
+		return;
+	}
+	try {
+		runtime.sessionMs = (await fetchRemoteConfig()).session_ms || 18e5;
+		await persistConfig(runtime.sessionMs);
+	} catch {
+		if (!runtime.sessionMs) runtime.sessionMs = DEFAULT_SESSION_MS;
+	}
+};
+const configure = async (options) => {
+	runtime.options = options;
+	runtime.context = buildEventContext(options.context);
+	await loadPersisted();
+	await refreshConfig();
+	armSessionTimer();
+	if (runtime.queue.length > 0) flush();
+};
+const toQueued = (event, now, sessionId, customer) => {
+	const scope = runtime.options?.getScope?.() ?? {};
+	const platform = runtime.options?.platform ?? "web";
+	const b1 = {
+		id: randomUUID(),
+		name: event.name,
+		session_id: sessionId
+	};
+	const b2 = { is_anonymous: customer.is_anonymous };
+	const b3 = { timestamp: new Date(now).toISOString() };
+	const b4 = {
+		store_id: scope.store_id,
+		channel_id: scope.channel_id
+	};
+	const b5 = {
+		brand_id: scope.brand_id,
+		fulfillment_id: scope.fulfillment_id
+	};
+	const b6 = { entity_id: entityIdFromEvent(event) };
+	const b7 = {
+		properties: event.properties,
+		platform
+	};
+	const b8 = { context: runtime.context ?? buildEventContext() };
+	return {
+		...b1,
+		...b2,
+		...b3,
+		...b4,
+		...b5,
+		...b6,
+		...b7,
+		...b8
+	};
+};
+const trackEvent = async (event) => {
+	if (!runtime.options) return;
+	const customer = runtime.options.getCustomer();
+	if (!customer) return;
+	const now = Date.now();
+	const prev = runtime.session;
+	let session = touchSession(prev, now, runtime.sessionMs);
+	if (isInteractionEventName(event.name)) {
+		const entityId = entityIdFromEvent(event);
+		const bound = bindInteractions(runtime.interactions, session.id);
+		if (!entityId || shouldSkipInteraction(bound, event.name, entityId)) {
+			runtime.session = {
+				...session,
+				last_event_at: now
+			};
+			runtime.interactions = bound;
+			await persistSession();
+			await persistInteractions();
+			armSessionTimer();
+			return;
+		}
+		runtime.interactions = markInteraction(bound, event.name, entityId);
+		runtime.session = session;
+		const queued = toQueued(event, now, session.id, customer);
+		runtime.queue = enqueueEvent(runtime.queue, queued, now, getLimits());
+		await persistSession();
+		await persistInteractions();
+		await persistQueue();
+		armSessionTimer();
+		return;
+	}
+	if (shouldCarryMenuViewed(prev, session) && event.name !== "menu_viewed") {
+		session = markSeen(session, "menu_viewed");
+		const p1 = [
+			{ name: "menu_viewed" },
+			now,
+			session.id,
+			customer
+		];
+		const carried = toQueued(...p1);
+		runtime.queue = enqueueEvent(runtime.queue, carried, now, getLimits());
+	}
+	if (shouldSkipFunnelEvent(session, event.name)) {
+		runtime.session = {
+			...session,
+			last_event_at: now
+		};
+		await persistSession();
+		await persistQueue();
+		armSessionTimer();
+		return;
+	}
+	session = markSeen(session, event.name);
+	runtime.session = session;
+	const queued = toQueued(event, now, session.id, customer);
+	runtime.queue = enqueueEvent(runtime.queue, queued, now, getLimits());
+	await persistSession();
+	await persistQueue();
+	if (event.name === "order_placed") {
+		await endSession();
+		return;
+	}
+	armSessionTimer();
+};
+let trackChain = Promise.resolve();
+const track = (event) => {
+	const run = () => trackEvent(event);
+	const next = trackChain.then(run, run);
+	const ok = () => void 0;
+	trackChain = next.then(ok, ok);
+	return next;
+};
+const endSession = async () => {
+	clearTimer("sessionTimer");
+	runtime.session = null;
+	await persistSession();
+	await flush();
+};
+const reset = async () => {
+	const storage = runtime.options?.storage;
+	resetRuntime();
+	if (!storage) return;
+	await storage.removeItem(SESSION_KEY);
+	await storage.removeItem(QUEUE_KEY);
+	await storage.removeItem(CONFIG_KEY);
+	await storage.removeItem(INTERACTIONS_KEY);
+};
+const analytics = {
+	configure,
+	track,
+	flush,
+	endSession,
+	reset
+};
+//#endregion
+export { FUNNEL_EVENTS, INTERACTION_EVENTS, analytics, configure, endSession, isFunnelEventName, isInteractionEventName, reset, track };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@fire-spark/analytics",
+  "version": "0.0.1",
+  "description": "Fire Spark storefront analytics SDK",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fire-spark/core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "platform": "neutral",
+    "dts": true,
+    "clean": true,
+    "deps": {
+      "neverBundle": [
+        "@fire-spark/core"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
+    "lint": "oxlint ./src --max-warnings=0",
+    "format": "oxfmt ./src",
+    "check-format": "oxfmt --check ./src"
+  }
+}