@se-studio/ab-testing 1.0.0

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3F,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,78 @@
+import type { AbTest, AbTestAssignment, IBlobStore } from '../types';
+/**
+ * Cached test data with pre-computed weights and lookups for fast middleware execution.
+ */
+export interface CachedAbTest extends AbTest {
+    /** Pre-computed weights map: variantId/control -> weight */
+    readyWeights: Record<string, number>;
+    /** Pre-computed lookup: variantId/control -> slug */
+    variantLookup: Record<string, string>;
+    /** Pre-computed lookup: variantId/control -> hubspot event name */
+    hubspotEventLookup: Record<string, string | undefined>;
+}
+/**
+ * In-memory cache structure for A/B tests.
+ */
+export interface TestsCache {
+    /** Timestamp when the cache was last refreshed */
+    timestamp: number;
+    /** Tests indexed by normalized control path */
+    testsByPath: Map<string, CachedAbTest[]>;
+}
+/**
+ * Configuration for the A/B test middleware.
+ */
+export interface AbTestMiddlewareConfig {
+    /**
+     * Factory function that returns the blob store instance.
+     * Called when the cache needs to be refreshed.
+     */
+    getStore: () => IBlobStore<AbTest> | Promise<IBlobStore<AbTest>>;
+    /**
+     * Cache time-to-live in milliseconds.
+     * @default 60000 (60 seconds)
+     */
+    cacheTtlMs?: number;
+    /**
+     * Name of the cookie used to store A/B test assignments.
+     * @default "ab-test-info"
+     */
+    cookieName?: string;
+    /**
+     * Cookie max age in seconds.
+     * @default 2592000 (30 days)
+     */
+    cookieMaxAge?: number;
+    /**
+     * Optional function to determine if middleware should process this request.
+     * Return false to skip A/B testing for this request.
+     * @default Always returns true
+     */
+    shouldProcess?: (pathname: string) => boolean;
+    /**
+     * Optional test data for development mode.
+     * When provided and in development, this data is used instead of fetching from store.
+     */
+    devTestData?: AbTest[];
+    /**
+     * Optional callback for validation failures.
+     * Called when a cookie assignment fails validation against current config.
+     */
+    onValidationFailure?: (testId: string, assignment: AbTestAssignment) => void;
+}
+/**
+ * Result of processing an A/B test request.
+ */
+export interface AbTestResult {
+    /** Whether a test was matched and processed */
+    matched: boolean;
+    /** The test that was matched (if any) */
+    test?: CachedAbTest;
+    /** The assignment for this user (if any) */
+    assignment?: AbTestAssignment;
+    /** The URL to rewrite to (if variant assigned) */
+    rewriteUrl?: string;
+    /** Updated cookie value to set */
+    cookieValue?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC1C,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,EAAE,MAAM,UAAU,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjE;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAE9C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC9E;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/middleware/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * A/B Testing Types
+ *
+ * Core type definitions for server-side A/B testing.
+ */
+/**
+ * Represents a single variant in an A/B test.
+ */
+export interface AbTestVariant {
+    /** Contentful entry ID of the PageVariant */
+    id: string;
+    /** URL slug of the variant page */
+    slug: string;
+}
+/**
+ * Configuration for a single variant in an A/B test.
+ * Index 0 is the control, subsequent indices correspond to variants.
+ */
+export interface AbTestVariantConfig {
+    /** Traffic weight for this variant (0-1, all weights should sum to 1) */
+    weight: number;
+    /** Optional HubSpot behavioral event name to fire for this variant */
+    hubspot_event_name?: string;
+}
+/**
+ * A/B test configuration stored in the blob store.
+ * This is the runtime representation of a PageTest entry.
+ */
+export interface AbTest {
+    /** Contentful entry ID of the PageTest */
+    id: string;
+    /** Internal CMS label for the test */
+    cmsLabel: string;
+    /** URL path slug of the control page (e.g., "pricing" or "lp/special-offer") */
+    controlSlug: string;
+    /** Optional URL query parameters to match (e.g., "utm_source=google") */
+    searchParameters?: string;
+    /** Optional override for analytics tracking label (defaults to cmsLabel) */
+    trackingLabel?: string;
+    /** Whether the test is currently active */
+    enabled: boolean;
+    /** Array of variant configurations with weights. Index 0 = control, 1+ = variants */
+    configuration: AbTestVariantConfig[];
+    /** Array of variants to test against the control */
+    variants: AbTestVariant[];
+}
+/**
+ * Assignment data stored in the A/B test cookie.
+ * Each test has its own assignment keyed by test ID.
+ */
+export interface AbTestAssignment {
+    /** Analytics tracking label for this test */
+    test_label: string;
+    /** Slug of the assigned variant, or "control" */
+    test_path: string;
+    /** Optional HubSpot event name for this variant */
+    hubspot_event?: string;
+    /** Original URL path where the test was assigned */
+    original_path?: string;
+}
+/**
+ * Cookie structure for A/B test assignments.
+ * Key is the test ID, value is the assignment data.
+ */
+export type AbTestCookie = Record<string, AbTestAssignment>;
+/**
+ * Generic blob store interface for A/B test configuration storage.
+ *
+ * Projects must implement this interface for their hosting platform:
+ * - Vercel: Use Vercel KV
+ * - Netlify: Use Netlify Blobs
+ * - Local development: Use file system
+ *
+ * @example Vercel KV implementation
+ * ```typescript
+ * import { kv } from '@vercel/kv';
+ * import type { IBlobStore, AbTest } from '@se-studio/ab-testing';
+ *
+ * export function getAbTestStore(): IBlobStore<AbTest> {
+ *   return {
+ *     async get(key) { return kv.get(`ab-test:${key}`); },
+ *     async set(key, value) { await kv.set(`ab-test:${key}`, value); },
+ *     async bulkWrite(entries) {
+ *       const pipeline = kv.pipeline();
+ *       for (const [key, value] of entries) {
+ *         pipeline.set(`ab-test:${key}`, value);
+ *       }
+ *       await pipeline.exec();
+ *     },
+ *     async size() { return (await kv.keys('ab-test:*')).length; },
+ *     async values() { return kv.mget(...(await kv.keys('ab-test:*'))); },
+ *   };
+ * }
+ * ```
+ */
+export interface IBlobStore<T> {
+    /**
+     * Get a value by key
+     * @param key - The key to look up
+     * @returns The value, or undefined if not found
+     */
+    get(key: string): Promise<T | undefined>;
+    /**
+     * Set a value by key
+     * @param key - The key to store under
+     * @param value - The value to store
+     */
+    set(key: string, value: T): Promise<void>;
+    /**
+     * Replace all entries in the store with new entries
+     * @param entries - Array of [key, value] tuples to store
+     */
+    bulkWrite(entries: [string, T][]): Promise<void>;
+    /**
+     * Get the number of entries in the store
+     * @returns The count of stored entries
+     */
+    size(): Promise<number>;
+    /**
+     * Get all values in the store
+     * @returns Array of all stored values
+     */
+    values(): Promise<T[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,oDAAoD;IACpD,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEzC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * A/B Testing Types
+ *
+ * Core type definitions for server-side A/B testing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/webhook/handler.d.ts

@@ -0,0 +1,116 @@
+import type { AbTest, IBlobStore } from '../types';
+/**
+ * Raw PageTest data from Contentful (before transformation).
+ * This interface represents the expected shape of data from your Contentful fetch.
+ */
+export interface RawPageTest {
+    /** Contentful system metadata */
+    sys: {
+        id: string;
+    };
+    /** CMS label for the test */
+    cmsLabel?: string | null;
+    /** Whether the test is enabled */
+    enabled?: boolean | null;
+    /** Optional tracking label override */
+    trackingLabel?: string | null;
+    /** Optional search parameters to match */
+    searchParameters?: string | null;
+    /** Variant configuration JSON */
+    configuration?: Array<{
+        weight: number;
+        hubspot_event_name?: string;
+    }> | null;
+    /** Control page reference */
+    control?: {
+        sys?: {
+            id: string;
+        };
+        slug?: string | null;
+    } | null;
+    /** Variants collection */
+    variantsCollection?: {
+        items?: Array<{
+            sys: {
+                id: string;
+            };
+            slug?: string | null;
+        } | null> | null;
+    } | null;
+}
+/**
+ * Configuration for the webhook handler.
+ */
+export interface WebhookHandlerConfig {
+    /**
+     * Function to fetch all active PageTest entries from Contentful.
+     * This should return the raw data from your GraphQL or REST API call.
+     */
+    fetchPageTests: () => Promise<RawPageTest[]>;
+    /**
+     * Function to get the blob store instance.
+     */
+    getStore: () => IBlobStore<AbTest> | Promise<IBlobStore<AbTest>>;
+    /**
+     * Optional secret for webhook authentication.
+     * If provided, the webhook will validate the x-contentful-webhook-secret header.
+     */
+    webhookSecret?: string;
+    /**
+     * Optional callback when a test is skipped (e.g., no control slug).
+     */
+    onSkippedTest?: (testId: string, reason: string) => void;
+    /**
+     * Optional revalidation function to call after updating the store.
+     * Useful for clearing Next.js cache tags.
+     */
+    revalidate?: () => void | Promise<void>;
+}
+/**
+ * Result of processing the webhook.
+ */
+export interface WebhookResult {
+    /** Whether the webhook was processed successfully */
+    success: boolean;
+    /** Number of tests stored */
+    count: number;
+    /** Optional error message */
+    error?: string;
+}
+/**
+ * Transform raw Contentful PageTest data into AbTest format.
+ */
+export declare function transformPageTest(raw: RawPageTest, onSkipped?: (testId: string, reason: string) => void): AbTest | null;
+/**
+ * Process all PageTest entries and store them in the blob store.
+ *
+ * @param config - Webhook handler configuration
+ * @returns Result with success status and count
+ */
+export declare function processAbTestWebhook(config: WebhookHandlerConfig): Promise<WebhookResult>;
+/**
+ * Create a Next.js API route handler for the A/B test webhook.
+ *
+ * @param config - Webhook handler configuration
+ * @returns POST handler function
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhooks/ab-test/route.ts
+ * import { createWebhookHandler } from '@se-studio/ab-testing/webhook';
+ * import { getAbTestStore } from '@/server/abTestStore';
+ * import { fetchAllPageTests } from '@/cms/pageTests';
+ * import { revalidateTag } from 'next/cache';
+ *
+ * export const dynamic = 'force-dynamic';
+ *
+ * export const POST = createWebhookHandler({
+ *   fetchPageTests: () => fetchAllPageTests(false), // preview=false
+ *   getStore: getAbTestStore,
+ *   webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET,
+ *   revalidate: () => revalidateTag('PageTests'),
+ * });
+ * ```
+ */
+export declare function createWebhookHandler(config: WebhookHandlerConfig): (request: Request) => Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/webhook/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/webhook/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,GAAG,EAAE;QACH,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IACF,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iCAAiC;IACjC,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC,GAAG,IAAI,CAAC;IACV,6BAA6B;IAC7B,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACtB,GAAG,IAAI,CAAC;IACT,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE;QACnB,KAAK,CAAC,EAAE,KAAK,CAAC;YACZ,GAAG,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SACtB,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;KAClB,GAAG,IAAI,CAAC;CACV;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE7C;;OAEG;IACH,QAAQ,EAAE,MAAM,UAAU,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACnD,MAAM,GAAG,IAAI,CAyBf;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAuC/F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,IACjC,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAsCnE"}

package/dist/webhook/handler.js

@@ -0,0 +1,123 @@
+/**
+ * Transform raw Contentful PageTest data into AbTest format.
+ */
+export function transformPageTest(raw, onSkipped) {
+    const controlSlug = raw.control?.slug;
+    if (!controlSlug) {
+        onSkipped?.(raw.sys.id, 'No control slug');
+        return null;
+    }
+    const variants = (raw.variantsCollection?.items ?? [])
+        .filter((item) => item !== null && item.slug !== null)
+        .map((item) => ({
+        id: item.sys.id,
+        slug: item.slug,
+    }));
+    return {
+        id: raw.sys.id,
+        cmsLabel: raw.cmsLabel || '',
+        controlSlug,
+        searchParameters: raw.searchParameters ?? undefined,
+        trackingLabel: raw.trackingLabel ?? undefined,
+        enabled: raw.enabled ?? false,
+        configuration: raw.configuration ?? [],
+        variants,
+    };
+}
+/**
+ * Process all PageTest entries and store them in the blob store.
+ *
+ * @param config - Webhook handler configuration
+ * @returns Result with success status and count
+ */
+export async function processAbTestWebhook(config) {
+    const { fetchPageTests, getStore, onSkippedTest, revalidate } = config;
+    try {
+        // Revalidate cache tags if function provided
+        if (revalidate) {
+            await Promise.resolve(revalidate());
+        }
+        // Fetch all active tests from Contentful
+        const rawTests = await fetchPageTests();
+        // Transform and index by control slug
+        const abTests = {};
+        for (const raw of rawTests) {
+            const test = transformPageTest(raw, onSkippedTest);
+            if (test) {
+                abTests[test.controlSlug] = test;
+            }
+        }
+        // Store in blob store
+        const store = await Promise.resolve(getStore());
+        await store.bulkWrite(Object.entries(abTests));
+        return {
+            success: true,
+            count: Object.keys(abTests).length,
+        };
+    }
+    catch (error) {
+        // biome-ignore lint/suspicious/noConsole: Error logging in webhook
+        console.error('Error processing ab-test webhook:', error);
+        return {
+            success: false,
+            count: 0,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Create a Next.js API route handler for the A/B test webhook.
+ *
+ * @param config - Webhook handler configuration
+ * @returns POST handler function
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhooks/ab-test/route.ts
+ * import { createWebhookHandler } from '@se-studio/ab-testing/webhook';
+ * import { getAbTestStore } from '@/server/abTestStore';
+ * import { fetchAllPageTests } from '@/cms/pageTests';
+ * import { revalidateTag } from 'next/cache';
+ *
+ * export const dynamic = 'force-dynamic';
+ *
+ * export const POST = createWebhookHandler({
+ *   fetchPageTests: () => fetchAllPageTests(false), // preview=false
+ *   getStore: getAbTestStore,
+ *   webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET,
+ *   revalidate: () => revalidateTag('PageTests'),
+ * });
+ * ```
+ */
+export function createWebhookHandler(config) {
+    return async function handler(request) {
+        // Validate webhook secret if configured
+        if (config.webhookSecret) {
+            const secret = request.headers.get('x-contentful-webhook-secret');
+            if (secret !== config.webhookSecret) {
+                return new Response(JSON.stringify({ message: 'Invalid secret' }), {
+                    status: 401,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+        }
+        const result = await processAbTestWebhook(config);
+        if (result.success) {
+            return new Response(JSON.stringify({
+                message: 'Success',
+                count: result.count,
+            }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        return new Response(JSON.stringify({
+            message: 'Error processing webhook',
+            error: result.error,
+        }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/webhook/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/webhook/handler.ts"],"names":[],"mappings":"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"}

package/dist/webhook/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A/B Testing Webhook Handlers
+ *
+ * Utilities for processing Contentful webhooks to sync PageTest configurations.
+ */
+export type { RawPageTest, WebhookHandlerConfig, WebhookResult, } from './handler';
+export { createWebhookHandler, processAbTestWebhook, transformPageTest, } from './handler';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/webhook/index.js

@@ -0,0 +1,7 @@
+/**
+ * A/B Testing Webhook Handlers
+ *
+ * Utilities for processing Contentful webhooks to sync PageTest configurations.
+ */
+export { createWebhookHandler, processAbTestWebhook, transformPageTest, } from './handler';
+//# sourceMappingURL=index.js.map

package/dist/webhook/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@se-studio/ab-testing",
+  "version": "1.0.0",
+  "description": "Server-side A/B testing framework for Next.js applications with Contentful CMS",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Something-Else-Studio/se-core-product",
+    "directory": "packages/ab-testing"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook/index.d.ts",
+      "import": "./dist/webhook/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "*.md"
+  ],
+  "keywords": [
+    "ab-testing",
+    "a/b-testing",
+    "experiment",
+    "nextjs",
+    "next.js",
+    "middleware",
+    "contentful",
+    "cms",
+    "typescript",
+    "react",
+    "analytics"
+  ],
+  "homepage": "https://github.com/Something-Else-Studio/se-core-product#readme",
+  "bugs": {
+    "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
+  },
+  "peerDependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/node": "^22.19.3",
+    "@types/react": "^19.2.7",
+    "next": "^15.5.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsc --project tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "biome lint .",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}