npm package: @overvio/woocommerce
Description: WooCommerce integration for Overvio SDK - Cart adapter and auto-init
Author: Overvio
Latest version: 1.0.0

# @overvio/woocommerce

WooCommerce integration for Overvio SDK - provides automatic cart tracking, checkout funnel events, coupon tracking, and more.

## Installation

```bash
npm install @overvio/woocommerce @overvio/sdk
# or
pnpm add @overvio/woocommerce @overvio/sdk
```

## Quick Start

### Via CDN (Recommended for WordPress)

Add the following PHP to your theme's `functions.php` or plugin:

```php
add_action('wp_footer', function() {
  $context = [
    'apiKey' => 'pk_live_your_api_key',
    'user' => is_user_logged_in() ? [
      'id' => get_current_user_id(),
      'email' => wp_get_current_user()->user_email,
      'firstName' => wp_get_current_user()->first_name,
      'lastName' => wp_get_current_user()->last_name,
    ] : null,
    'cart' => WC()->cart ? array_values(array_map(function($item, $key) {
      $product = $item['data'];
      return [
        'key' => $key,
        'product_id' => $item['product_id'],
        'variation_id' => $item['variation_id'] ?? 0,
        'quantity' => $item['quantity'],
        'product_name' => $product->get_name(),
        'product_sku' => $product->get_sku(),
        'line_total' => $item['line_total'],
        'line_subtotal' => $item['line_subtotal'],
        'variation' => $item['variation'] ?? [],
      ];
    }, WC()->cart->get_cart(), array_keys(WC()->cart->get_cart()))) : [],
    'currency' => get_woocommerce_currency(),
    'pageType' => overvio_get_page_type(),
  ];

  echo '<script>window.OvervioContext = ' . json_encode($context) . ';</script>';
  echo '<script src="https://cdn.overvio.ai/v1/woocommerce.min.js" defer></script>';
});

function overvio_get_page_type() {
  if (is_front_page() || is_home()) return 'home';
  if (is_shop()) return 'shop';
  if (is_product()) return 'product';
  if (is_product_category()) return 'product_category';
  if (is_product_tag()) return 'product_tag';
  if (is_cart()) return 'cart';
  if (is_checkout()) return 'checkout';
  if (is_wc_endpoint_url('order-received')) return 'order_received';
  if (is_account_page()) return 'my_account';
  return 'other';
}
```

### Via NPM (for bundled builds)

```typescript
import { initWooCommerce } from '@overvio/woocommerce';

const sdk = initWooCommerce({
  apiKey: 'pk_live_your_api_key', // Optional if in OvervioContext
  debug: true, // Enable console logging
});
```

## Features

### Automatic Tracking

The WooCommerce integration automatically tracks:

- **view_cart**: When the cart page is loaded
- **begin_checkout**: When checkout page initializes
- **add_shipping_info**: When shipping method is selected
- **add_payment_info**: When payment method is selected
- **order_completed**: On thank you page (requires PHP setup)
- **coupon_applied**: When a coupon is successfully applied
- **coupon_failed**: When coupon application fails
- **coupon_removed**: When a coupon is removed

### Cart Adapter

The cart adapter syncs cart state with WooCommerce:

```typescript
import { WooCommerceCartAdapter } from '@overvio/woocommerce';

const adapter = new WooCommerceCartAdapter({ debug: true });

// Listen to cart changes
adapter.onChange((items) => {
  console.log('Cart updated:', items.length, 'items');
});

// Set source for next add-to-cart (for tracking context)
adapter.setNextSource('search');
```

## PHP Integration Requirements

### Order Tracking (Thank You Page)

To track order completions, add the following to your theme or plugin:

```php
add_action('woocommerce_thankyou', function($order_id) {
  $order = wc_get_order($order_id);
  if (!$order) return;

  $products = [];
  foreach ($order->get_items() as $item) {
    $product = $item->get_product();
    $products[] = [
      'productId' => (string) $product->get_id(),
      'name' => $item->get_name(),
      'quantity' => $item->get_quantity(),
      'price' => (float) ($item->get_total() / $item->get_quantity()),
      'sku' => $product->get_sku(),
      'categories' => wp_list_pluck(
        get_the_terms($product->get_id(), 'product_cat') ?: [],
        'name'
      ),
    ];
  }

  $order_data = [
    'orderId' => (string) $order_id,
    'orderNumber' => $order->get_order_number(),
    'total' => (float) $order->get_total(),
    'subtotal' => (float) $order->get_subtotal(),
    'currency' => $order->get_currency(),
    'products' => $products,
    'coupons' => $order->get_coupon_codes(),
    'discount' => (float) $order->get_total_discount(),
    'shipping' => (float) $order->get_shipping_total(),
    'tax' => (float) $order->get_total_tax(),
    'paymentMethod' => $order->get_payment_method(),
    'customer' => [
      'email' => $order->get_billing_email(),
      'firstName' => $order->get_billing_first_name(),
      'lastName' => $order->get_billing_last_name(),
    ],
    'billingCountry' => $order->get_billing_country(),
    'shippingCountry' => $order->get_shipping_country(),
  ];

  echo '<script>window.OvervioOrderData = ' . json_encode($order_data) . ';</script>';
});
```

