@se-studio/ab-testing 0.0.0-next16-20260822103555

package/dist/middleware/types.d.ts

@@ -0,0 +1,103 @@
+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 -> variant_label */
+    variantLabelLookup: Record<string, string | undefined>;
+    /** Pre-computed lookup: variantId/control -> reporting event name */
+    reportingEventLookup: Record<string, string | undefined>;
+    /** Pre-computed lookup: variantId/control -> url_params */
+    urlParamsLookup: Record<string, Record<string, string> | undefined>;
+    /** Pre-computed lookup: variantId/control -> reporting_params */
+    reportingParamsLookup: Record<string, 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;
+    /**
+     * Path prefix to prepend when rewriting to a variant.
+     * e.g. "/page-test" → rewrites to "/page-test/slug" instead of "/slug".
+     * Useful to keep variant URLs on an internal route excluded from robots.txt.
+     * @default "" (no prefix — rewrite directly to slug)
+     */
+    variantPathPrefix?: string;
+    /**
+     * Remove cookie entries for tests no longer in the active config.
+     * @default true
+     */
+    pruneStaleAssignments?: boolean;
+    /**
+     * When injecting url_params, skip keys already present on the request URL.
+     * @default true
+     */
+    respectExistingUrlParams?: boolean;
+}
+/**
+ * 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;
+    /** Whether stale cookie keys were pruned */
+    prunedStale?: boolean;
+}
+//# 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,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACvD,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACpE,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;CAC3E;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;IAE7E;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;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;IACrB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

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/middleware/urlParams.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Apply url_params to a URL, optionally respecting existing query keys.
+ *
+ * @returns true if any param was set
+ */
+export declare function applyUrlParams(url: URL, urlParams: Record<string, string> | undefined, respectExisting: boolean): boolean;
+//# sourceMappingURL=urlParams.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"urlParams.d.ts","sourceRoot":"","sources":["../../src/middleware/urlParams.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC7C,eAAe,EAAE,OAAO,GACvB,OAAO,CAeT"}

package/dist/middleware/urlParams.js

@@ -0,0 +1,20 @@
+/**
+ * Apply url_params to a URL, optionally respecting existing query keys.
+ *
+ * @returns true if any param was set
+ */
+export function applyUrlParams(url, urlParams, respectExisting) {
+    if (!urlParams) {
+        return false;
+    }
+    let changed = false;
+    for (const [key, value] of Object.entries(urlParams)) {
+        if (respectExisting && url.searchParams.has(key)) {
+            continue;
+        }
+        url.searchParams.set(key, value);
+        changed = true;
+    }
+    return changed;
+}
+//# sourceMappingURL=urlParams.js.map

package/dist/middleware/urlParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlParams.js","sourceRoot":"","sources":["../../src/middleware/urlParams.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAQ,EACR,SAA6C,EAC7C,eAAwB;IAExB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,eAAe,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,SAAS;QACX,CAAC;QACD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/middleware/variantId.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Build the variant_id string for a bucket assignment.
+ *
+ * @param isControl - Whether this is the control bucket
+ * @param variantLabel - CMS variant_label for the bucket
+ * @param fallbackSlug - Fallback label when variant_label is absent
+ */
+export declare function buildVariantId(isControl: boolean, variantLabel: string | undefined, fallbackSlug: string): string;
+//# sourceMappingURL=variantId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variantId.d.ts","sourceRoot":"","sources":["../../src/middleware/variantId.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,OAAO,EAClB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR"}

package/dist/middleware/variantId.js

@@ -0,0 +1,12 @@
+/**
+ * Build the variant_id string for a bucket assignment.
+ *
+ * @param isControl - Whether this is the control bucket
+ * @param variantLabel - CMS variant_label for the bucket
+ * @param fallbackSlug - Fallback label when variant_label is absent
+ */
+export function buildVariantId(isControl, variantLabel, fallbackSlug) {
+    const label = variantLabel ?? fallbackSlug;
+    return `${isControl ? 'control' : 'variant'}:${label}`;
+}
+//# sourceMappingURL=variantId.js.map

package/dist/middleware/variantId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variantId.js","sourceRoot":"","sources":["../../src/middleware/variantId.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAkB,EAClB,YAAgC,EAChC,YAAoB;IAEpB,MAAM,KAAK,GAAG,YAAY,IAAI,YAAY,CAAC;IAC3C,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,KAAK,EAAE,CAAC;AACzD,CAAC"}

package/dist/reporting/buildExperimentImpression.d.ts

@@ -0,0 +1,6 @@
+import type { AbTestAssignment } from '../types';
+/**
+ * Snake_case experiment_impression payload for analytics adapters.
+ */
+export declare function buildExperimentImpression(testId: string, assignment: AbTestAssignment): Record<string, string>;
+//# sourceMappingURL=buildExperimentImpression.d.ts.map

package/dist/reporting/buildExperimentImpression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildExperimentImpression.d.ts","sourceRoot":"","sources":["../../src/reporting/buildExperimentImpression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB"}

package/dist/reporting/buildExperimentImpression.js

