@elevateab/sdk 1.1.2 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @elevateab/sdk
 
-Elevate AB Testing SDK for Hydrogen and Remix frameworks.
+Elevate AB Testing SDK for Shopify Hydrogen and Next.js with built-in analytics tracking and cart attribute tagging.
 
 ## Installation
 
@@ -8,142 +8,519 @@ Elevate AB Testing SDK for Hydrogen and Remix frameworks.
 npm install @elevateab/sdk
 ```
 
-## Usage
+**Peer Dependencies:**
 
-### Automatic Config Loading
+- `react` >= 18.0.0
+- `@shopify/hydrogen` >= 2023.10.0 (optional - only for Hydrogen)
 
-The easiest way to use the SDK is with `ElevateProvider`. It automatically fetches all active experiments from the CDN and makes them available throughout your app:
+## Framework Support
+
+| Framework            | Support | Analytics Mode                 |
+| -------------------- | ------- | ------------------------------ |
+| **Shopify Hydrogen** | ✅ Full | Automatic via `useAnalytics()` |
+| **Next.js**          | ✅ Full | Manual tracking functions      |
+| **Remix**            | ✅ Full | Manual tracking functions      |
+| **Other React**      | ✅ Full | Manual tracking functions      |
+
+## Quick Start
+
+### 1. Setup ElevateProvider
+
+Wrap your app with `ElevateProvider` - it handles everything (config fetching, analytics tracking, and event sending):
 
 ```typescript
