@se-studio/ab-testing 1.0.0

package/README.md

@@ -0,0 +1,393 @@
+# @se-studio/ab-testing
+
+Server-side A/B testing framework for Next.js applications with Contentful CMS.
+
+## Features
+
+- **Server-side rendering**: No flicker or layout shift - variants are rendered on the server
+- **Edge-optimized**: Middleware runs at the edge for minimal latency
+- **CMS-driven**: Test configuration managed entirely in Contentful
+- **Provider-agnostic**: Bring your own blob storage (Vercel KV, Netlify Blobs, etc.)
+- **Flexible analytics**: Use the `useAbTestAssignments` hook to integrate with any analytics platform
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Contentful    │────▶│  Webhook Handler │────▶│   Blob Store    │
+│   PageTest      │     │  (API Route)     │     │  (Project-      │
+│   Entries       │     │                  │     │   specific)     │
+└─────────────────┘     └──────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   User Request  │────▶│   Middleware     │────▶│   Variant Page  │
+│   /pricing      │     │   (Edge)         │     │   (SSR)         │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                │
+                                ▼
+                        ┌──────────────────┐
+                        │   Cookie Set     │
+                        │   ab-test-info   │
+                        └────────┬─────────┘
+                                 │
+                                 ▼
+                        ┌──────────────────┐
+                        │ useAbTestAssign- │
+                        │ ments Hook       │
+                        │ → Your Analytics │
+                        └──────────────────┘
+```
+
+## Installation
+
+```bash
+pnpm add @se-studio/ab-testing
+```
+
+## Quick Start
+
+### 1. Implement Your Blob Store
+
+The package requires you to implement the `IBlobStore<AbTest>` interface for your hosting platform.
+
+**Vercel KV Example:**
+
+```typescript
+// src/server/abTestStore.ts
+import { kv } from '@vercel/kv';
+import type { IBlobStore, AbTest } from '@se-studio/ab-testing';
+
+const STORE_KEY = 'ab-tests';
+
+export function getAbTestStore(): IBlobStore<AbTest> {
+  return {
+    async get(key) {
+      const data = await kv.hget<AbTest>(STORE_KEY, key);
+      return data ?? undefined;
+    },
+    async set(key, value) {
+      await kv.hset(STORE_KEY, { [key]: value });
+    },
+    async bulkWrite(entries) {
+      await kv.del(STORE_KEY);
+      if (entries.length > 0) {
+        const data = Object.fromEntries(entries);
+        await kv.hset(STORE_KEY, data);
+      }
+    },
+    async size() {
+      return kv.hlen(STORE_KEY);
+    },
+    async values() {
+      const data = await kv.hgetall<Record<string, AbTest>>(STORE_KEY);
+      return data ? Object.values(data) : [];
+    },
+  };
+}
+```
+
+**Netlify Blobs Example:**
+
+```typescript
+// src/server/abTestStore.ts
+import { getStore } from '@netlify/blobs';
+import type { IBlobStore, AbTest } from '@se-studio/ab-testing';
+
+export function getAbTestStore(): IBlobStore<AbTest> {
+  const store = getStore('ab-testing');
+  const BLOB_NAME = 'config';
+
+  return {
+    async get(key) {
+      const data = await store.get(BLOB_NAME, { type: 'json' });
+      return data?.[key];
+    },
+    async set(key, value) {
+      const data = (await store.get(BLOB_NAME, { type: 'json' })) ?? {};
+      data[key] = value;
+      await store.setJSON(BLOB_NAME, data);
+    },
+    async bulkWrite(entries) {
+      const data = Object.fromEntries(entries);
+      await store.setJSON(BLOB_NAME, data);
+    },
+    async size() {
+      const data = await store.get(BLOB_NAME, { type: 'json' });
+      return data ? Object.keys(data).length : 0;
+    },
+    async values() {
+      const data = await store.get(BLOB_NAME, { type: 'json' });
+      return data ? Object.values(data) : [];
+    },
+  };
+}
+```
+
+### 2. Set Up the Middleware
+
+```typescript
+// src/middleware.ts
+import { createAbTestMiddleware } from '@se-studio/ab-testing/middleware';
+import { getAbTestStore } from './server/abTestStore';
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+const abTestHandler = createAbTestMiddleware({
+  getStore: getAbTestStore,
+  cacheTtlMs: 60000, // 60 second cache
+});
+
+export async function middleware(request: NextRequest) {
+  // Skip static assets, API routes, etc.
+  if (request.nextUrl.pathname.startsWith('/_next') ||
+      request.nextUrl.pathname.startsWith('/api')) {
+    return NextResponse.next();
+  }
+
+  // Process A/B tests
+  const abResponse = await abTestHandler(request);
+  if (abResponse) return abResponse;
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+### 3. Create the Webhook Handler
+
+```typescript
+// src/app/api/webhooks/ab-test/route.ts
+import { createWebhookHandler } from '@se-studio/ab-testing/webhook';
+import { getAbTestStore } from '@/server/abTestStore';
+import { revalidateTag } from 'next/cache';
+
+// Your Contentful fetch function
+async function fetchPageTests() {
+  // Fetch all PageTest entries from Contentful
+  // Return array of RawPageTest objects
+}
+
+export const dynamic = 'force-dynamic';
+
+export const POST = createWebhookHandler({
+  fetchPageTests,
+  getStore: getAbTestStore,
+  webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET,
+  revalidate: () => revalidateTag('PageTests'),
+});
+```
+
+### 4. Create Your Analytics Reporter (Project-Specific)
+
+The package provides a `useAbTestAssignments` hook that returns test assignments for the current page. You create your own reporter component with your project's specific analytics integrations.
+
+```tsx
+// src/components/AbTestReporter.tsx (project-specific)
+'use client';
+
+import { useEffect } from 'react';
+import { useAbTestAssignments } from '@se-studio/ab-testing';
+import { sendEvent } from '@/lib/analytics';
+
+export function AbTestReporter() {
+  const assignments = useAbTestAssignments();
+
+  useEffect(() => {
+    for (const assignment of assignments) {
+      // Send to GTM/GA4
+      sendEvent('experiment_impression', {
+        experiment_id: assignment.testId,
+        experiment_name: assignment.test_label,
+        variant_id: assignment.test_path,
+      });
+    }
+  }, [assignments]);
+
+  return null;
+}
+```
+
+**With HubSpot Integration (HSD-style):**
+
+```tsx
+// src/components/AbTestReporter.tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useAbTestAssignments } from '@se-studio/ab-testing';
+import { sendEvent } from '@/lib/analytics';
+import { sendHubspotCustomEvent } from '@/lib/hubspotCustomEvents';
+
+export function AbTestReporter() {
+  const assignments = useAbTestAssignments();
+
+  useEffect(() => {
+    for (const assignment of assignments) {
+      // Send to GTM/GA4
+      sendEvent('experiment_impression', {
+        experiment_id: assignment.testId,
+        experiment_name: assignment.test_label,
+        variant_id: assignment.test_path,
+      });
+
+      // Send to HubSpot (if configured)
+      if (assignment.hubspot_event) {
+        sendHubspotCustomEvent(assignment.hubspot_event, {
+          experiment_name: assignment.test_label,
+          experiment_id: assignment.testId,
+        });
+      }
+    }
+  }, [assignments]);
+
+  return null;
+}
+```
+
+**Add to your layout:**
+
+```tsx
+// src/app/layout.tsx
+import { AbTestReporter } from '@/components/AbTestReporter';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <AbTestReporter />
+      </body>
+    </html>
+  );
+}
+```
+
+## Contentful Content Model
+
+### PageTest
+
+| Field | Type | Description |
+|-------|------|-------------|
+| cmsLabel | Symbol | Internal label for the test |
+| control | Reference (Page/PageVariant) | The control page to test against |
+| enabled | Boolean | Whether the test is active |
+| trackingLabel | Symbol (optional) | Override for analytics label |
+| searchParameters | Symbol (optional) | URL params to match (e.g., "utm_source=google") |
+| configuration | JSON | Array of `{weight, hubspot_event_name?}` |
+| variants | References (PageVariant[]) | Variants to test |
+
+### PageVariant
+
+Existing content type that references an original page and defines component swaps.
+
+## API Reference
+
+### Types
+
+```typescript
+interface AbTest {
+  id: string;
+  cmsLabel: string;
+  controlSlug: string;
+  searchParameters?: string;
+  trackingLabel?: string;
+  enabled: boolean;
+  configuration: AbTestVariantConfig[];
+  variants: AbTestVariant[];
+}
+
+interface IBlobStore<T> {
+  get(key: string): Promise<T | undefined>;
+  set(key: string, value: T): Promise<void>;
+  bulkWrite(entries: [string, T][]): Promise<void>;
+  size(): Promise<number>;
+  values(): Promise<T[]>;
+}
+
+interface ActiveAbTestAssignment {
+  testId: string;
+  test_label: string;
+  test_path: string;
+  hubspot_event?: string;
+  original_path?: string;
+}
+```
+
+### Middleware
+
+```typescript
+import { createAbTestMiddleware } from '@se-studio/ab-testing/middleware';
+
+const handler = createAbTestMiddleware({
+  getStore: () => store,      // Required: blob store factory
+  cacheTtlMs: 60000,          // Optional: cache TTL (default: 60s)
+  cookieName: 'ab-test-info', // Optional: cookie name
+  cookieMaxAge: 2592000,      // Optional: cookie max age (default: 30 days)
+  shouldProcess: (path) => true, // Optional: filter requests
+  devTestData: [],            // Optional: test data for development
+});
+```
+
+### Webhook
+
+```typescript
+import { createWebhookHandler } from '@se-studio/ab-testing/webhook';
+
+export const POST = createWebhookHandler({
+  fetchPageTests: () => Promise<RawPageTest[]>, // Required
+  getStore: () => store,                         // Required
+  webhookSecret: 'secret',                       // Optional
+  revalidate: () => void,                        // Optional
+  onSkippedTest: (id, reason) => void,          // Optional
+});
+```
+
+### Hook
+
+```typescript
+import { useAbTestAssignments } from '@se-studio/ab-testing';
+
+// Returns array of assignments for the current page
+const assignments = useAbTestAssignments({
+  cookieName: 'ab-test-info', // Optional: custom cookie name
+});
+
+// Each assignment contains:
+// - testId: string
+// - test_label: string
+// - test_path: string (variant slug or "control")
+// - hubspot_event?: string
+// - original_path?: string
+```
+
+## Analytics Integration
+
+### Google Tag Manager (GTM)
+
+Push events to `window.dataLayer`:
+
+```typescript
+window.dataLayer.push({
+  event: 'experiment_impression',
+  experiment_id: assignment.testId,
+  experiment_name: assignment.test_label,
+  variant_id: assignment.test_path,
+});
+```
+
+### Google Analytics 4 (GA4)
+
+Register custom dimensions in GA4:
+1. Go to Admin > Data display > Custom definitions
+2. Create event-scoped dimensions for:
+   - `experiment_id`
+   - `experiment_name`
+   - `variant_id`
+
+## License
+
+MIT

package/dist/hooks/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A/B Testing Hooks
+ *
+ * React hooks for client-side A/B test reporting.
+ */
+export type { ActiveAbTestAssignment, UseAbTestAssignmentsOptions } from './useAbTestAssignments';
+export { useAbTestAssignments } from './useAbTestAssignments';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+/**
+ * A/B Testing Hooks
+ *
+ * React hooks for client-side A/B test reporting.
+ */
+export { useAbTestAssignments } from './useAbTestAssignments';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/hooks/useAbTestAssignments.d.ts

@@ -0,0 +1,55 @@
+import type { AbTestAssignment } from '../types';
+/**
+ * An A/B test assignment with its test ID included.
+ */
+export interface ActiveAbTestAssignment extends AbTestAssignment {
+    /** Contentful entry ID of the PageTest */
+    testId: string;
+}
+/**
+ * Options for the useAbTestAssignments hook.
+ */
+export interface UseAbTestAssignmentsOptions {
+    /**
+     * Cookie name to read assignments from.
+     * @default "ab-test-info"
+     */
+    cookieName?: string;
+}
+/**
+ * Hook that returns A/B test assignments for the current page.
+ *
+ * This hook reads the A/B test cookie and returns only the assignments
+ * that match the current page path. Projects can use this to build
+ * their own analytics reporting with project-specific integrations.
+ *
+ * @param options - Hook configuration options
+ * @returns Array of active test assignments for the current page
+ *
+ * @example Basic usage
+ * ```tsx
+ * 'use client';
+ *
+ * import { useEffect } from 'react';
+ * import { useAbTestAssignments } from '@se-studio/ab-testing';
+ *
+ * export function AbTestReporter() {
+ *   const assignments = useAbTestAssignments();
+ *
+ *   useEffect(() => {
+ *     for (const assignment of assignments) {
+ *       // Send to your analytics
+ *       sendEvent('experiment_impression', {
+ *         experiment_id: assignment.testId,
+ *         experiment_name: assignment.test_label,
+ *         variant_id: assignment.test_path,
+ *       });
+ *     }
+ *   }, [assignments]);
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useAbTestAssignments(options?: UseAbTestAssignmentsOptions): ActiveAbTestAssignment[];
+//# sourceMappingURL=useAbTestAssignments.d.ts.map

package/dist/hooks/useAbTestAssignments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAbTestAssignments.d.ts","sourceRoot":"","sources":["../../src/hooks/useAbTestAssignments.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,2BAA2B,GACpC,sBAAsB,EAAE,CA8C1B"}

package/dist/hooks/useAbTestAssignments.js

@@ -0,0 +1,87 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { DEFAULT_COOKIE_NAME, readCookieFromDocument } from '../middleware/cookies';
+/**
+ * Normalize a path for comparison (remove trailing slash except for root).
+ */
+function normalizePath(path) {
+    if (path.endsWith('/') && path.length > 1) {
+        return path.slice(0, -1);
+    }
+    return path;
+}
+/**
+ * Hook that returns A/B test assignments for the current page.
+ *
+ * This hook reads the A/B test cookie and returns only the assignments
+ * that match the current page path. Projects can use this to build
+ * their own analytics reporting with project-specific integrations.
+ *
+ * @param options - Hook configuration options
+ * @returns Array of active test assignments for the current page
+ *
+ * @example Basic usage
+ * ```tsx
+ * 'use client';
+ *
+ * import { useEffect } from 'react';
+ * import { useAbTestAssignments } from '@se-studio/ab-testing';
+ *
+ * export function AbTestReporter() {
+ *   const assignments = useAbTestAssignments();
+ *
+ *   useEffect(() => {
+ *     for (const assignment of assignments) {
+ *       // Send to your analytics
+ *       sendEvent('experiment_impression', {
+ *         experiment_id: assignment.testId,
+ *         experiment_name: assignment.test_label,
+ *         variant_id: assignment.test_path,
+ *       });
+ *     }
+ *   }, [assignments]);
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useAbTestAssignments(options) {
+    const cookieName = options?.cookieName ?? DEFAULT_COOKIE_NAME;
+    const [assignments, setAssignments] = useState([]);
+    useEffect(() => {
+        try {
+            const allAssignments = readCookieFromDocument(document.cookie, cookieName);
+            if (Object.keys(allAssignments).length === 0) {
+                setAssignments([]);
+                return;
+            }
+            // Get and normalize current browser path
+            const currentPath = window.location.pathname;
+            const normalizedCurrentPath = normalizePath(currentPath);
+            // Filter to only assignments for the current page
+            const activeAssignments = [];
+            for (const [testId, assignment] of Object.entries(allAssignments)) {
+                // Skip if original_path is not present
+                if (!assignment.original_path) {
+                    continue;
+                }
+                // Skip if not on the original path where the test was assigned
+                if (assignment.original_path !== normalizedCurrentPath) {
+                    continue;
+                }
+                activeAssignments.push({
+                    ...assignment,
+                    testId,
+                });
+            }
+            setAssignments(activeAssignments);
+        }
+        catch (e) {
+            // biome-ignore lint/suspicious/noConsole: Error logging
+            console.error('[useAbTestAssignments] Error reading A/B test cookie', e);
+            setAssignments([]);
+        }
+    }, [cookieName]);
+    return assignments;
+}
+//# sourceMappingURL=useAbTestAssignments.js.map

package/dist/hooks/useAbTestAssignments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAbTestAssignments.js","sourceRoot":"","sources":["../../src/hooks/useAbTestAssignments.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAsBpF;;GAEG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAqC;IAErC,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC;IAC9D,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAA2B,EAAE,CAAC,CAAC;IAE7E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,sBAAsB,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAE3E,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7C,cAAc,CAAC,EAAE,CAAC,CAAC;gBACnB,OAAO;YACT,CAAC;YAED,yCAAyC;YACzC,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC7C,MAAM,qBAAqB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;YAEzD,kDAAkD;YAClD,MAAM,iBAAiB,GAA6B,EAAE,CAAC;YAEvD,KAAK,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClE,uCAAuC;gBACvC,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;oBAC9B,SAAS;gBACX,CAAC;gBAED,+DAA+D;gBAC/D,IAAI,UAAU,CAAC,aAAa,KAAK,qBAAqB,EAAE,CAAC;oBACvD,SAAS;gBACX,CAAC;gBAED,iBAAiB,CAAC,IAAI,CAAC;oBACrB,GAAG,UAAU;oBACb,MAAM;iBACP,CAAC,CAAC;YACL,CAAC;YAED,cAAc,CAAC,iBAAiB,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,wDAAwD;YACxD,OAAO,CAAC,KAAK,CAAC,sDAAsD,EAAE,CAAC,CAAC,CAAC;YACzE,cAAc,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @se-studio/ab-testing
+ *
+ * Server-side A/B testing framework for Next.js applications with Contentful CMS.
+ *
+ * @packageDocumentation
+ */
+export type { ActiveAbTestAssignment, UseAbTestAssignmentsOptions } from './hooks';
+export { useAbTestAssignments } from './hooks';
+export type { AbTestMiddlewareConfig, AbTestResult, CachedAbTest, TestsCache, } from './middleware';
+export { clearTestCache, createAbTestMiddleware, createAssignment, DEFAULT_COOKIE_MAX_AGE, DEFAULT_COOKIE_NAME, getAssignment, getCachedTests, getTestCacheState, isValidAssignment, normalizePath, parseCookie, processAbTestRequest, readCookieFromDocument, selectVariant, serializeCookie, setAssignment, } from './middleware';
+export type { AbTest, AbTestAssignment, AbTestCookie, AbTestVariant, AbTestVariantConfig, IBlobStore, } from './types';
+export type { RawPageTest, WebhookHandlerConfig, WebhookResult, } from './webhook';
+export { createWebhookHandler, processAbTestWebhook, transformPageTest, } from './webhook';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAEnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EACV,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,MAAM,EACN,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @se-studio/ab-testing
+ *
+ * Server-side A/B testing framework for Next.js applications with Contentful CMS.
+ *
+ * @packageDocumentation
+ */
+// Re-export hooks
+export { useAbTestAssignments } from './hooks';
+// Re-export middleware utilities
+export { clearTestCache, createAbTestMiddleware, createAssignment, DEFAULT_COOKIE_MAX_AGE, DEFAULT_COOKIE_NAME, getAssignment, getCachedTests, getTestCacheState, isValidAssignment, normalizePath, parseCookie, processAbTestRequest, readCookieFromDocument, selectVariant, serializeCookie, setAssignment, } from './middleware';
+// Re-export webhook utilities
+export { createWebhookHandler, processAbTestWebhook, transformPageTest, } from './webhook';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,kBAAkB;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAO/C,iCAAiC;AACjC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,cAAc,CAAC;AAetB,8BAA8B;AAC9B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/middleware/assignment.d.ts

@@ -0,0 +1,36 @@
+import type { AbTestAssignment } from '../types';
+import type { CachedAbTest } from './types';
+/**
+ * Perform weighted random selection to assign a variant.
+ *
+ * @param test - The cached test with pre-computed weights
+ * @returns Object with selectedKey (variant ID or "control") and variant slug
+ */
+export declare function selectVariant(test: CachedAbTest): {
+    selectedKey: string;
+    variantSlug: string;
+};
+/**
+ * Create an assignment object for a newly selected variant.
+ *
+ * @param test - The cached test
+ * @param selectedKey - The selected variant ID or "control"
+ * @param variantSlug - The slug of the selected variant
+ * @param originalPath - The original URL path where the test was assigned
+ * @returns Assignment object to store in cookie
+ */
+export declare function createAssignment(test: CachedAbTest, selectedKey: string, variantSlug: string, originalPath: string): AbTestAssignment;
+/**
+ * Validate an existing cookie assignment against current CMS config.
+ * Checks that:
+ * - original_path is present
+ * - test_label matches current config
+ * - test_path (variant) exists and has weight > 0
+ * - hubspot_event matches current config
+ *
+ * @param test - The cached test with current config
+ * @param assignment - The assignment from the cookie
+ * @returns true if assignment is still valid, false if it should be re-assigned
+ */
+export declare function isValidAssignment(test: CachedAbTest, assignment: AbTestAssignment): boolean;
+//# sourceMappingURL=assignment.d.ts.map

package/dist/middleware/assignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.d.ts","sourceRoot":"","sources":["../../src/middleware/assignment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAe9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CA6C3F"}