@od-oneapp/analytics 2026.1.1301

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

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Utilities for normalizing and validating ecommerce event properties
+ * Utilities for normalizing and validating ecommerce event properties
+ */
+
+import type { BaseProductProperties, EcommerceEventProperties } from './types';
+
+/**
+ * Input product type for normalization functions
+ * Accepts various property naming conventions
+ */
+interface ProductInput {
+  // ID variations
+  product_id?: string;
+  productId?: string;
+  id?: string;
+  // Name variations
+  name?: string;
+  title?: string;
+  productName?: string;
+  // Image URL variations
+  image_url?: string;
+  imageUrl?: string;
+  image?: string;
+  // URL variations
+  url?: string;
+  link?: string;
+  product_url?: string;
+  // Other properties
+  brand?: string;
+  manufacturer?: string;
+  category?: string;
+  coupon?: string;
+  couponCode?: string;
+  coupon_code?: string;
+  position?: number | string;
+  price?: number | string;
+  quantity?: number | string;
+  variant?: string;
+  variation?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Normalizes product properties to ensure consistent naming
+ * Handles common variations like productId vs product_id
+ */
+export function normalizeProductProperties(
+  product?: ProductInput | unknown,
+): BaseProductProperties {
+  if (!product || typeof product !== 'object') {
+    throw new Error('Product properties are required');
+  }
+
+  const p = product as ProductInput;
+
+  // Normalize product ID (required) - using ES2022 nullish coalescing
+  const product_id = p.product_id ?? p.productId ?? p.id;
+  if (!product_id) {
+    throw new Error('Product must have an id (product_id, productId, or id)');
+  }
+
+  const normalized = {
+    product_id,
+    name: p.name ?? p.title ?? p.productName,
+    image_url: p.image_url ?? p.imageUrl ?? p.image,
+    url: p.url ?? p.link ?? p.product_url,
+    brand: p.brand ?? p.manufacturer,
+    category: p.category,
+    coupon: p.coupon ?? p.couponCode ?? p.coupon_code,
+    position: normalizePosition(p.position),
+    price: normalizePrice(p.price),
+    quantity: normalizeQuantity(p.quantity),
+    variant: p.variant ?? p.variation,
+  };
+
+  // Remove undefined and null values - using ES2022 Object.hasOwn
+  const result: BaseProductProperties = { product_id };
+  Object.entries(normalized).forEach(([key, value]) => {
+    if (
+      value !== undefined &&
+      value !== null &&
+      Object.hasOwn(normalized, key) &&
+      key !== 'product_id'
+    ) {
+      // Cast to any to allow dynamic property assignment
+      (result as any)[key] = value;
+    }
+  });
+
+  return result;
+}
+
+/**
+ * Normalizes an array of products
+ */
+export function normalizeProducts(products: unknown[]): BaseProductProperties[] {
+  if (!Array.isArray(products)) {
+    return [];
+  }
+  return products.map(product => normalizeProductProperties(product as ProductInput));
+}
+
+/**
+ * ES2022 enhanced product validation with Error.cause
+ */
+export function validateProductWithContext(product: unknown, context?: string): void {
+  try {
+    normalizeProductProperties(product as ProductInput);
+  } catch (error) {
+    throw new Error(`Product validation failed${context ? ` in ${context}` : ''}`, {
+      cause: error,
+    });
+  }
+}
+
+/**
+ * Normalizes price to a number
+ */
+function normalizePrice(price: unknown): number | undefined {
+  if (price === undefined || price === null) {
+    return undefined;
+  }
+  const normalized = typeof price === 'string' ? Number.parseFloat(price) : Number(price);
+  return Number.isNaN(normalized) ? undefined : normalized;
+}
+
+/**
+ * Normalizes quantity to a positive integer
+ */
+function normalizeQuantity(quantity: unknown): number | undefined {
+  if (quantity === undefined || quantity === null) {
+    return undefined;
+  }
+  const normalized = Number.parseInt(String(quantity), 10);
+  return Number.isNaN(normalized) || normalized < 0 ? undefined : normalized;
+}
+
+/**
+ * Normalizes position to a positive integer
+ */
+function normalizePosition(position: unknown): number | undefined {
+  if (position === undefined || position === null) {
+    return undefined;
+  }
+  const normalized = Number.parseInt(String(position), 10);
+  return Number.isNaN(normalized) || normalized < 0 ? undefined : normalized;
+}
+
+/**
+ * Validates required properties for an event
+ */
+export function validateRequiredProperties<T extends Record<string, any>>(
+  properties: T,
+  required: (keyof T)[],
+): void {
+  const missing = required.filter(prop => {
+    const value = properties[prop];
+    return value === undefined || value === null || value === '';
+  });
+  if (missing.length > 0) {
+    throw new Error(`Missing required properties: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Removes undefined values from an object
+ */
+export function cleanProperties<T extends Record<string, any>>(obj: T): Partial<T> {
+  const cleaned: Partial<T> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) {
+      cleaned[key as keyof T] = value;
+    }
+  }
+  return cleaned;
+}
+
+/**
+ * Merges common fields with event-specific properties
+ */
+export function mergeEventProperties(
+  specific: EcommerceEventProperties,
+  common?: Record<string, any>,
+): EcommerceEventProperties {
+  return {
+    ...common,
+    ...specific,
+  };
+}
+
+/**
+ * Validates currency code (ISO 4217)
+ */
+export function validateCurrency(currency?: string): string | undefined {
+  if (!currency || typeof currency !== 'string') return undefined;
+
+  // Basic validation - should be 3 uppercase letters
+  const normalized = currency.toUpperCase();
+  if (!/^[A-Z]{3}$/.test(normalized)) {
+    // Invalid currency code - return undefined
+    return undefined;
+  }
+
+  return normalized;
+}
+
+/**
+ * Creates a consistent context object for ecommerce events
+ */
+export function createEcommerceContext(additionalContext?: Record<string, any>) {
+  return {
+    ...additionalContext,
+    category: 'ecommerce',
+  };
+}