@fire-spark/analytics 0.0.3 → 0.1.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 //#region src/types.d.ts
-declare const FUNNEL_EVENTS: readonly ["menu_viewed", "product_viewed", "cart_item_added", "order_placed"];
+declare const FUNNEL_EVENTS: readonly ["menu_viewed", "product_viewed", "add_to_cart", "purchase"];
 declare const INTERACTION_EVENTS: readonly ["product_visited", "category_visited"];
 type FunnelEventName = (typeof FUNNEL_EVENTS)[number];
 type InteractionEventName = (typeof INTERACTION_EVENTS)[number];
@@ -26,6 +26,35 @@ type AnalyticsScope = {
   brand_id?: string;
   fulfillment_id?: string;
 };
+type DestinationProviderId = "ga4" | "meta" | "masivo" | "tiktok";
+type AnalyticsRuntime = "web" | "react-native";
+type AnalyticsConsent = {
+  analytics: boolean;
+  ads: boolean;
+};
+type AnalyticsSampleOptions = {
+  firstPerEvent?: boolean;
+  rate?: number;
+};
+type NormalizedEvent = {
+  name: string;
+  params: Record<string, unknown>;
+  items?: Array<Record<string, unknown>>;
+  userProperties?: Record<string, unknown>;
+  context: Record<string, unknown>;
+  runtime: AnalyticsRuntime;
+  consent: AnalyticsConsent;
+};
+type AnalyticsAdapter = {
+  provider: DestinationProviderId;
+  send: (event: NormalizedEvent) => Promise<void> | void;
+};
+type TrackOptions = {
+  only?: DestinationProviderId[];
+  exclude?: DestinationProviderId[];
+  extra?: AnalyticsAdapter[];
+  variant?: string;
+};
 type MenuViewedEvent = {
   name: "menu_viewed";
   properties?: Record<string, unknown>;
@@ -36,15 +65,15 @@ type ProductViewedEvent = {
     product_id: string;
   };
 };