-import { ElevateProvider, Experiment, VariantDisplay } from "@elevateab/sdk";
+import { ElevateProvider } from "@elevateab/sdk";
+
+export default function Root() {
+  const data = useLoaderData<typeof loader>();
 
-function App() {
   return (
-    <ElevateProvider storeId="mystore.myshopify.com">
-      <ProductPage />
+    <ElevateProvider
+      storeId="mystore.myshopify.com"
+      cart={data.cart}
+      shop={data.shop}
+      consent={data.consent}
+      storefrontUrl={data.shop.primaryDomain.url}
+    >
+      <Outlet />
     </ElevateProvider>
   );
 }
+```
+
+**That's it!** The `ElevateProvider` automatically:
+
+- ✅ Fetches test configurations from CDN
+- ✅ Sets up Shopify Analytics tracking
+- ✅ Tracks all analytics events with A/B test data
+- ✅ Sends events to CloudFlare Worker
+- ✅ Manages visitor IDs and session tracking
+
+### 2. Use A/B Tests in Your Components
+
+```typescript
+import { useExperiment } from "@elevateab/sdk";
 
 function ProductPage() {
+  const { variant, isLoading } = useExperiment("test-price-1");
+
+  if (isLoading) return <div>Loading...</div>;
+
   return (
     <div>
-      {/* Price test - Only the assigned variant will render */}
-      <Experiment testId="exp-123" userId="user-123">
-        <VariantDisplay variantId="control">
-          <Price amount={99.99} />
-        </VariantDisplay>
-        <VariantDisplay variantId="variant-a">
-          <Price amount={89.99} />
-        </VariantDisplay>
-      </Experiment>
-
-      {/* Headline test */}
-      <Experiment testId="exp-456" userId="user-123">
-        <VariantDisplay variantId="control">
-          <h1>Original Headline</h1>
-        </VariantDisplay>
-        <VariantDisplay variantId="variant-b">
-          <h1>New Headline</h1>
-        </VariantDisplay>
-      </Experiment>
+      {variant?.isControl ? <Price amount={99.99} /> : <Price amount={89.99} />}
     </div>
   );
 }
 ```
 
+## How It Works
+
+### Automatic Analytics Tracking
+
+The `ElevateProvider` automatically tracks the following Shopify analytics events and enriches them with A/B test data:
+
+- `page_viewed` - Page views with test assignments
+- `product_viewed` - Product views
+- `product_added_to_cart` - Add to cart events
+- `product_removed_from_cart` - Remove from cart events
+- `cart_viewed` - Cart page views
+
+### Event Data Structure
+
+Events are sent to CloudFlare Worker with:
+
+- **Test Assignments** (`ab_test_assignments`) - All tests the user is assigned to
+- **Test Views** (`ab_test_views`) - Tests the user has actually viewed
+- **UTM Parameters** - Campaign tracking data
+- **Device/Browser Info** - User agent, device type, OS
+- **Referrer Source** - Traffic source (Google, Facebook, Direct, etc.)
+- **Product/Cart Data** - Product IDs, prices, quantities
+
+**No additional setup needed** - just use `ElevateProvider` and everything works automatically!
+
+## Cart Attribute Tagging
+
+Carts are **automatically tagged** with A/B test data for order attribution.
+
+### For Hydrogen Stores
+
+Cart attributes are automatically updated when `product_added_to_cart` event fires, **if you provide the `storefrontAccessToken`**:
+
+```typescript
+<ElevateProvider
+  storeId="mystore.myshopify.com"
+  cart={data.cart}
+  shop={data.shop}
+  consent={data.consent}
+  storefrontAccessToken={env.PUBLIC_STOREFRONT_API_TOKEN} // ← Add this!
+>
+  <Outlet />
+</ElevateProvider>
+```
+
+**That's it!** When users add items to cart, we automatically:
+
+1. Track the `product_added_to_cart` event
+2. Update cart attributes with A/B test data
+
+### For Next.js / Other Stores
+
+Pass `cartId` and `storefrontAccessToken` to `trackAddToCart()`:
+
+```typescript
+await trackAddToCart({
+  storeId: "mystore.myshopify.com",
+  productId: "123456789",
+  variantId: "987654321",
+  productPrice: 99.99,
+  productQuantity: 1,
+  currency: "USD",
+  // Add these to auto-update cart attributes:
+  cartId: cart.id,
+  storefrontAccessToken: process.env.NEXT_PUBLIC_STOREFRONT_TOKEN,
+});
+```
+
+### Manual Cart Tagging (If Needed)
+
+You can also manually update cart attributes:
+
+```typescript
+import { updateCartAttributes } from "@elevateab/sdk";
+
+await updateCartAttributes(cart.id, {
+  storefrontAccessToken: process.env.NEXT_PUBLIC_STOREFRONT_TOKEN,
+});
+```
+
+> ✅ **The Storefront Access Token is SAFE to use client-side!**
+> It's a PUBLIC token that Shopify designed for browser use. It can only read products and manage carts - it cannot do anything destructive.
+
+### Cart Attributes GraphQL Mutation
+
+If you want to handle cart attributes in your own GraphQL calls:
+
+```typescript
+import {
+  CART_ATTRIBUTES_UPDATE_MUTATION,
+  getCartAttributesPayload,
+} from "@elevateab/sdk";
+
+const attributes = getCartAttributesPayload();
+
+// Use in your GraphQL mutation
+const result = await storefrontClient.mutate({
+  mutation: CART_ATTRIBUTES_UPDATE_MUTATION,
+  variables: {
+    cartId: "gid://shopify/Cart/...",
+    attributes,
+  },
+});
+```
+
+## Usage Examples
+
 ### Using the Hook
 
 ```typescript
-import { ElevateProvider, useExperiment } from "@elevateab/sdk";
+import { useExperiment } from "@elevateab/sdk";
 
-function MyComponent() {
-  const { variant, isLoading } = useExperiment("exp-123", "user-123");
+function PriceTest() {
+  const { variant, isLoading } = useExperiment("test-price-1");
 
   if (isLoading) return <div>Loading...</div>;
 
+  // Use convenience flags
+  if (variant?.isA) return <Price amount={99.99} label="Original" />;
+  if (variant?.isB) return <Price amount={89.99} label="Sale Price" />;
+
+  return null;
+}
+```
+
+### Conditional Rendering
+
+```typescript
+function ContentTest() {
+  const { variant } = useExperiment("test-headline-1");
+
   return (
     <div>
-      {variant?.id === "control" ? (
-        <Price amount={99.99} />
+      {variant?.isControl ? (
+        <h1>Buy Now and Save!</h1>
       ) : (
-        <Price amount={89.99} />
+        <h1>Limited Time Offer - 20% Off</h1>
       )}
     </div>
   );
 }
 ```
 
+### Multiple Variations
+
+```typescript
+function MultiVariantTest() {
+  const { variant } = useExperiment("test-layout-1");
+
+  if (variant?.isA) return <LayoutA />;
+  if (variant?.isB) return <LayoutB />;
+  if (variant?.isC) return <LayoutC />;
+  if (variant?.isD) return <LayoutD />;
+
+  return <LayoutDefault />;
+}
+```
+
+## Advanced Usage
+
+### Cookie & Storage Management
+
+The SDK uses cookies and session storage for state management:
+
+**Cookies (1 year expiration):**
+
+- `eabUserId` - Persistent visitor ID
+- `ABTL` - Test assignments (which variant each test is assigned to)
+- `ABAU` - Unique test views (which tests have been viewed)
+- `_shopify_y` - Shopify client ID (read-only)
+
+**Session Storage:**
+
+- `eabSessionId` - Session identifier
+- `ABAV` - Session test views
+- `eabReferrer` - Entry referrer
+- `eabEntry` - Entry page URL
+
 ### Utility Functions
 
 ```typescript
 import {
   assignVariant,
-  validateConfig,
-  generateExperimentId,
-  calculateRevenueLift,
+  getTestList,
+  getVisitorId,
+  getSessionId,
+  parseAddViewData,
 } from "@elevateab/sdk";
 
-// Assign a variant based on weighted distribution
-const variant = assignVariant(config.variants, "user-123");
+// Get current test assignments
+const assignments = getTestList(); // { "test-1": "variant-a", "test-2": "control" }
 
-// Validate experiment configuration
-const isValid = validateConfig(config);
+// Get visitor ID
+const visitorId = getVisitorId(); // "uuid-v4"
 
-// Generate unique experiment ID
-const expId = generateExperimentId("My Test");
+// Get session ID
+const sessionId = getSessionId(); // "uuid-v4"
+
+// Parse analytics data
+const analyticsData = parseAddViewData({
+  referrer: document.referrer,
+  entryPage: window.location.href,
+  userAgent: navigator.userAgent,
+});
+// Returns: UTM params, device type, browser info, referrer source, etc.
+```
 
-// Calculate revenue lift
-const { lift, confidence } = calculateRevenueLift(
-  10000, // control revenue
-  12000, // variant revenue
-  500, // control sample size
-  500 // variant sample size
+### Device & Traffic Detection
+
+```typescript
+import {
+  getDeviceType,
+  getTrafficSource,
+  checkFacebookBrowser,
+  checkInstagramBrowser,
+} from "@elevateab/sdk";
+
+const device = getDeviceType(); // "desktop" | "tablet" | "mobile"
+const source = getTrafficSource(); // "facebook" | "google" | "direct" | etc.
+const isFB = checkFacebookBrowser(); // boolean
+const isIG = checkInstagramBrowser(); // boolean
+```
+
+### Custom Event Tracking
+
+For advanced use cases, access the analytics utilities directly:
+
+```typescript
+import {
+  extractProductId,
+  extractProductVariantId,
+  cleanCartToken,
+  sanitizeString,
+  roundToTwo,
+} from "@elevateab/sdk";
+
+// Extract IDs from Shopify GIDs
+const productId = extractProductId("gid://shopify/Product/123456");
+// Returns: "123456"
+
+const variantId = extractProductVariantId(
+  "gid://shopify/ProductVariant/789012"
 );
+// Returns: "789012"
+
+// Clean and sanitize data
+const cleanToken = cleanCartToken("token?param=value");
+const safeString = sanitizeString(userInput);
+const price = roundToTwo(99.999); // 100.00
+```
+
+## Test Types Support
+
+The SDK provides infrastructure for multiple test types:
+
+- **Split URL Tests** - Redirect tests between different URLs
+- **Price Tests** - A/B test different pricing strategies
+- **Content Tests** - Test different copy, headlines, CTAs
+- **Custom Code Tests** - Run custom JavaScript for advanced tests
+
+### Example: Split URL Test
+
+```typescript
+function SplitURLTest() {
+  const { variant } = useExperiment("test-split-url-1");
+
+  useEffect(() => {
+    if (
+      variant?.handle &&
+      window.location.pathname !== `/products/${variant.handle}`
+    ) {
+      window.location.href = `/products/${variant.handle}`;
+    }
+  }, [variant]);
+
+  return null;
+}
 ```
 
+### Example: Price Test
+
+```typescript
+function PriceTest({ originalPrice }: { originalPrice: number }) {
+  const { variant } = useExperiment("test-price-1");
+
+  const displayPrice = variant?.price
+    ? parseFloat(variant.price)
+    : originalPrice;
+
+  return <Price amount={displayPrice} />;
+}
+```
+
+## API Reference
+
+### Components
+
+#### `<ElevateProvider>`
+
+The main component that handles everything - config fetching, analytics tracking, and event sending.
+
+```typescript
+interface ElevateProviderProps {
+  storeId: string; // Your Shopify store ID (required)
+  cart?: any; // Cart object from Shopify (Hydrogen only)
+  shop?: any; // Shop object from Shopify (Hydrogen only)
+  consent?: any; // Consent object from Shopify (Hydrogen only)
+  hasLocalizedPaths?: boolean; // Set true if homepage is at /en-us/, /fr-ca/, etc.
+  workerUrl?: string; // Custom CloudFlare Worker endpoint
+  ordersWorkerUrl?: string; // Custom orders endpoint for checkout_completed
+  children: React.ReactNode;
+}
+```
+
+**Basic Usage:**
+
+```typescript
+<ElevateProvider
+  storeId="mystore.myshopify.com"
+  cart={data.cart}
+  shop={data.shop}
+  consent={data.consent}
+>
+  <Outlet />
+</ElevateProvider>
+```
+
+**With Localized Paths:**
+
+```typescript
+<ElevateProvider
+  storeId="mystore.myshopify.com"
+  cart={data.cart}
+  shop={data.shop}
+  consent={data.consent}
+  hasLocalizedPaths={true} // Only if homepage is at /en-us/, /fr-ca/, etc.
+>
+  <Outlet />
+</ElevateProvider>
+```
+
+### Hooks
+
+#### `useExperiment(testId: string)`
+
+Get assigned variant for a test.
+
+```typescript
+const { variant, isLoading } = useExperiment("test-id");
+
+// variant properties:
+// - id: string - Variant ID
+// - name: string - Variant name
+// - weight: number - Traffic percentage
+// - isControl: boolean - Is this the control variant
+// - isA, isB, isC, isD: boolean - Position flags
+// - handle?: string - Product handle (for product tests)
+// - price?: string - Price override (for price tests)
+```
+
+#### `useElevateConfig()`
+
+Access the full configuration context.
+
+```typescript
+const { config } = useElevateConfig();
+// config.tests: Test[] - All active tests
+```
+
+### Functions
+
+#### Cart Attributes
+
+- `updateCartAttributes(cartId, options)` - Update cart with test data
+- `cleanupCartAttributes(cartId, options)` - Remove test data from cart
+- `getCartAttributesPayload()` - Get current test data as attributes array
+
+#### Storage
+
+- `getVisitorId()` - Get or create visitor ID
+- `getSessionId()` - Get or create session ID
+- `getTestList()` - Get current test assignments
+- `setCookie(name, value)` - Set a cookie (1 year expiration)
+- `getCookie(name)` - Get a cookie value
+
+#### Analytics
+
+- `parseAddViewData(params)` - Parse UTM params, device info, referrer
+- `getPageTypeFromPathname(path)` - Detect page type
+- `extractProductId(gid)` - Extract product ID from Shopify GID
+- `extractProductVariantId(gid)` - Extract variant ID from Shopify GID
+
 ## Features
 
-- ✅ Zero-config TypeScript support
-- ✅ React Server Components compatible
-- ✅ ESM and CJS dual format
-- ✅ Tree-shakeable
-- ✅ Minified and optimized
-- ✅ Full type definitions
-- ✅ < 1KB gzipped
+- ✅ **TypeScript** - Full type safety with zero config
+- ✅ **React Server Components** - Compatible with RSC
+- ✅ **Analytics Tracking** - Automatic event tracking via @shopify/hydrogen
+- ✅ **Cart Tagging** - Attribute orders to A/B tests
+- ✅ **Device Detection** - Mobile, tablet, desktop detection
+- ✅ **Traffic Source Detection** - Facebook, Instagram, Google, etc.
+- ✅ **UTM Parameter Tracking** - Campaign attribution
+- ✅ **ESM & CJS** - Dual format for maximum compatibility
+- ✅ **Tree-shakeable** - Import only what you need
+- ✅ **Minified** - Optimized bundle size
 
 ## Compatibility
 
-- **Shopify Hydrogen**: ✅ Full support
-- **Remix**: ✅ Full support (ESM + CJS)
+- **Shopify Hydrogen**: ✅ Full support (2023.10.0+) - Automatic analytics
+- **Next.js**: ✅ Full support (13+, 14+, 15+) - Manual tracking ([See guide](./NEXTJS_EXAMPLE.md))
+- **Remix**: ✅ Full support - Manual tracking
 - **React**: 18.0.0+
 - **TypeScript**: 5.0.0+
 - **Node.js**: 18.0.0+
 
-## API Reference
+## Quick Start Guides
 
-### Types
+- **Hydrogen**: See below for automatic analytics setup
+- **Next.js**: See [Next.js Example](./NEXTJS_EXAMPLE.md) for manual tracking
 
-- `ExperimentConfig`: Configuration for an experiment
-- `Variant`: Definition of a test variant
-- `TrackingEvent`: Event tracking data structure
-- `ExperimentStatus`: Experiment lifecycle status
+## 🧪 Sandbox Stores for Testing
 
-### Components
+We've set up complete sandbox Shopify stores to help you test the Elevate SDK:
+
+### Hydrogen Sandbox Store
+
+**Location:** `hydrogen-shopify-sandbox/`
+
+A fully functional Shopify Hydrogen storefront with Elevate SDK integration.
+
+**Quick Start:**
+
+```bash
+cd hydrogen-shopify-sandbox
+npm install
+npm run dev
+```
 
-- `ElevateProvider`: Provider component that fetches configs from CDN
-- `Experiment`: Main experiment wrapper component
-- `VariantDisplay`: Conditional rendering based on variant
-- `useExperiment`: React hook for experiment logic
-- `useElevateConfig`: Hook to access config from context
+**Features:**
+- ✅ Complete ElevateProvider integration
+- ✅ Automatic analytics tracking
+- ✅ Cart attribute tagging
+- ✅ Multiple A/B test examples
+- ✅ Real Shopify products and cart
 
-### Utilities
+[View Hydrogen Sandbox Documentation →](./hydrogen-shopify-sandbox/README.md)
 
-- `assignVariant()`: Assign variant based on distribution
-- `hashString()`: Hash function for consistent assignment
-- `validateConfig()`: Validate experiment configuration
-- `generateExperimentId()`: Generate unique experiment IDs
-- `calculateRevenueLift()`: Calculate A/B test metrics
+[View Complete Sandbox Setup Guide →](./SANDBOX_SETUP.md)
 
 ## License
 
@@ -151,4 +528,4 @@ MIT
 
 ## Support
 
-For issues and questions, please visit [GitHub Issues](https://github.com/elevateab/sdk/issues).
+For issues and questions, please visit [GitHub Issues](https://github.com/abshop/headless-npm/issues).

package/dist/ElevateAnalytics-Cp5iR7dJ.d.cts

@@ -0,0 +1,48 @@
+/**
+ * ElevateAnalytics Component
+ *
+ * Internal component used by ElevateHydrogenAnalytics.
+ * Subscribes to Hydrogen analytics events and sends them to Elevate.
+ *
+ * For Hydrogen stores, use ElevateHydrogenAnalytics instead - it's zero-config!
+ * For Next.js/Remix, use manual tracking functions (trackPageView, trackAddToCart, etc.)
+ */
+/**
+ * Type for useAnalytics hook signature (matches @shopify/hydrogen)
+ */
+type UseAnalyticsHook = () => {
+    subscribe: (event: string, callback: (data: unknown) => void) => void;
+    register: (name: string) => {
+        ready: () => void;
+    };
+};
+/**
+ * Props for ElevateHydrogenAnalytics (public API)
+ */
+interface ElevateHydrogenAnalyticsProps {
+    /** Override storeId from context (optional) */
+    storeId?: string;
+    /** Override storefrontAccessToken from context (optional) */
+    storefrontAccessToken?: string;
+    /** Enable localized path detection (e.g., /en-us/, /fr-ca/) */
+    hasLocalizedPaths?: boolean;
+    /** Custom CloudFlare Worker URL */
+    workerUrl?: string;
+    /** Custom orders worker URL */
+    ordersWorkerUrl?: string;
+}
+/**
+ * Internal props for ElevateAnalytics (requires useAnalytics hook)
+ */
+interface ElevateAnalyticsProps extends ElevateHydrogenAnalyticsProps {
+    /** The useAnalytics hook from @shopify/hydrogen (required) */
+    useAnalytics: UseAnalyticsHook;
+}
+/**
+ * ElevateAnalytics - Subscribes to Hydrogen analytics events
+ *
+ * @internal Used by ElevateHydrogenAnalytics. For Hydrogen stores, use ElevateHydrogenAnalytics instead!
+ */
+declare function ElevateAnalytics({ storeId: storeIdProp, storefrontAccessToken: tokenProp, hasLocalizedPaths, workerUrl, ordersWorkerUrl, useAnalytics, }: ElevateAnalyticsProps): null;
+
+export { type ElevateHydrogenAnalyticsProps as E, type UseAnalyticsHook as U, ElevateAnalytics as a };

package/dist/ElevateAnalytics-Cp5iR7dJ.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ElevateAnalytics Component
+ *
+ * Internal component used by ElevateHydrogenAnalytics.
+ * Subscribes to Hydrogen analytics events and sends them to Elevate.
+ *
+ * For Hydrogen stores, use ElevateHydrogenAnalytics instead - it's zero-config!
+ * For Next.js/Remix, use manual tracking functions (trackPageView, trackAddToCart, etc.)
+ */
+/**
+ * Type for useAnalytics hook signature (matches @shopify/hydrogen)
+ */
+type UseAnalyticsHook = () => {
+    subscribe: (event: string, callback: (data: unknown) => void) => void;
+    register: (name: string) => {
+        ready: () => void;
+    };
+};
+/**
+ * Props for ElevateHydrogenAnalytics (public API)
+ */
+interface ElevateHydrogenAnalyticsProps {
+    /** Override storeId from context (optional) */
+    storeId?: string;
+    /** Override storefrontAccessToken from context (optional) */
+    storefrontAccessToken?: string;
+    /** Enable localized path detection (e.g., /en-us/, /fr-ca/) */
+    hasLocalizedPaths?: boolean;
+    /** Custom CloudFlare Worker URL */
+    workerUrl?: string;
+    /** Custom orders worker URL */
+    ordersWorkerUrl?: string;
+}
+/**
+ * Internal props for ElevateAnalytics (requires useAnalytics hook)
+ */
+interface ElevateAnalyticsProps extends ElevateHydrogenAnalyticsProps {
+    /** The useAnalytics hook from @shopify/hydrogen (required) */
+    useAnalytics: UseAnalyticsHook;
+}
+/**
+ * ElevateAnalytics - Subscribes to Hydrogen analytics events
+ *
+ * @internal Used by ElevateHydrogenAnalytics. For Hydrogen stores, use ElevateHydrogenAnalytics instead!
+ */
+declare function ElevateAnalytics({ storeId: storeIdProp, storefrontAccessToken: tokenProp, hasLocalizedPaths, workerUrl, ordersWorkerUrl, useAnalytics, }: ElevateAnalyticsProps): null;
+
+export { type ElevateHydrogenAnalyticsProps as E, type UseAnalyticsHook as U, ElevateAnalytics as a };