@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/ecommerce/events/marketplace.ts

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Marketplace and affiliate-specific ecommerce events
+ * Marketplace and affiliate-specific ecommerce events
+ * These events track user interactions unique to marketplace/affiliate models
+ */
+
+import { type BaseProductProperties, ECOMMERCE_EVENTS, type EcommerceEventSpec } from '../types';
+import { cleanProperties, normalizeProductProperties, validateRequiredProperties } from '../utils';
+
+/**
+ * Track when a user views price comparisons across multiple merchants
+ */
+export function priceComparisonViewed(properties: {
+  product_id: string;
+  merchants: {
+    merchant_id: string;
+    merchant_name: string;
+    price: number;
+    shipping?: number;
+    total_price?: number;
+    availability?: string;
+    rating?: number;
+  }[];
+  lowest_price?: number;
+  highest_price?: number;
+  average_price?: number;
+}): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['product_id', 'merchants']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRICE_COMPARISON_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['product_id', 'merchants'],
+  };
+}
+
+/**
+ * Track when a user selects a specific merchant from multiple options
+ */
+export function merchantSelected(
+  properties: BaseProductProperties & {
+    selected_merchant_id: string;
+    selected_merchant_name: string;
+    selection_reason?: 'lowest_price' | 'fastest_shipping' | 'best_rating' | 'in_stock' | 'other';
+    compared_merchants?: string[];
+  },
+): EcommerceEventSpec {
+  const normalizedProps = normalizeProductProperties(properties);
+  validateRequiredProperties(properties, ['product_id', 'selected_merchant_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.MERCHANT_SELECTED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      ...normalizedProps,
+      selected_merchant_id: properties.selected_merchant_id,
+      selected_merchant_name: properties.selected_merchant_name,
+      compared_merchants: properties.compared_merchants,
+      selection_reason: properties.selection_reason,
+    }),
+    requiredProperties: ['product_id', 'selected_merchant_id'],
+  };
+}
+
+/**
+ * Track when a user clicks an affiliate link to visit merchant site
+ */
+export function affiliateLinkClicked(
+  properties: BaseProductProperties & {
+    destination_url: string;
+    affiliate_network?: string;
+    commission_rate?: number;
+    tracking_code?: string;
+    deep_link?: boolean;
+  },
+): EcommerceEventSpec {
+  const normalizedProps = normalizeProductProperties(properties);
+  validateRequiredProperties(properties, ['product_id', 'destination_url']);
+
+  return {
+    name: ECOMMERCE_EVENTS.AFFILIATE_LINK_CLICKED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      ...normalizedProps,
+      destination_url: properties.destination_url,
+      deep_link: properties.deep_link,
+      tracking_code: properties.tracking_code,
+    }),
+    requiredProperties: ['product_id', 'destination_url'],
+  };
+}
+
+/**
+ * Track when an affiliate conversion is confirmed
+ * This is typically fired via webhook or after confirmation from affiliate network
+ */
+export function affiliateConversionTracked(properties: {
+  product_id: string;
+  order_id: string;
+  merchant_id: string;
+  merchant_name?: string;
+  affiliate_network?: string;
+  commission_amount?: number;
+  commission_rate?: number;
+  conversion_value?: number;
+  currency?: string;
+  conversion_type?: 'sale' | 'lead' | 'click' | 'other';
+  tracking_code?: string;
+}): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['product_id', 'order_id', 'merchant_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.AFFILIATE_CONVERSION_TRACKED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['product_id', 'order_id', 'merchant_id'],
+  };
+}

