@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/ecommerce/events/wishlist-sharing.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Wishlist, sharing, and review-related ecommerce events
+ * Wishlist, sharing, and review-related ecommerce events
+ */
+
+import {
+  type BaseProductProperties,
+  type CartProperties,
+  ECOMMERCE_EVENTS,
+  type EcommerceEventSpec,
+  type ReviewProperties,
+  type SharingProperties,
+  type WishlistProperties,
+} from '../types';
+import {
+  cleanProperties,
+  normalizeProductProperties,
+  normalizeProducts,
+  validateRequiredProperties,
+} from '../utils';
+
+/**
+ * Track when a product is added to wishlist
+ */
+export function productAddedToWishlist(properties: WishlistProperties): EcommerceEventSpec {
+  const { wishlist_id, wishlist_name, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_ADDED_TO_WISHLIST,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      wishlist_id,
+      wishlist_name,
+      ...normalizedProduct,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when a product is removed from wishlist
+ */
+export function productRemovedFromWishlist(properties: WishlistProperties): EcommerceEventSpec {
+  const { wishlist_id, wishlist_name, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_REMOVED_FROM_WISHLIST,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      wishlist_id,
+      wishlist_name,
+      ...normalizedProduct,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when a wishlist product is added to cart
+ */
+export function wishlistProductAddedToCart(
+  properties: WishlistProperties & { cart_id?: string },
+): EcommerceEventSpec {
+  const { cart_id, wishlist_id, wishlist_name, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.WISHLIST_PRODUCT_ADDED_TO_CART,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      cart_id,
+      wishlist_id,
+      wishlist_name,
+      ...normalizedProduct,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when a product is shared
+ */
+export function productShared(
+  properties: BaseProductProperties & SharingProperties,
+): EcommerceEventSpec {
+  const { recipient, share_message, share_via, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_SHARED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      recipient,
+      share_message,
+      share_via,
+      ...normalizedProduct,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}
+
+/**
+ * Track when a cart is shared
+ */
+export function cartShared(properties: CartProperties & SharingProperties): EcommerceEventSpec {
+  const { cart_id, products, recipient, share_message, share_via } = properties;
+
+  return {
+    name: ECOMMERCE_EVENTS.CART_SHARED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      cart_id,
+      products: products ? normalizeProducts(products) : undefined,
+      recipient,
+      share_message,
+      share_via,
+    }),
+    requiredProperties: [],
+  };
+}
+
+/**
+ * Track when a product is reviewed
+ */
+export function productReviewed(properties: ReviewProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRODUCT_REVIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(properties),
+    requiredProperties: ['product_id'],
+  };
+}

package/src/shared/emitters/ecommerce/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Platform-standard ecommerce events
+ *
+ * This module provides comprehensive ecommerce event tracking following industry
+ * best practices (Segment.io ecommerce spec, Google Analytics Enhanced Ecommerce).
+ *
+ * **Event Categories**:
+ * - **Cart & Checkout**: Add to cart, remove from cart, checkout started, checkout completed
+ * - **Orders**: Order placed, order updated, order refunded, order cancelled
+ * - **Products**: Product viewed, product added, product removed, product shared
+ * - **Coupons**: Coupon applied, coupon removed, coupon viewed
+ * - **Engagement**: Product list viewed, product list filtered, product searched
+ * - **Marketplace**: Seller viewed, seller contacted, review submitted
+ * - **Registry**: Registry created, registry item added, registry shared
+ * - **Wishlist**: Wishlist item added, wishlist item removed, wishlist shared
+ *
+ * **Usage**: Import event functions and use with `analytics.emit()`:
+ * ```typescript
+ * import { ecommerce } from '@od-oneapp/analytics/shared';
+ * await analytics.emit(ecommerce.productViewed({ productId: 'prod-123' }));
+ * ```
+ *
+ * @module @od-oneapp/analytics/shared/emitters/ecommerce
+ */
+
+// Export all types
+export * from './types';
+
+// Export utilities
+export * from './utils';
+
+// Export all event functions
+export * from './events/cart-checkout';
+export * from './events/coupon';
+export * from './events/engagement';
+export * from './events/marketplace';
+export * from './events/order';
+export * from './events/product';
+export * from './events/registry';
+export * from './events/wishlist-sharing';
+
+// Export tracking functionality
+export * from './track-ecommerce';
+
+// Re-export commonly used constants for convenience
+export { ECOMMERCE_EVENTS } from './types';

package/src/shared/emitters/ecommerce/track-ecommerce.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Ecommerce tracking wrapper that integrates with the core emitter system
+ * Ecommerce tracking wrapper that integrates with the core emitter system
+ */
+
+import { track } from '../emitters';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../emitter-types';
+import type { EcommerceEventSpec } from './types';
+
+/**
+ * Convert an ecommerce event specification to a track payload
+ *
+ * @param eventSpec - The ecommerce event specification
+ * @param options - Optional emitter options
+ * @returns Track payload ready to be sent to analytics providers
+ */
+export function trackEcommerce(
+  eventSpec: EcommerceEventSpec,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  // Add ecommerce context to options
+  const enrichedOptions: EmitterOptions = {
+    ...options,
+    context: {
+      ...options?.context,
+      // Add ecommerce-specific context if needed
+      ...(eventSpec.category && {
+        // Store category as a custom field since EmitterContext doesn't have category
+        traits: {
+          ...options?.context?.traits,
+          event_category: eventSpec.category,
+        },
+      }),
+    },
+  };
+
+  // Return the track payload with the event name and properties
+  return track(eventSpec.name, eventSpec.properties, enrichedOptions);
+}
+
+/**
+ * Helper to create a tracking function for a specific ecommerce event
+ * This allows for cleaner usage in applications
+ */
+export function createEcommerceTracker<T extends Record<string, any>>(
+  eventFactory: (properties: T) => EcommerceEventSpec,
+) {
+  return (properties: T, options?: EmitterOptions): EmitterTrackPayload => {
+    const eventSpec = eventFactory(properties);
+    return trackEcommerce(eventSpec, options);
+  };
+}

package/src/shared/emitters/ecommerce/types.ts

@@ -0,0 +1,314 @@
+/**
+ * @fileoverview Platform-standard ecommerce event types
+ * Platform-standard ecommerce event types
+ * Based on industry best practices for ecommerce tracking
+ */
+
+// Base product properties shared across events
+export interface BaseProductProperties {
+  affiliate_link?: string | undefined;
+  affiliate_network?: string | undefined;
+  availability?: 'in_stock' | 'out_of_stock' | 'preorder' | 'discontinued' | undefined;
+  brand?: string | undefined;
+  category?: string | undefined;
+  commission_amount?: number | undefined;
+  commission_rate?: number | undefined;
+  condition?: 'new' | 'used' | 'refurbished' | undefined;
+  coupon?: string | undefined;
+  gtin?: string | undefined;
+  image_url?: string | undefined;
+  // Marketplace/affiliate properties (optional for any product)
+  merchant_id?: string | undefined;
+  merchant_name?: string | undefined;
+  merchant_url?: string | undefined;
+  mpn?: string | undefined;
+  name?: string | undefined;
+  original_price?: number | undefined;
+  position?: number | undefined;
+  price?: number | undefined;
+  product_id: string;
+  quantity?: number | undefined;
+  sale_price?: number | undefined;
+  url?: string | undefined;
+  variant?: string | undefined;
+}
+
+// Extended product properties for detailed tracking
+export interface ExtendedProductProperties extends BaseProductProperties {
+  currency?: string | undefined;
+  value?: number | undefined;
+}
+
+// Registry-specific properties
+export interface RegistryProperties {
+  co_registrant_id?: string | undefined;
+  co_registrant_name?: string | undefined;
+  event_date?: string | undefined;
+  privacy_setting?: 'public' | 'private' | 'unlisted' | undefined;
+  registry_id: string;
+  registry_name?: string | undefined;
+  registry_type?: 'wedding' | 'baby' | 'birthday' | 'universal' | 'custom' | undefined;
+  registry_url?: string | undefined;
+}
+
+// Registry item properties
+export interface RegistryItemProperties extends BaseProductProperties {
+  merchant_id?: string | undefined;
+  merchant_name?: string | undefined;
+  notes?: string | undefined;
+  priority?: 'high' | 'medium' | 'low' | undefined;
+  purchased_quantity?: number | undefined;
+  registry_id: string;
+  requested_quantity?: number | undefined;
+}
+
+// Properties for product list events
+export interface ProductListProperties {
+  category?: string | undefined;
+  list_id?: string | undefined;
+  products?: BaseProductProperties[] | undefined;
+}
+
+// Properties for cart events
+export interface CartProperties {
+  cart_id?: string | undefined;
+  products?: BaseProductProperties[] | undefined;
+}
+
+// Properties for checkout events
+export interface CheckoutProperties {
+  checkout_id?: string | undefined;
+  payment_method?: string | undefined;
+  products?: BaseProductProperties[] | undefined;
+  shipping_method?: string | undefined;
+  step?: number | undefined;
+}
+
+// Properties for order events
+export interface OrderProperties {
+  affiliation?: string | undefined;
+  coupon?: string | undefined;
+  currency?: string | undefined;
+  discount?: number | undefined;
+  order_id: string;
+  products?: BaseProductProperties[] | undefined;
+  revenue?: number | undefined;
+  shipping?: number | undefined;
+  tax?: number | undefined;
+  total?: number | undefined;
+}
+
+// Properties for coupon events
+export interface CouponProperties {
+  cart_id?: string | undefined;
+  coupon_id?: string | undefined;
+  coupon_name?: string | undefined;
+  discount?: number | undefined;
+  order_id?: string | undefined;
+  reason?: string | undefined;
+}
+
+// Properties for wishlist events
+export interface WishlistProperties extends BaseProductProperties {
+  wishlist_id?: string | undefined;
+  wishlist_name?: string | undefined;
+}
+
+// Properties for sharing events
+export interface SharingProperties {
+  recipient?: string | undefined;
+  share_message?: string | undefined;
+  share_via?: string | undefined;
+}
+
+// Properties for review events
+export interface ReviewProperties {
+  product_id: string;
+  rating?: string | undefined;
+  review_body?: string | undefined;
+  review_id?: string | undefined;
+}
+
+// Properties for search results
+export interface SearchResultsProperties {
+  filters_applied?: Record<string, any>;
+  products?: BaseProductProperties[];
+  query: string;
+  results_count: number;
+  sort_order?: string;
+}
+
+// Properties for cart updates
+export interface CartUpdateProperties {
+  action: 'added' | 'removed' | 'updated';
+  cart_id?: string;
+  cart_total?: number;
+  product: BaseProductProperties;
+  quantity_change?: number;
+}
+
+// Properties for cart abandonment
+export interface CartAbandonmentProperties {
+  abandonment_reason?: 'timeout' | 'navigation' | 'closed';
+  cart_id: string;
+  cart_value: number;
+  products: BaseProductProperties[];
+  time_in_cart?: number;
+}
+
+// Properties for checkout progression
+export interface CheckoutProgressProperties {
+  action: 'viewed' | 'completed' | 'abandoned' | 'error';
+  checkout_id?: string;
+  error_message?: string;
+  payment_method?: string;
+  products?: BaseProductProperties[];
+  shipping_method?: string;
+  step: number;
+  step_name: string;
+}
+
+// Properties for order status updates
+export interface OrderStatusProperties {
+  carrier?: string;
+  estimated_delivery?: string;
+  order_id: string;
+  previous_status?: string;
+  status:
+    | 'confirmed'
+    | 'processing'
+    | 'shipped'
+    | 'out_for_delivery'
+    | 'delivered'
+    | 'returned'
+    | 'failed';
+  tracking_number?: string;
+}
+
+// Properties for product comparison
+export interface ProductComparisonProperties {
+  action: 'added' | 'removed' | 'viewed';
+  comparison_list?: BaseProductProperties[];
+  product: BaseProductProperties;
+}
+
+// Properties for recommendations
+export interface RecommendationProperties {
+  algorithm?: string;
+  products: BaseProductProperties[];
+  recommendation_type:
+    | 'similar'
+    | 'frequently_bought'
+    | 'trending'
+    | 'personalized'
+    | 'upsell'
+    | 'cross_sell';
+  source: string; // e.g., 'product_page', 'cart', 'checkout'
+}
+
+// Properties for engagement events
+export interface EngagementProperties {
+  action_type: 'price_alert' | 'back_in_stock' | 'favorite';
+  notification_method?: 'email' | 'sms' | 'push';
+  product_id: string;
+  threshold_price?: number;
+}
+
+// Properties for returns
+export interface ReturnProperties {
+  order_id: string;
+  products: BaseProductProperties[];
+  reason: string;
+  refund_amount?: number;
+  return_id?: string;
+  return_method?: 'mail' | 'store' | 'pickup';
+}
+
+// Standard ecommerce event names
+export const ECOMMERCE_EVENTS = {
+  PRODUCT_CLICKED: 'Product Clicked',
+  PRODUCT_COMPARED: 'Product Compared',
+  PRODUCT_LIST_FILTERED: 'Product List Filtered',
+  PRODUCT_LIST_VIEWED: 'Product List Viewed',
+  PRODUCT_RECOMMENDATION_CLICKED: 'Product Recommendation Clicked',
+  PRODUCT_RECOMMENDATION_VIEWED: 'Product Recommendation Viewed',
+  // Search & Discovery events
+  PRODUCT_SEARCHED: 'Product Searched',
+  PRODUCT_VIEWED: 'Product Viewed',
+  SEARCH_RESULTS_VIEWED: 'Search Results Viewed',
+
+  CART_ABANDONED: 'Cart Abandoned',
+  // Cart events
+  CART_UPDATED: 'Cart Updated',
+  CART_VIEWED: 'Cart Viewed',
+
+  // Checkout events
+  CHECKOUT_PROGRESSED: 'Checkout Progressed',
+
+  ORDER_CANCELLED: 'Order Cancelled',
+  // Order events
+  ORDER_COMPLETED: 'Order Completed',
+  ORDER_FAILED: 'Order Failed',
+  ORDER_REFUNDED: 'Order Refunded',
+  ORDER_STATUS_UPDATED: 'Order Status Updated',
+
+  // Coupon events
+  COUPON_APPLIED: 'Coupon Applied',
+  COUPON_REMOVED: 'Coupon Removed',
+
+  // Wishlist events
+  PRODUCT_ADDED_TO_WISHLIST: 'Product Added to Wishlist',
+  PRODUCT_REMOVED_FROM_WISHLIST: 'Product Removed from Wishlist',
+  WISHLIST_PRODUCT_ADDED_TO_CART: 'Wishlist Product Added to Cart',
+
+  CART_SHARED: 'Cart Shared',
+  // Sharing events
+  PRODUCT_SHARED: 'Product Shared',
+
+  // Review events
+  PRODUCT_REVIEWED: 'Product Reviewed',
+
+  AFFILIATE_CONVERSION_TRACKED: 'Affiliate Conversion Tracked',
+  AFFILIATE_LINK_CLICKED: 'Affiliate Link Clicked',
+  // Marketplace-specific events
+  MERCHANT_SELECTED: 'Merchant Selected',
+  PRICE_COMPARISON_VIEWED: 'Price Comparison Viewed',
+
+  REGISTRY_ITEM_MANAGED: 'Registry Item Managed',
+  // Registry events
+  REGISTRY_MANAGED: 'Registry Managed',
+  REGISTRY_SHARED: 'Registry Shared',
+  REGISTRY_VIEWED: 'Registry Viewed',
+
+  RETURN_COMPLETED: 'Return Completed',
+  // Post-purchase events
+  RETURN_REQUESTED: 'Return Requested',
+
+  BACK_IN_STOCK_REQUESTED: 'Back In Stock Requested',
+  // Engagement events
+  PRICE_ALERT_SET: 'Price Alert Set',
+} as const;
+
+export type EcommerceEventName = (typeof ECOMMERCE_EVENTS)[keyof typeof ECOMMERCE_EVENTS];
+
+// Event specification interface
+export interface EcommerceEventSpec<T = any> {
+  category: 'ecommerce';
+  name: EcommerceEventName;
+  properties: T;
+  requiredProperties: (keyof T)[];
+}
+
+// Union type for all ecommerce event properties
+export type EcommerceEventProperties =
+  | BaseProductProperties
+  | ExtendedProductProperties
+  | ProductListProperties
+  | CartProperties
+  | CheckoutProperties
+  | OrderProperties
+  | CouponProperties
+  | WishlistProperties
+  | (BaseProductProperties & SharingProperties)
+  | (CartProperties & SharingProperties)
+  | ReviewProperties;