@salla.sa/ecommerce-events-base

A comprehensive TypeScript package providing type-safe ecommerce event tracking with automatic listener discovery for Salla applications.

🚀 Features

• Complete TypeScript Types: Full type definitions for Segment Ecommerce v2 events
• Auto-Discovery Plugin: Vite plugin that automatically discovers and registers event listeners
• Type-Safe Interface: Strongly typed interface for Salla analytics tracker
• Browser & Node.js Support: Dual exports for different environments
• Zero Configuration: Works out of the box with conventional file structure

📦 Installation

npm install @salla.sa/ecommerce-events-base

🏗️ Quick Start

1. Install and Configure Vite Plugin

// vite.config.ts
import { defineConfig } from 'vite';
import { AutoRegistryEventsPlugin } from '@salla.sa/ecommerce-events-base/plugin';

export default defineConfig({
  plugins: [
    AutoRegistryEventsPlugin()
  ]
});

2. Create Event Listeners

Create listeners in your src/listeners/ directory following this pattern:

// src/listeners/product-viewed.ts
import { ProductViewedPayload, EcommerceEvents } from '@salla.sa/ecommerce-events-base';

export const eventName = EcommerceEvents.PRODUCT_VIEWED;

export default (payload: ProductViewedPayload): void => {
  console.log('Product viewed:', payload);

  // Your custom tracking logic here
  // e.g., send to analytics service
};

3. Use Types in Your Application

import {
  Product,
  Order,
  EcommerceEvents,
  ProductViewedPayload,
  SallaTracker
} from '@salla.sa/ecommerce-events-base';

// Type-safe product definition
const product: Product = {
  product_id: '123',
  name: 'Sample Product',
  price: 29.99,
  category: 'Electronics'
};

// Type-safe tracker implementation
const tracker: SallaTracker = {
  name: 'my-custom-tracker',
  track: (eventName: string, payload: any) => {
    console.log(`Tracking ${eventName}:`, payload);
  }
};

🔧 Auto-Discovery Plugin

The AutoRegistryEventsPlugin automatically:

• Discovers event listeners in src/listeners/ directory
• Generates an auto-registry file mapping events to handlers
• Supports both development and build modes
• Validates listener file patterns for consistency

How It Works

1. Scans your src/listeners/ directory for .ts files
2. Parses each file to extract eventName and default export
3. Generates src/auto-listeners-registry.ts with all mappings
4. Registers listeners automatically during build/dev

Expected Listener Pattern

// src/listeners/[event-name].ts
import { [PayloadType], EcommerceEvents } from '@salla.sa/ecommerce-events-base';

// Required: Export the event name
export const eventName = EcommerceEvents.[EVENT_NAME];

// Required: Default export function with typed payload
export default (payload: [PayloadType]): void => {
  // Your event handling logic
};

📋 Available Types

Core Interfaces

| Interface | Description | |-----------|-------------| | Product | Product information structure | | Cart | Shopping cart structure | | Order | Order information structure | | Checkout | Checkout process structure | | Promotion | Promotion/discount structure |

Event Payload Types

| Payload Type | Event | Description | |--------------|-------|-------------| | ProductViewedPayload | Product Viewed | When a product is viewed | | ProductAddedPayload | Product Added | When a product is added to cart | | CartViewedPayload | Cart Viewed | When cart is viewed | | CheckoutStartedPayload | Checkout Started | When checkout process begins | | OrderCompletedPayload | Order Completed | When an order is completed | | CouponAppliedPayload | Coupon Applied | When a coupon is applied | | WishlistProductAddedPayload | Wishlist Product Added | When product added to wishlist |

Enums

| Enum | Description | |------|-------------| | EcommerceEvents | All supported event names |

Tracker Interface

interface SallaTracker {
  name: string;
  track: (eventName: string, payload: EcommerceEventPayload) => void;
  page?: (payload: any) => void;
}

🎯 Usage Examples

Basic Event Listener

// src/listeners/order-completed.ts
import { OrderCompletedPayload, EcommerceEvents } from '@salla.sa/ecommerce-events-base';

export const eventName = EcommerceEvents.ORDER_COMPLETED;

export default (payload: OrderCompletedPayload): void => {
  // Send to analytics
  gtag('event', 'purchase', {
    transaction_id: payload.order_id,
    value: payload.total,
    currency: payload.currency,
    items: payload.products.map(product => ({
      item_id: product.product_id,
      item_name: product.name,
      category: product.category,
      quantity: product.quantity,
      price: product.price
    }))
  });
};

Advanced Listener with Multiple Services

// src/listeners/product-added.ts
import { ProductAddedPayload, EcommerceEvents } from '@salla.sa/ecommerce-events-base';

export const eventName = EcommerceEvents.PRODUCT_ADDED;

export default (payload: ProductAddedPayload): void => {
  // Multiple tracking services

  // Google Analytics
  gtag('event', 'add_to_cart', {
    currency: 'SAR',
    value: payload.price * (payload.quantity || 1),
    items: [{
      item_id: payload.product_id,
      item_name: payload.name,
      category: payload.category,
      quantity: payload.quantity || 1,
      price: payload.price
    }]
  });

  // Facebook Pixel
  fbq('track', 'AddToCart', {
    content_ids: [payload.product_id],
    content_type: 'product',
    value: payload.price,
    currency: 'SAR'
  });

  // Custom API
  fetch('/api/track', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      event: 'product_added',
      payload
    })
  });
};

🔍 Plugin Configuration

The plugin works with zero configuration, but you can customize its behavior:

// vite.config.ts
import { defineConfig } from 'vite';
import { AutoRegistryEventsPlugin } from '@salla.sa/ecommerce-events-base/plugin';

export default defineConfig({
  plugins: [
    AutoRegistryEventsPlugin({
      // Plugin automatically discovers listeners in src/listeners/
      // No configuration needed for standard setups
    })
  ]
});

📁 Project Structure

your-project/
├── src/
│   ├── listeners/           # Event listeners directory
│   │   ├── product-viewed.ts
│   │   ├── cart-viewed.ts
│   │   ├── order-completed.ts
│   │   └── ...
│   ├── auto-listeners-registry.ts  # Auto-generated (don't edit)
│   └── index.ts
├── vite.config.ts          # Vite configuration
└── package.json

🚦 Development Workflow

1. Install the package and configure the Vite plugin
2. Create event listeners in src/listeners/ following the pattern
3. Run your development server - plugin auto-generates registry
4. Build your project - registry is included in the build
5. Deploy - all listeners are automatically registered

🔧 Troubleshooting

Plugin Not Discovering Listeners

Ensure your listeners follow the exact pattern:

• Located in src/listeners/ directory
• Export eventName from EcommerceEvents enum
• Export default function with typed payload

TypeScript Errors

Make sure you're importing types correctly:

import { EcommerceEvents, ProductViewedPayload } from '@salla.sa/ecommerce-events-base';

Build Issues

The plugin requires Node.js environment for file system operations. It's automatically excluded from browser builds.

📄 License

MIT © Salla

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.