package/src/shared/emitters/ecommerce/events/order.ts

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Order-related ecommerce events
+ * Order-related ecommerce events
+ */
+
+import { trackEcommerce } from '../track-ecommerce';
+import {
+  ECOMMERCE_EVENTS,
+  type EcommerceEventSpec,
+  type OrderProperties,
+  type OrderStatusProperties,
+  type ReturnProperties,
+} from '../types';
+import {
+  cleanProperties,
+  normalizeProducts,
+  validateCurrency,
+  validateRequiredProperties,
+} from '../utils';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../../emitter-types';
+
+/**
+ * Track when a user completes an order
+ */
+export function orderCompleted(
+  properties: OrderProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['order_id']);
+
+  const normalizedProps: OrderProperties = {
+    order_id: properties.order_id,
+    affiliation: properties.affiliation,
+    coupon: properties.coupon,
+    currency: validateCurrency(properties.currency),
+    discount: properties.discount,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+    revenue: properties.revenue,
+    shipping: properties.shipping,
+    tax: properties.tax,
+    total: properties.total,
+  };
+
+  const eventSpec: EcommerceEventSpec = {
+    name: ECOMMERCE_EVENTS.ORDER_COMPLETED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id'],
+  };
+
+  return trackEcommerce(eventSpec, options);
+}
+
+/**
+ * Track when an order fails (payment declined, validation error, etc.)
+ */
+export function orderFailed(
+  properties: OrderProperties & {
+    failure_reason?: string;
+    error_code?: string;
+  },
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id']);
+
+  const { error_code, failure_reason, ...orderProps } = properties;
+  const normalizedProps = {
+    order_id: orderProps.order_id,
+    affiliation: orderProps.affiliation,
+    coupon: orderProps.coupon,
+    currency: validateCurrency(orderProps.currency),
+    discount: orderProps.discount,
+    error_code,
+    failure_reason,
+    products: orderProps.products ? normalizeProducts(orderProps.products) : undefined,
+    revenue: orderProps.revenue,
+    shipping: orderProps.shipping,
+    tax: orderProps.tax,
+    total: orderProps.total,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.ORDER_FAILED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id'],
+  };
+}
+
+/**
+ * Track when an order is refunded
+ */
+export function orderRefunded(properties: OrderProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id']);
+
+  const normalizedProps: OrderProperties = {
+    order_id: properties.order_id,
+    affiliation: properties.affiliation,
+    coupon: properties.coupon,
+    currency: validateCurrency(properties.currency),
+    discount: properties.discount,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+    revenue: properties.revenue,
+    shipping: properties.shipping,
+    tax: properties.tax,
+    total: properties.total,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.ORDER_REFUNDED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id'],
+  };
+}
+
+/**
+ * Track when an order is cancelled
+ */
+export function orderCancelled(properties: OrderProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id']);
+
+  const normalizedProps: OrderProperties = {
+    order_id: properties.order_id,
+    affiliation: properties.affiliation,
+    coupon: properties.coupon,
+    currency: validateCurrency(properties.currency),
+    discount: properties.discount,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+    revenue: properties.revenue,
+    shipping: properties.shipping,
+    tax: properties.tax,
+    total: properties.total,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.ORDER_CANCELLED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id'],
+  };
+}
+
+/**
+ * Track order status changes (shipping, delivery, etc.)
+ */
+export function orderStatusUpdated(properties: OrderStatusProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id', 'status']);
+
+  return {
+    name: ECOMMERCE_EVENTS.ORDER_STATUS_UPDATED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['order_id', 'status'],
+  };
+}
+
+/**
+ * Track when a return is requested
+ */
+export function returnRequested(properties: ReturnProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id', 'reason']);
+
+  const normalizedProps = {
+    ...properties,
+    products: normalizeProducts(properties.products),
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.RETURN_REQUESTED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id', 'reason'],
+  };
+}
+
+/**
+ * Track when a return is completed
+ */
+export function returnCompleted(
+  properties: ReturnProperties & {
+    completion_date?: string;
+    refund_status?: 'pending' | 'completed' | 'failed';
+  },
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['order_id', 'return_id']);
+
+  const normalizedProps = {
+    ...properties,
+    products: normalizeProducts(properties.products),
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.RETURN_COMPLETED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['order_id', 'return_id'],
+  };
+}