### Enhanced Coupon Tracking

For detailed coupon tracking, expose coupon data via PHP:

```php
add_action('wp_footer', function() {
  if (!is_cart() && !is_checkout()) return;

  $coupon_map = [];
  foreach (WC()->cart->get_applied_coupons() as $code) {
    $coupon = new WC_Coupon($code);
    $coupon_map[strtolower($code)] = [
      'code' => $code,
      'type' => $coupon->get_discount_type(),
      'amount' => (float) $coupon->get_amount(),
    ];
  }

  if (!empty($coupon_map)) {
    echo '<script>window.OvervioCouponDataMap = ' . json_encode($coupon_map) . ';</script>';
  }
});
```

### Checkout Events Enhancement

The SDK listens to standard WooCommerce jQuery events for checkout tracking. Ensure your theme triggers these events:

- `init_checkout` - Fired when checkout page loads
- `updated_checkout` - Fired when checkout form updates
- `applied_coupon` - Fired when coupon is applied
- `removed_coupon` - Fired when coupon is removed

## Configuration Options

```typescript
interface InitWooCommerceOptions {
  /** Override apiKey from context */
  apiKey?: string;

  /** SDK modules to enable (default: ['events', 'cart']) */
  modules?: ('events' | 'cart' | 'search' | 'banners' | 'recommendations')[];

  /** Custom API endpoints */
  endpoints?: {
    api?: string;
    events?: string;
  };

  /** Disable cart adapter (default: false) */
  disableCartAdapter?: boolean;

  /** Disable auto user identification (default: false) */
  disableAutoIdentify?: boolean;

  /** Disable order tracking on thank you page (default: false) */
  disableOrderTracking?: boolean;

  /** Disable page tracking (view_cart) (default: false) */
  disablePageTracking?: boolean;

  /** Disable checkout funnel tracking (default: false) */
  disableCheckoutTracking?: boolean;

  /** Disable coupon tracking (default: false) */
  disableCouponTracking?: boolean;

  /** Enable debug logging (default: false) */
  debug?: boolean;
}
```

## Manual Tracking

### Track View Cart (e.g., for cart drawer)

```typescript
import { trackViewCart } from '@overvio/woocommerce';

// When cart drawer/modal opens
cartDrawer.addEventListener('open', () => {
  trackViewCart(sdk, { debug: true });
});
```

### Track with Custom Source

```typescript
import { initWooCommerce, WooCommerceCartAdapter } from '@overvio/woocommerce';

const sdk = initWooCommerce();
const adapter = sdk.cart.getManager()?.getAdapter() as WooCommerceCartAdapter;

// Before adding to cart from search results
adapter?.setNextSource('search');
// ... add to cart action
```

## Events Tracked

| Event | Trigger | Required Context |
|-------|---------|------------------|
| `view_cart` | Cart page load | `pageType: 'cart'` |
| `begin_checkout` | Checkout page init | `pageType: 'checkout'` |
| `add_shipping_info` | Shipping method selected | Checkout page |
| `add_payment_info` | Payment method selected | Checkout page |
| `order_completed` | Thank you page load | `OvervioOrderData` |
| `coupon_applied` | Coupon applied via jQuery event | Cart/Checkout |
| `coupon_failed` | Coupon AJAX returns error | Cart/Checkout |
| `coupon_removed` | Coupon removed via jQuery event | Cart/Checkout |

## TypeScript Types

All types are exported for TypeScript users:

```typescript
import type {
  InitWooCommerceOptions,
  WooCommerceContext,
  WooCommerceCartItem,
  WooCommerceOrderData,
  WooCommercePageType,
  CartSource,
} from '@overvio/woocommerce';
```

## License

MIT