@@ -0,0 +1,22 @@
+/**
+ * Snake_case experiment_impression payload for analytics adapters.
+ */
+export function buildExperimentImpression(testId, assignment) {
+    const payload = {
+        experiment_id: testId,
+        experiment_name: assignment.experiment_name,
+        variant_id: assignment.variant_id,
+        variant_slug: assignment.variant_slug,
+        original_path: assignment.original_path,
+    };
+    if (assignment.reporting_event) {
+        payload.reporting_event = assignment.reporting_event;
+    }
+    if (assignment.reporting_params) {
+        for (const [key, value] of Object.entries(assignment.reporting_params)) {
+            payload[key] = value;
+        }
+    }
+    return payload;
+}
+//# sourceMappingURL=buildExperimentImpression.js.map

package/dist/reporting/buildExperimentImpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildExperimentImpression.js","sourceRoot":"","sources":["../../src/reporting/buildExperimentImpression.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAc,EACd,UAA4B;IAE5B,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,MAAM;QACrB,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,YAAY,EAAE,UAAU,CAAC,YAAY;QACrC,aAAa,EAAE,UAAU,CAAC,aAAa;KACxC,CAAC;IAEF,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC;QAC/B,OAAO,CAAC,eAAe,GAAG,UAAU,CAAC,eAAe,CAAC;IACvD,CAAC;IAED,IAAI,UAAU,CAAC,gBAAgB,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACvE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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;
+    /** CMS label for this bucket; drives variant_id suffix */
+    variant_label?: string;
+    /** Optional per-bucket analytics event name */
+    reporting_event?: string;
+    /** Query params to inject when injectUrlParams is enabled on the test */
+    url_params?: Record<string, string>;
+    /** Arbitrary key-value pairs merged into experiment_impression payloads */
+    reporting_params?: Record<string, 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;
+    /** Analytics experiment name (defaults to cmsLabel) */
+    trackingLabel?: string;
+    /** Whether the test is currently active */
+    enabled: boolean;
+    /** When true, inject url_params from the assigned bucket into the request URL */
+    injectUrlParams?: 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 experiment name for this test */
+    experiment_name: string;
+    /** Bucket identifier, e.g. "control:normal-cta" or "variant:home-kids" */
+    variant_id: string;
+    /** Slug of the assigned variant, or "control" */
+    variant_slug: string;
+    /** Original URL path where the test was assigned */
+    original_path: string;
+    /** Optional per-bucket analytics event name */
+    reporting_event?: string;
+    /**
+     * When true, middleware and AbTestUtmScript may apply `url_params` to the URL.
+     * When false or absent (legacy cookies), do not inject into the address bar.
+     */
+    injectUrlParams?: boolean;
+    /** URL params to inject when injectUrlParams is enabled */
+    url_params?: Record<string, string>;
+    /** Arbitrary key-value pairs for analytics adapters */
+    reporting_params?: Record<string, 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,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;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,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qFAAqF;IACrF,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,oDAAoD;IACpD,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;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/utils.d.ts

@@ -0,0 +1,12 @@
+import type { CachedAbTest } from './middleware/types';
+/**
+ * Given a testsByPath map and a variant slug, returns the canonical
+ * (user-facing) path that owns the variant.
+ *
+ * Useful in page-test route handlers to set the correct canonical URL
+ * in metadata rather than exposing the internal variant path.
+ *
+ * @returns The canonical path (e.g. '/services/'), or undefined if not found.
+ */
+export declare function findCanonicalPath(testsByPath: Record<string, CachedAbTest[]>, variantSlug: string): string | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAC3C,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CASpB"}

package/dist/utils.js

@@ -0,0 +1,20 @@
+/**
+ * Given a testsByPath map and a variant slug, returns the canonical
+ * (user-facing) path that owns the variant.
+ *
+ * Useful in page-test route handlers to set the correct canonical URL
+ * in metadata rather than exposing the internal variant path.
+ *
+ * @returns The canonical path (e.g. '/services/'), or undefined if not found.
+ */
+export function findCanonicalPath(testsByPath, variantSlug) {
+    for (const [controlPath, tests] of Object.entries(testsByPath)) {
+        for (const test of tests) {
+            if (test.variants.some((v) => v.slug === variantSlug)) {
+                return controlPath.endsWith('/') ? controlPath : `${controlPath}/`;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAA2C,EAC3C,WAAmB;IAEnB,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;gBACtD,OAAO,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/webhook/handler.d.ts

@@ -0,0 +1,109 @@
+import type { AbTest, AbTestVariantConfig, IBlobStore } from '../types';
+/** Legacy CMS configuration shape accepted during migration. */
+interface LegacyVariantConfig {
+    weight: number;
+    variant_label?: string;
+    reporting_event?: string;
+    hubspot_event_name?: string;
+    utm_content?: string;
+    url_params?: Record<string, string>;
+    reporting_params?: Record<string, string>;
+}
+/**
+ * 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;
+    /** When true, inject url_params from the assigned bucket */
+    injectUrlParams?: boolean | null;
+    /** Variant configuration JSON */
+    configuration?: LegacyVariantConfig[] | 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;
+}
+/**
+ * Normalize a single bucket config, accepting legacy field names.
+ */
+export declare function normalizeVariantConfig(raw: LegacyVariantConfig): AbTestVariantConfig;
+/**
+ * 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.
+ */
+export declare function createWebhookHandler(config: WebhookHandlerConfig): (request: Request) => Promise<Response>;
+export {};
+//# 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":"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"}