package/src/shared/emitters/ecommerce/events/product.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Product-related ecommerce events
+ * Product-related ecommerce events
+ */
+
+import { trackEcommerce } from '../track-ecommerce';
+import {
+  type BaseProductProperties,
+  ECOMMERCE_EVENTS,
+  type EcommerceEventSpec,
+  type ProductComparisonProperties,
+  type ProductListProperties,
+  type RecommendationProperties,
+  type SearchResultsProperties,
+} from '../types';
+import {
+  cleanProperties,
+  normalizeProductProperties,
+  normalizeProducts,
+  validateRequiredProperties,
+} from '../utils';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../../emitter-types';
+
+/**
+ * Track when a user searches for products
+ */
+export function productSearched(
+  properties: { query: string },
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['query']);
+
+  const eventSpec: EcommerceEventSpec = {
+    name: ECOMMERCE_EVENTS.PRODUCT_SEARCHED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['query'],
+  };
+
+  return trackEcommerce(eventSpec, options);
+}
+
+/**
+ * Track when search results are displayed
+ */
+export function searchResultsViewed(properties: SearchResultsProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['query', 'results_count']);
+
+  const normalizedProps = {
+    ...properties,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.SEARCH_RESULTS_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['query', 'results_count'],
+  };
+}
+
+/**
+ * Track when a user views a product list or category
+ */
+export function productListViewed(
+  properties: ProductListProperties,
+): EcommerceEventSpec<ProductListProperties> {
+  const normalizedProps: ProductListProperties = {
+    list_id: properties.list_id,
+    category: properties.category,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_LIST_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: [],
+  };
+}
+
+/**
+ * Track when a user filters a product list
+ */
+export function productListFiltered(
+  properties: ProductListProperties & { filters?: Record<string, any> },
+): EcommerceEventSpec {
+  const normalizedProps = {
+    list_id: properties.list_id,
+    category: properties.category,
+    filters: properties.filters,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_LIST_FILTERED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: [],
+  };
+}
+
+/**
+ * Track when a user clicks on a product
+ */
+export function productClicked(properties: BaseProductProperties): EcommerceEventSpec {
+  const normalizedProps = normalizeProductProperties(properties);
+  validateRequiredProperties(normalizedProps, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_CLICKED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when a user views a product detail page
+ */
+export function productViewed(
+  properties: BaseProductProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  const normalizedProps = normalizeProductProperties(properties);
+  validateRequiredProperties(normalizedProps, ['product_id']);
+
+  const eventSpec: EcommerceEventSpec = {
+    name: ECOMMERCE_EVENTS.PRODUCT_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['product_id'],
+  };
+
+  return trackEcommerce(eventSpec, options);
+}
+
+/**
+ * Track when a user compares products
+ */
+export function productCompared(properties: ProductComparisonProperties): EcommerceEventSpec {
+  const { action, comparison_list, product } = properties;
+  const normalizedProduct = normalizeProductProperties(product);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_COMPARED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      action,
+      ...normalizedProduct,
+      comparison_list: comparison_list ? normalizeProducts(comparison_list) : undefined,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when product recommendations are viewed
+ */
+export function productRecommendationViewed(
+  properties: RecommendationProperties,
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['recommendation_type', 'source']);
+
+  const normalizedProps = {
+    ...properties,
+    products: normalizeProducts(properties.products),
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_RECOMMENDATION_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['recommendation_type', 'source'],
+  };
+}
+
+/**
+ * Track when a recommended product is clicked
+ */
+export function productRecommendationClicked(
+  properties: BaseProductProperties & {
+    recommendation_type: string;
+    source: string;
+    position?: number;
+  },
+): EcommerceEventSpec {
+  const { recommendation_type, position, source, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_RECOMMENDATION_CLICKED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      ...normalizedProduct,
+      recommendation_type,
+      position,
+      source,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}

package/src/shared/emitters/ecommerce/events/registry.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Universal registry events for gift registries, wishlists, and similar features
+ * Universal registry events for gift registries, wishlists, and similar features
+ * Uses action-based patterns for efficient tracking
+ */
+
+import {
+  ECOMMERCE_EVENTS,
+  type EcommerceEventSpec,
+  type RegistryItemProperties,
+  type RegistryProperties,
+} from '../types';
+import { cleanProperties, normalizeProductProperties, validateRequiredProperties } from '../utils';
+
+/**
+ * Track registry management actions (create, update, delete)
+ */
+export function registryManaged(
+  properties: RegistryProperties & {
+    action: 'created' | 'updated' | 'deleted';
+    updated_fields?: string[];
+  },
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['registry_id', 'action']);
+
+  return {
+    name: ECOMMERCE_EVENTS.REGISTRY_MANAGED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['registry_id', 'action'],
+  };
+}
+
+/**
+ * Track when someone views a registry
+ */
+export function registryViewed(
+  properties: RegistryProperties & {
+    viewer_id?: string;
+    viewer_relationship?: 'owner' | 'co_owner' | 'friend' | 'family' | 'other';
+    items_count?: number;
+    items_fulfilled?: number;
+  },
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['registry_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.REGISTRY_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['registry_id'],
+  };
+}
+
+/**
+ * Track when a registry is shared
+ */
+export function registryShared(
+  properties: RegistryProperties & {
+    share_method: 'email' | 'social' | 'link' | 'qr_code' | 'other';
+    recipients_count?: number;
+    message?: string;
+  },
+): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['registry_id', 'share_method']);
+
+  return {
+    name: ECOMMERCE_EVENTS.REGISTRY_SHARED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['registry_id', 'share_method'],
+  };
+}
+
+/**
+ * Track registry item management (add, remove, update, purchase)
+ */
+export function registryItemManaged(
+  properties: RegistryItemProperties & {
+    action: 'added' | 'removed' | 'updated' | 'purchased';
+    purchaser_id?: string;
+    purchaser_name?: string;
+    purchase_quantity?: number;
+    purchase_message?: string;
+    gift_wrap?: boolean;
+    anonymous_gift?: boolean;
+    updated_fields?: string[];
+  },
+): EcommerceEventSpec {
+  const {
+    purchaser_id,
+    registry_id,
+    purchaser_name,
+    action,
+    anonymous_gift,
+    gift_wrap,
+    purchase_message,
+    purchase_quantity,
+    updated_fields,
+    ...productProps
+  } = properties;
+
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(properties, ['registry_id', 'product_id', 'action']);
+
+  return {
+    name: ECOMMERCE_EVENTS.REGISTRY_ITEM_MANAGED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      purchaser_id,
+      registry_id,
+      purchaser_name,
+      action,
+      anonymous_gift,
+      gift_wrap,
+      purchase_message,
+      purchase_quantity,
+      updated_fields,
+      ...normalizedProduct,
+    }),
+    requiredProperties: ['registry_id', 'product_id', 'action'],
+  };
+}