@salla.sa/ecommerce-events-base

@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

• Scans your src/listeners/ directory for .ts files
• Parses each file to extract eventName and default export
• Generates src/auto-listeners-registry.ts with all mappings
• 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

• Install the package and configure the Vite plugin
• Create event listeners in src/listeners/ following the pattern
• Run your development server - plugin auto-generates registry
• Build your project - registry is included in the build
• 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.