-type CartItemAddedEvent = {
-  name: "cart_item_added";
+type AddToCartEvent = {
+  name: "add_to_cart";
   properties: {
     product_id: string;
     quantity: number;
   };
 };
-type OrderPlacedEvent = {
-  name: "order_placed";
+type PurchaseEvent = {
+  name: "purchase";
   properties: {
     order_id: string;
     total?: number;
@@ -65,7 +94,7 @@ type CategoryVisitedEvent = {
     category_id: string;
   };
 };
-type FunnelTrackEvent = MenuViewedEvent | ProductViewedEvent | CartItemAddedEvent | OrderPlacedEvent;
+type FunnelTrackEvent = MenuViewedEvent | ProductViewedEvent | AddToCartEvent | PurchaseEvent;
 type InteractionTrackEvent = ProductVisitedEvent | CategoryVisitedEvent;
 type FreeTrackEvent = {
   name: string;
@@ -82,6 +111,7 @@ type AnalyticsLimits = {
   maxAgeMs?: number;
   maxBytes?: number;
 };
+type AnalyticsMerchantContext = () => Record<string, unknown>;
 type AnalyticsConfigureOptions = {
   baseUrl?: string;
   getAccessToken?: () => Promise<string>;
@@ -89,11 +119,20 @@ type AnalyticsConfigureOptions = {
   getCustomer: () => AnalyticsCustomer | null;
   getScope?: () => AnalyticsScope;
   platform: AnalyticsPlatform;
-  context?: AnalyticsContext;
+  channel_id: string;
+  context?: AnalyticsContext | AnalyticsMerchantContext;
+  merchantContext?: AnalyticsMerchantContext;
   isOnline?: () => boolean | Promise<boolean>;
   limits?: AnalyticsLimits;
   fetchImpl?: typeof fetch;
   sessionMs?: number;
+  currency?: string;
+  adapters?: AnalyticsAdapter[];
+  env?: "production" | "staging";
+  planVersionId?: string;
+  consent?: () => AnalyticsConsent;
+  sample?: AnalyticsSampleOptions;
+  runtime?: AnalyticsRuntime;
 };
 type AnalyticsConfig = {
   session: {
@@ -110,15 +149,27 @@ 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>;
+type TrackName = (name: string, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
+type TrackAlias = (event: TrackEvent) => Promise<void>;
+type TrackEither = (nameOrEvent: string | TrackEvent, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
+type TrackFn = TrackName & TrackAlias & TrackEither;
+declare const track: TrackFn;
 declare const endSession: () => Promise<void>;
 declare const reset: () => Promise<void>;
+declare class Analytics {
+  constructor(options?: AnalyticsConfigureOptions);
+  configure: typeof configure;
+  track: TrackFn;
+  flush: typeof flush;
+  endSession: typeof endSession;
+  reset: typeof reset;
+}
 declare const analytics: {
   configure: typeof configure;
-  track: typeof track;
+  track: TrackFn;
   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 };
+export { Analytics, type AnalyticsAdapter, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type DestinationProviderId, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type NormalizedEvent, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, analytics, configure, endSession, flush, isFunnelEventName, isInteractionEventName, reset, track };

package/dist/index.js

@@ -32,36 +32,54 @@ const buildEventContext = (context) => {
 	};
 };
 //#endregion
-//#region src/retry.ts
-const defaultSleep = (ms) => {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
+//#region src/pii.ts
+const PII_KEYS = /* @__PURE__ */ new Set([
+	"phone",
+	"device_ip",
+	"email",
+	"ttclid"
+]);
+const toHex = (bytes) => {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 };
-/** 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);
+const isPiiParam = (name) => {
+	return PII_KEYS.has(name);
+};
+const hashPiiValue = async (value) => {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("SHA-256 unavailable");
+	const normalized = value.trim().toLowerCase();
+	const data = new TextEncoder().encode(normalized);
+	const digest = await subtle.digest("SHA-256", data);
+	return toHex(new Uint8Array(digest));
+};
+const hashDeep = async (value) => {
+	if (typeof value === "string") return hashPiiValue(value);
+	if (typeof value === "number" || typeof value === "boolean") return hashPiiValue(String(value));
+	if (Array.isArray(value)) return Promise.all(value.map((item) => hashDeep(item)));
+	if (!value || typeof value !== "object") return value;
+	return hashPiiParams(value);
+};
+const hashPiiParams = async (params) => {
+	const next = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (!isPiiParam(key)) {
+			next[key] = value;
+			continue;
+		}
+		try {
+			next[key] = await hashDeep(value);
+		} catch {}
 	}
-	throw lastError;
+	return next;
 };
 //#endregion
 //#region src/types.ts
 const FUNNEL_EVENTS = [
 	"menu_viewed",
 	"product_viewed",
-	"cart_item_added",
-	"order_placed"
+	"add_to_cart",
+	"purchase"
 ];
 const INTERACTION_EVENTS = ["product_visited", "category_visited"];
 const isFunnelEventName = (name) => {
@@ -139,17 +157,31 @@ const enqueueEvent = (events, event, now, limits) => {
 const CONFIG_KEY = "firespark:analytics:config";
 const DEFAULT_SESSION_MS = 1800 * 1e3;
 const RETRY_MS = 6e4;
-const runtime = {
+const r1 = {
 	options: null,
-	context: null,
+	context: null
+};
+const r2 = {
 	sessionMs: DEFAULT_SESSION_MS,
-	session: null,
+	session: null
+};
+const r3 = {
 	interactions: null,
-	queue: [],
+	queue: []
+};
+const r4 = {
 	hydrated: false,
 	sessionTimer: null,
 	retryTimer: null
 };
+const r5 = { sampleSeen: null };
+const runtime = {
+	...r1,
+	...r2,
+	...r3,
+	...r4,
+	...r5
+};
 const getLimits = () => {
 	const limits = runtime.options?.limits;
 	return {
@@ -212,6 +244,698 @@ const resetRuntime = () => {
 	runtime.interactions = null;
 	runtime.queue = [];
 	runtime.hydrated = false;
+	runtime.sampleSeen = null;
+};
+//#endregion
+//#region ../../packages/constants/src/tracking-plan-catalog/currency.ts
+const ISO_4217_CODE = /^[A-Z]{3}$/;
+const USD_AMOUNT_PARAM_SUFFIX = "_in_usd";
+const isUsdAmountParam = (name) => {
+	return name.endsWith(USD_AMOUNT_PARAM_SUFFIX);
+};
+const dropUsdDeep = (value) => {
+	if (Array.isArray(value)) return value.map(dropUsdDeep);
+	if (!value || typeof value !== "object") return value;
+	const next = {};
+	for (const [key, nested] of Object.entries(value)) {
+		if (isUsdAmountParam(key)) continue;
+		next[key] = dropUsdDeep(nested);
+	}
+	return next;
+};
+const dropUsdAmountParams = (params) => {
+	return dropUsdDeep(params);
+};
+/** ISO 4217 from `merchants.currency_id` → `currencies.code`. */
+const merchantCurrencyCode = (code) => {
+	const normalized = code.trim().toUpperCase();
+	if (!ISO_4217_CODE.test(normalized)) throw new Error("Merchant currency must be an ISO 4217 code");
+	return normalized;
+};
+//#endregion
+//#region ../../packages/constants/src/tracking-plan-catalog/params.ts
+const valueParam = (required = true) => {
+	return {
+		name: "value",
+		type: "currency",
+		required,
+		scope: "ecommerce"
+	};
+};
+const priceParam = (required = false) => {
+	return {
+		name: "price",
+		type: "currency",
+		required,
+		scope: "item"
+	};
+};
+const quantityParam = (required = false) => {
+	return {
+		name: "quantity",
+		type: "integer",
+		required,
+		scope: "item"
+	};
+};
+const itemsParam = () => {
+	return {
+		name: "items",
+		type: "array<object>",
+		required: false,
+		scope: "ecommerce"
+	};
+};
+const transactionIdParam = () => {
+	return {
+		name: "transaction_id",
+		type: "string",
+		required: false,
+		scope: "event"
+	};
+};
+//#endregion
+//#region ../../packages/constants/src/tracking-plan-catalog/events.ts
+const both = (name) => {
+	return {
+		web: name,
+		reactNative: name
+	};
+};
+const none = () => {
+	return {
+		web: null,
+		reactNative: null
+	};
+};
+const meta = (web, reactNative) => {
+	return {
+		web,
+		reactNative
+	};
+};
+const ecommerceParams = (valueRequired = true) => {
+	return [
+		valueParam(valueRequired),
+		itemsParam(),
+		transactionIdParam()
+	];
+};
+/**
+* Native events only. Custom events are merchant-authored and never shipped
+* as catalog suggestions or plan defaults.
+*/
+const CATALOG_EVENTS = [
+	{
+		id: "add_to_cart",
+		name: "add_to_cart",
+		kind: "native",
+		category: "E-commerce",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [
+			{
+				name: "product_id",
+				type: "string",
+				required: true,
+				scope: "event"
+			},
+			quantityParam(true),
+			...ecommerceParams(false)
+		],
+		destinations: {
+			"fire-spark": both("add_to_cart"),
+			ga4: both("add_to_cart"),
+			meta: meta("AddToCart", "fb_mobile_add_to_cart"),
+			tiktok: both("AddToCart"),
+			masivo: both("ADD_TO_CART")
+		}
+	},
+	{
+		id: "begin_checkout",
+		name: "begin_checkout",
+		kind: "native",
+		category: "E-commerce",
+		runtimes: ["web", "react-native"],
+		recommendedParams: ecommerceParams(),
+		destinations: {
+			"fire-spark": both("begin_checkout"),
+			ga4: both("begin_checkout"),
+			meta: meta("InitiateCheckout", "fb_mobile_initiated_checkout"),
+			tiktok: both("InitiateCheckout"),
+			masivo: both("begin_checkout")
+		}
+	},
+	{
+		id: "purchase",
+		name: "purchase",
+		kind: "native",
+		category: "E-commerce",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [{
+			name: "order_id",
+			type: "string",
+			required: true,
+			scope: "event"
+		}, ...ecommerceParams(false)],
+		destinations: {
+			"fire-spark": both("purchase"),
+			ga4: both("purchase"),
+			meta: meta("Purchase", "fb_mobile_purchase"),
+			tiktok: both("Purchase"),
+			masivo: both("PURCHASE")
+		}
+	},
+	{
+		id: "view_item",
+		name: "view_item",
+		kind: "native",
+		category: "E-commerce",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [
+			valueParam(false),
+			itemsParam(),
+			priceParam(),
+			quantityParam()
+		],
+		destinations: {
+			"fire-spark": both("product_viewed"),
+			ga4: both("view_item"),
+			meta: meta("ViewContent", "fb_mobile_content_view"),
+			tiktok: both("ViewContent"),
+			masivo: both("view_item")
+		}
+	},
+	{
+		id: "sign_up",
+		name: "sign_up",
+		kind: "native",
+		category: "Account",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [{
+			name: "method",
+			type: "string",
+			required: false,
+			scope: "event"
+		}],
+		destinations: {
+			"fire-spark": both("sign_up"),
+			ga4: both("sign_up"),
+			meta: meta("CompleteRegistration", "fb_mobile_complete_registration"),
+			tiktok: both("Registration"),
+			masivo: both("sign_up")
+		}
+	},
+	{
+		id: "login",
+		name: "login",
+		kind: "native",
+		category: "Account",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [{
+			name: "method",
+			type: "string",
+			required: false,
+			scope: "event"
+		}],
+		destinations: {
+			"fire-spark": both("login"),
+			ga4: both("login"),
+			meta: both("login"),
+			tiktok: both("Login"),
+			masivo: both("login")
+		}
+	},
+	{
+		id: "page_view",
+		name: "page_view",
+		kind: "native",
+		category: "Navegación",
+		runtimes: ["web"],
+		recommendedParams: [],
+		destinations: {
+			"fire-spark": both("page_view"),
+			ga4: both("page_view"),
+			meta: none(),
+			tiktok: none(),
+			masivo: none()
+		}
+	},
+	{
+		id: "screen_view",
+		name: "screen_view",
+		kind: "native",
+		category: "Navegación",
+		runtimes: ["react-native"],
+		recommendedParams: [],
+		destinations: {
+			"fire-spark": both("screen_view"),
+			ga4: both("screen_view"),
+			meta: none(),
+			tiktok: none(),
+			masivo: none()
+		}
+	},
+	{
+		id: "menu_viewed",
+		name: "menu_viewed",
+		kind: "native",
+		category: "Navegación",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [],
+		destinations: {
+			"fire-spark": both("menu_viewed"),
+			ga4: both("menu_viewed"),
+			meta: both("menu_viewed"),
+			tiktok: both("menu_viewed"),
+			masivo: both("menu_viewed")
+		}
+	},
+	{
+		id: "product_viewed",
+		name: "product_viewed",
+		kind: "native",
+		category: "E-commerce",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [{
+			name: "product_id",
+			type: "string",
+			required: true,
+			scope: "event"
+		}],
+		destinations: {
+			"fire-spark": both("product_viewed"),
+			ga4: both("view_item"),
+			meta: meta("ViewContent", "fb_mobile_content_view"),
+			tiktok: both("ViewContent"),
+			masivo: both("view_item")
+		}
+	},
+	{
+		id: "product_visited",
+		name: "product_visited",
+		kind: "native",
+		category: "Navegación",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [
+			{
+				name: "product_id",
+				type: "string",
+				required: true,
+				scope: "event"
+			},
+			{
+				name: "category_id",
+				type: "string",
+				required: false,
+				scope: "event"
+			},
+			{
+				name: "attribution_source",
+				type: "string",
+				required: false,
+				scope: "event"
+			},
+			{
+				name: "attribution_id",
+				type: "string",
+				required: false,
+				scope: "event"
+			}
+		],
+		destinations: {
+			"fire-spark": both("product_visited"),
+			ga4: both("product_visited"),
+			meta: both("product_visited"),
+			tiktok: both("product_visited"),
+			masivo: both("product_visited")
+		}
+	},
+	{
+		id: "category_visited",
+		name: "category_visited",
+		kind: "native",
+		category: "Navegación",
+		runtimes: ["web", "react-native"],
+		recommendedParams: [{
+			name: "category_id",
+			type: "string",
+			required: true,
+			scope: "event"
+		}],
+		destinations: {
+			"fire-spark": both("category_visited"),
+			ga4: both("category_visited"),
+			meta: both("category_visited"),
+			tiktok: both("category_visited"),
+			masivo: both("category_visited")
+		}
+	}
+];
+const eventsByName = new Map(CATALOG_EVENTS.map((event) => [event.name, event]));
+const catalogEventByName = (name) => {
+	return eventsByName.get(name);
+};
+const destinationEventName = (developerName, provider, runtime) => {
+	const event = catalogEventByName(developerName);
+	if (!event) return developerName;
+	const binding = event.destinations[provider];
+	if (!binding) return developerName;
+	if (runtime === "react-native") return binding.reactNative;
+	return binding.web;
+};
+//#endregion
+//#region ../../packages/constants/src/tracking-plan-catalog/transforms.ts
+const stringVal = (value) => {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const numberVal = (value) => {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	return value;
+};
+const itemId = (item) => {
+	return stringVal(item.item_id) ?? stringVal(item.content_id) ?? "";
+};
+const itemQty = (item) => {
+	return numberVal(item.quantity) ?? 1;
+};
+const itemPrice = (item) => {
+	return numberVal(item.price) ?? numberVal(item.item_price) ?? 0;
+};
+const itemsOf$1 = (input) => {
+	if (input.items && input.items.length > 0) return input.items;
+	const fromParams = input.params.items;
+	if (!Array.isArray(fromParams)) return [];
+	return fromParams.filter((row) => {
+		return !!row && typeof row === "object" && !Array.isArray(row);
+	});
+};
+const valueOf = (input, items) => {
+	const explicit = numberVal(input.params.value);
+	if (explicit !== void 0) return explicit;
+	return items.reduce((sum, item) => sum + itemPrice(item) * itemQty(item), 0);
+};
+/**
+* Delivery-only TikTok names for storefronts already emitting these events.
+* Never used to build or prefill tracking plans.
+*/
+const LEGACY_TIKTOK_ALIASES = {
+	medios_view_item_delivery: "UnlockAchievement",
+	medios_view_item_express: "StartTrial",
+	medios_purchase_delivery: "Subscribe",
+	medios_purchase_express: "GenerateLead"
+};
+const resolvedName = (input, provider) => {
+	const alias = LEGACY_TIKTOK_ALIASES[input.name];
+	if (provider === "tiktok" && alias) return alias;
+	return destinationEventName(input.name, provider, input.runtime) ?? input.name;
+};
+const ga4Payload = (input, items) => {
+	const currency = merchantCurrencyCode(input.currency);
+	const value = valueOf(input, items);
+	const b1 = {
+		items: items.map((item) => {
+			return {
+				item_id: itemId(item),
+				item_name: item.item_name,
+				price: itemPrice(item),
+				quantity: itemQty(item)
+			};
+		}),
+		value,
+		currency
+	};
+	const transaction_id = stringVal(input.params.transaction_id);
+	const order_id = stringVal(input.params.order_id);
+	return {
+		...b1,
+		transaction_id: transaction_id ?? order_id
+	};
+};
+const metaContents = (items) => {
+	return items.map((item) => {
+		return {
+			id: itemId(item),
+			quantity: itemQty(item),
+			item_price: itemPrice(item)
+		};
+	});
+};
+const metaPayload = (input, items) => {
+	const currency = merchantCurrencyCode(input.currency);
+	return {
+		value: valueOf(input, items),
+		currency,
+		contents: metaContents(items)
+	};
+};
+const tiktokContents = (items) => {
+	return items.map((item) => {
+		return {
+			content_id: itemId(item),
+			quantity: itemQty(item),
+			price: itemPrice(item)
+		};
+	});
+};
+const tiktokPayload = (input, items) => {
+	const currency = merchantCurrencyCode(input.currency);
+	const params = input.params;
+	const ctx = input.context ?? {};
+	const b1 = {
+		value: valueOf(input, items),
+		currency
+	};
+	const b2 = { content_type: params.content_type };
+	const b3 = { content_id: params.content_id };
+	const b4 = {
+		description: params.description,
+		order_id: params.order_id
+	};
+	const b5 = { contents: tiktokContents(items) };
+	const properties = {
+		...b1,
+		...b2,
+		...b3,
+		...b4,
+		...b5
+	};
+	const user = {
+		external_id: ctx.external_id,
+		ttclid: ctx.ttclid
+	};
+	const r1 = { event: resolvedName(input, "tiktok") };
+	const r2 = {
+		event_time: input.eventTime,
+		event_id: input.eventId
+	};
+	return {
+		...r1,
+		...r2,
+		properties,
+		context: user
+	};
+};
+const masivoPayload = (input, items) => {
+	const currency = merchantCurrencyCode(input.currency);
+	const ctx = input.context ?? {};
+	const products = items.map((item) => {
+		const metadata = { prices: {
+			net_price: itemPrice(item),
+			currency
+		} };
+		return {
+			id: itemId(item),
+			quantity: itemQty(item),
+			metadata
+		};
+	});
+	const order = {
+		id: input.params.order_id ?? input.params.transaction_id,
+		currency,
+		products
+	};
+	const metadata = {
+		store_id: ctx.store_id,
+		vendor_id: ctx.vendor_id
+	};
+	return {
+		type: resolvedName(input, "masivo"),
+		order,
+		metadata
+	};
+};
+const transformForProvider = (provider, input) => {
+	const params = dropUsdAmountParams(input.params);
+	const itemsIn = input.items?.map((item) => dropUsdAmountParams(item));
+	const next = {
+		...input,
+		params,
+		items: itemsIn
+	};
+	const items = itemsOf$1(next);
+	const name = resolvedName(next, provider);
+	if (provider === "ga4") return {
+		provider,
+		name,
+		payload: ga4Payload(next, items)
+	};
+	if (provider === "meta") return {
+		provider,
+		name,
+		payload: metaPayload(next, items)
+	};
+	if (provider === "tiktok") return {
+		provider,
+		name,
+		payload: tiktokPayload(next, items)
+	};
+	if (provider === "masivo") return {
+		provider,
+		name,
+		payload: masivoPayload(next, items)
+	};
+	return {
+		provider,
+		name,
+		payload: next.params
+	};
+};
+//#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/fanout.ts
+const ADS_PROVIDERS = /* @__PURE__ */ new Set(["meta", "tiktok"]);
+const DEFAULT_CONSENT = {
+	analytics: true,
+	ads: true
+};
+const resolveRuntime = (options) => {
+	if (options.runtime) return options.runtime;
+	return options.platform === "web" ? "web" : "react-native";
+};
+const resolveMerchantContext = (options) => {
+	if (options.merchantContext) return options.merchantContext();
+	if (typeof options.context === "function") return options.context();
+	return { ...options.getScope?.() ?? {} };
+};
+const resolveAdapters = (opts) => {
+	const constructed = runtime.options?.adapters ?? [];
+	const extra = opts?.extra ?? [];
+	const available = [...constructed, ...extra];
+	if (opts?.only) {
+		for (const id of opts.only) if (!available.some((adapter) => adapter.provider === id)) throw new Error(`Adapter ${id} was never constructed`);
+		return available.filter((adapter) => opts.only?.includes(adapter.provider));
+	}
+	if (!opts?.exclude) return available;
+	return available.filter((adapter) => !opts.exclude?.includes(adapter.provider));
+};
+const itemsOf = (params) => {
+	if (!Array.isArray(params.items)) return void 0;
+	return params.items.filter((row) => {
+		return !!row && typeof row === "object" && !Array.isArray(row);
+	});
+};
+const sendOne = async (adapter, event, consent, runtimeId, currency, context) => {
+	const ads = ADS_PROVIDERS.has(adapter.provider);
+	if (ads && !consent.ads) return;
+	if (!ads && !consent.analytics) return;
+	const raw = event.properties ?? {};
+	const params = ads ? await hashPiiParams(raw) : raw;
+	const rows = itemsOf(params);
+	const items = ads && rows ? await Promise.all(rows.map(hashPiiParams)) : rows;
+	const b1 = {
+		name: event.name,
+		params,
+		items,
+		currency
+	};
+	const b2 = {
+		runtime: runtimeId,
+		eventId: randomUUID()
+	};
+	const b3 = {
+		eventTime: Math.floor(Date.now() / 1e3),
+		context
+	};
+	const input = {
+		...b1,
+		...b2,
+		...b3
+	};
+	const transformed = transformForProvider(adapter.provider, input);
+	const n1 = {
+		name: transformed.name,
+		params: transformed.payload
+	};
+	const n2 = {
+		items,
+		context,
+		runtime: runtimeId,
+		consent
+	};
+	const normalized = {
+		...n1,
+		...n2
+	};
+	await adapter.send(normalized);
+};
+const fanoutAdapters = async (event, opts) => {
+	const adapters = resolveAdapters(opts);
+	if (adapters.length === 0) return;
+	const options = runtime.options;
+	if (!options) return;
+	const consent = options.consent?.() ?? DEFAULT_CONSENT;
+	const runtimeId = resolveRuntime(options);
+	const currency = options.currency ?? "USD";
+	const context = resolveMerchantContext(options);
+	const send = async (adapter) => {
+		try {
+			await sendOne(...[
+				adapter,
+				event,
+				consent,
+				runtimeId
+			], currency, context);
+		} catch {}
+	};
+	await Promise.all(adapters.map(send));
+};
+//#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/flush.ts
@@ -239,17 +963,20 @@ const isOnline = async () => {
 	if (!check) return true;
 	return check();
 };
-const postChunk = async (events) => {
-	const http = await httpOptions();
+const storefrontCall = async (path, init) => {
 	return storefrontJson(...[
-		"/api/storefront/v1/analytics/events",
-		{
-			method: "POST",
-			body: JSON.stringify({ events })
-		},
-		http
+		path,
+		init,
+		await httpOptions()
 	]);
 };
+const postChunk = async (events) => {
+	const init = {
+		method: "POST",
+		body: JSON.stringify({ events })
+	};
+	return storefrontCall("/api/storefront/v1/analytics/events", init);
+};
 const scheduleRetry = () => {
 	if (runtime.retryTimer || runtime.queue.length === 0) return;
 	runtime.retryTimer = setTimeout(() => {
@@ -262,19 +989,21 @@ const preferencesPath = () => {
 	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);
+	const channel_id = scope.channel_id ?? runtime.options?.channel_id;
+	if (channel_id) params.set("channel_id", 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;
+	const path = preferencesPath();
+	const prefs = await storefrontCall(path, { method: "GET" });
+	const currency_code = prefs.currency?.code;
+	return {
+		...prefs.analytics,
+		currency_code
+	};
 };
 let flushWait = null;
 const flushOnce = async () => {
@@ -309,19 +1038,130 @@ const flush = async () => {
 	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)}`;
+//#region src/sample.ts
+const SAMPLE_KEY = "firespark:analytics:samples";
+const PLAN_SAMPLES_PATH = "/api/storefront/v1/analytics/plan-samples";
+const DEFAULT_RATE = .01;
+const inferType = (value) => {
+	if (value === null) return "null";
+	if (Array.isArray(value)) {
+		const first = value[0];
+		if (first && typeof first === "object") return "array<object>";
+		return "array";
+	}
+	if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+	return typeof value;
+};
+const parseSeen = (raw) => {
+	if (!raw) return /* @__PURE__ */ new Set();
+	try {
+		const parsed = JSON.parse(raw);
+		return new Set(parsed.keys ?? []);
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+};
+const loadSeen = async () => {
+	if (runtime.sampleSeen) return runtime.sampleSeen;
+	runtime.sampleSeen = parseSeen(await readStorage(SAMPLE_KEY));
+	return runtime.sampleSeen;
+};
+const persistSeen = async (seen) => {
+	runtime.sampleSeen = seen;
+	const keys = [...seen];
+	await writeStorage(SAMPLE_KEY, JSON.stringify({ keys }));
+};
+const leafName = (path) => {
+	const parts = path.split(".");
+	return parts[parts.length - 1] ?? path;
+};
+const shouldOmitParam = (path) => {
+	return isPiiParam(path) || isPiiParam(leafName(path));
+};
+const pushParam = (path, value, param_names, inferred_types, presence) => {
+	if (shouldOmitParam(path)) return;
+	param_names.push(path);
+	inferred_types.push(inferType(value));
+	presence.push(value !== void 0 && value !== null);
+};
+const describeSample = (event, opts) => {
+	const params = event.properties ?? {};
+	const param_names = [];
+	const inferred_types = [];
+	const presence = [];
+	const p1 = [
+		param_names,
+		inferred_types,
+		presence
+	];
+	for (const [key, value] of Object.entries(params)) {
+		if (shouldOmitParam(key)) continue;
+		pushParam(key, value, ...p1);
+		if (Array.isArray(value)) {
+			const first = value.find((item) => item && typeof item === "object");
+			if (!first) continue;
+			for (const [ik, iv] of Object.entries(first)) pushParam(`${key}.*.${ik}`, iv, ...p1);
+			continue;
+		}
+		if (!value || typeof value !== "object") continue;
+		for (const [ck, cv] of Object.entries(value)) pushParam(`${key}.${ck}`, cv, ...p1);
+	}
+	const variant = opts?.variant;
+	return {
+		event_key: event.name,
+		param_names,
+		inferred_types,
+		presence,
+		variant
+	};
+};
+const shouldSend = (seen, firstPerEvent, rate) => {
+	if (!seen && firstPerEvent) return true;
+	if (rate >= 1) return true;
+	if (rate <= 0) return false;
+	return Math.random() < rate;
+};
+const samplePlanEvent = async (event, opts) => {
+	const options = runtime.options;
+	if (!options?.planVersionId) return;
+	const sample = options.sample ?? {};
+	const firstPerEvent = sample.firstPerEvent !== false;
+	const rate = sample.rate ?? DEFAULT_RATE;
+	const variant = opts?.variant;
+	const key = variant ? `${event.name}:${variant}` : event.name;
+	const seen = await loadSeen();
+	const already = seen.has(key);
+	if (!shouldSend(already, firstPerEvent, rate)) return;
+	const described = describeSample(event, opts);
+	const env = options.env ?? "production";
+	const body1 = { plan_version_id: options.planVersionId };
+	const body2 = { event_key: described.event_key };
+	const body3 = {
+		variant_id: described.variant ?? null,
+		env
+	};
+	const body4 = { channel_id: options.channel_id };
+	const body5 = { param_names: described.param_names };
+	const body6 = { inferred_types: described.inferred_types };
+	const body7 = { presence: described.presence };
+	const full = {
+		...body1,
+		...body2,
+		...body3,
+		...body4,
+		...body5,
+		...body6,
+		...body7
+	};
+	const init = {
+		method: "POST",
+		body: JSON.stringify(full)
+	};
+	await storefrontCall(PLAN_SAMPLES_PATH, init);
+	if (!already) {
+		seen.add(key);
+		await persistSeen(seen);
+	}
 };
 //#endregion
 //#region src/session.ts
@@ -372,6 +1212,14 @@ const shouldCarryMenuViewed = (prev, next) => {
 };
 //#endregion
 //#region src/index.ts
+const toTrackEvent = (nameOrEvent, params) => {
+	if (typeof nameOrEvent !== "string") return nameOrEvent;
+	if (!params) return { name: nameOrEvent };
+	return {
+		name: nameOrEvent,
+		properties: params
+	};
+};
 const entityIdFromEvent = (event) => {
 	const props = event.properties;
 	if (!props) return void 0;
@@ -410,23 +1258,45 @@ const refreshConfig = async () => {
 		return;
 	}
 	try {
-		runtime.sessionMs = (await fetchRemoteConfig()).session_ms || 18e5;
+		const config = await fetchRemoteConfig();
+		runtime.sessionMs = config.session_ms || 18e5;
 		await persistConfig(runtime.sessionMs);
+		const code = config.currency_code;
+		if (code && runtime.options && !runtime.options.currency) runtime.options = {
+			...runtime.options,
+			currency: code
+		};
 	} catch {
 		if (!runtime.sessionMs) runtime.sessionMs = DEFAULT_SESSION_MS;
 	}
 };
+let trackChain = Promise.resolve();
+const enqueue = (run) => {
+	const next = trackChain.then(run, run);
+	const ok = () => void 0;
+	trackChain = next.then(ok, ok);
+	return next;
+};
 const configure = async (options) => {
-	runtime.options = options;
-	runtime.context = buildEventContext(options.context);
-	await loadPersisted();
-	await refreshConfig();
-	armSessionTimer();
-	if (runtime.queue.length > 0) flush();
+	const channel_id = options.channel_id?.trim() ?? "";
+	if (!channel_id) throw new Error("channel_id is required");
+	return enqueue(async () => {
+		runtime.options = {
+			...options,
+			channel_id
+		};
+		const ctx = options.context;
+		runtime.context = buildEventContext(typeof ctx === "function" ? void 0 : ctx);
+		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 channel_id = runtime.options?.channel_id ?? scope.channel_id;
 	const b1 = {
 		id: randomUUID(),
 		name: event.name,
@@ -436,7 +1306,7 @@ const toQueued = (event, now, sessionId, customer) => {
 	const b3 = { timestamp: new Date(now).toISOString() };
 	const b4 = {
 		store_id: scope.store_id,
-		channel_id: scope.channel_id
+		channel_id
 	};
 	const b5 = {
 		brand_id: scope.brand_id,
@@ -517,19 +1387,28 @@ const trackEvent = async (event) => {
 	runtime.queue = enqueueEvent(runtime.queue, queued, now, getLimits());
 	await persistSession();
 	await persistQueue();
-	if (event.name === "order_placed") {
+	if (event.name === "purchase") {
 		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 swallow = (task) => {
+	return task.catch(() => void 0);
+};
+const dispatch = async (event, objectForm, opts) => {
+	const sampleP = swallow(samplePlanEvent(event, opts));
+	resolveAdapters(opts);
+	const fanoutP = swallow(fanoutAdapters(event, opts));
+	const funnel = isFunnelEventName(event.name);
+	const interaction = isInteractionEventName(event.name);
+	if (objectForm || funnel || interaction) await trackEvent(event);
+	await Promise.all([sampleP, fanoutP]);
+};
+const track = (nameOrEvent, params, opts) => {
+	const objectForm = typeof nameOrEvent !== "string";
+	const event = toTrackEvent(nameOrEvent, params);
+	return enqueue(() => dispatch(event, objectForm, opts));
 };
 const endSession = async () => {
 	clearTimer("sessionTimer");
@@ -545,6 +1424,19 @@ const reset = async () => {
 	await storage.removeItem(QUEUE_KEY);
 	await storage.removeItem(CONFIG_KEY);
 	await storage.removeItem(INTERACTIONS_KEY);
+	await storage.removeItem(SAMPLE_KEY);
+};
+var Analytics = class {
+	constructor(options) {
+		if (!options) return;
+		if (!(options.channel_id?.trim() ?? "")) throw new Error("channel_id is required");
+		configure(options);
+	}
+	configure = configure;
+	track = track;
+	flush = flush;
+	endSession = endSession;
+	reset = reset;
 };
 const analytics = {
 	configure,
@@ -554,4 +1446,4 @@ const analytics = {
 	reset
 };
 //#endregion
-export { FUNNEL_EVENTS, INTERACTION_EVENTS, analytics, configure, endSession, isFunnelEventName, isInteractionEventName, reset, track };
+export { Analytics, FUNNEL_EVENTS, INTERACTION_EVENTS, analytics, configure, endSession, flush, isFunnelEventName, isInteractionEventName, reset, track };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/analytics",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "description": "Fire Spark storefront analytics SDK",
   "type": "module",
   "sideEffects": false,
@@ -17,7 +17,7 @@
     }
   },
   "dependencies": {
-    "@fire-spark/core": "0.0.3"
+    "@fire-spark/core": "^0.1.1"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",
@@ -46,7 +46,7 @@
     }
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && find ../../packages/constants/src -name '*.d.ts' -delete",
     "dev": "tsdown --watch",
     "check-types": "tsc --noEmit",
     "test:utils": "vitest run",