@storepecker/storefront-analytics

TypeScript client for the storefront analytics API. Tracks pages and events in storefront.

Install

npm install @yourorg/storefront-analytics

Setup

import { createAnalytics } from '@yourorg/storefront-analytics';

export const analytics = createAnalytics({
  baseUrl: 'https://mystore.com',
  token: getUserJwt(), // optional — include when the user is logged in
});

When token is provided, events are automatically linked to the customer's account (identity stitching). Pass undefined for anonymous visitors.

Update the token after login:

analytics.setToken(jwt);   // on login
analytics.setToken(undefined); // on logout

Page Views

Fire on every SPA route change:

// Basic
analytics.pageView({ path: '/shop/classic-cotton-tee' });

// With UTM params (read from URL query string)
analytics.pageView({
  path: '/',
});

Cart Events

// Add to cart
analytics.addToCart({ product_variant_id: 42, quantity: 2 });

// Remove from cart
analytics.removeFromCart({ product_variant_id: 42, quantity: 1 });

quantity defaults to 1 if omitted.

Checkout Funnel

Fire these in order as the customer progresses through checkout:

// 1. User arrives on checkout page
analytics.checkoutStarted({ event_value: 2500.00, item_count: 3 });

// 2. User fills in shipping address
analytics.addressEntered({ event_value: 2500.00 });

// 3. User picks a shipping method
analytics.shippingSelected({ event_value: 2500.00, shipping_method: 'standard' });

// 4. User selects payment method
analytics.paymentSelected({ event_value: 2500.00, payment_method: 'razorpay' });

// 5. User clicks "Pay Now"
analytics.paymentInitiated({ event_value: 2500.00, payment_method: 'razorpay' });

// ✓ "Order completed" is recorded server-side — no frontend call needed.

All event_value and item_count fields are optional and default to 0.

Supported payment_method values: razorpay, phonepe, stripe, cod.

API Reference

| Method | Description | |---|---| | pageView({ path, utm_params? }) | Page view on every route change | | addToCart({ product_variant_id, quantity? }) | Item added to cart | | removeFromCart({ product_variant_id, quantity? }) | Item removed from cart | | checkoutStarted({ event_value?, item_count? }) | Checkout page visited | | addressEntered({ event_value? }) | Shipping address completed | | shippingSelected({ event_value?, shipping_method? }) | Shipping method chosen | | paymentSelected({ event_value?, payment_method? }) | Payment method chosen | | paymentInitiated({ event_value?, payment_method? }) | "Pay Now" clicked | | setToken(token) | Update JWT after login/logout |

All methods return Promise<void> and throw on non-2xx responses.