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

package/dist/webhook/handler.js

@@ -0,0 +1,128 @@
+/**
+ * Normalize a single bucket config, accepting legacy field names.
+ */
+export function normalizeVariantConfig(raw) {
+    const reporting_event = raw.reporting_event ?? raw.hubspot_event_name;
+    const url_params = raw.url_params ??
+        (raw.utm_content !== undefined ? { utm_content: raw.utm_content } : undefined);
+    const config = {
+        weight: raw.weight,
+    };
+    if (raw.variant_label) {
+        config.variant_label = raw.variant_label;
+    }
+    if (reporting_event) {
+        config.reporting_event = reporting_event;
+    }
+    if (url_params && Object.keys(url_params).length > 0) {
+        config.url_params = url_params;
+    }
+    if (raw.reporting_params && Object.keys(raw.reporting_params).length > 0) {
+        config.reporting_params = raw.reporting_params;
+    }
+    return config;
+}
+/**
+ * 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,
+    }));
+    const configuration = (raw.configuration ?? []).map(normalizeVariantConfig);
+    return {
+        id: raw.sys.id,
+        cmsLabel: raw.cmsLabel || '',
+        controlSlug,
+        searchParameters: raw.searchParameters ?? undefined,
+        trackingLabel: raw.trackingLabel ?? undefined,
+        enabled: raw.enabled ?? false,
+        injectUrlParams: raw.injectUrlParams ?? false,
+        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.
+ */
+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, normalizeVariantConfig, 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,sBAAsB,EACtB,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, normalizeVariantConfig, 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,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/docs/llms.md

@@ -0,0 +1,106 @@
+# @se-studio/ab-testing — LLM Reference
+
+Server-side A/B testing framework for Next.js App Router with Contentful CMS. Variants are assigned via cookies; decisions happen in Next.js `proxy` (Next 16) or `middleware` (Next 15). Call `createAbTestMiddleware` / `createStaticAbTestMiddleware` from either file — the factory API is unchanged.
+
+## Core Concepts
+
+- **Test**: a named experiment with 2+ variants, each mapped to a URL path
+- **Assignment**: a cookie that records which variant a user is seeing
+- **Middleware**: intercepts requests and rewrites URLs to the assigned variant path
+
+## Key Types
+
+```ts
+import type {
+  AbTest,              // { id, name, variants: AbTestVariant[] }
+  AbTestVariant,       // { id, name, path: string, weight: number }
+  AbTestAssignment,    // { testId, variantId }
+  AbTestCookie,        // serialised cookie value
+  AbTestVariantConfig, // { variantId, contentPath }
+  IBlobStore,          // storage interface for test configs (Vercel Blob)
+} from '@se-studio/ab-testing';
+```
+
+## Middleware Setup
+
+```ts
+// src/proxy.ts (Next 16) or src/middleware.ts (Next 15)
+import { createAbTestMiddleware } from '@se-studio/ab-testing';
+
+const abTestMiddleware = createAbTestMiddleware({
+  blobStore,       // IBlobStore — fetches test configs from Vercel Blob
+  cookieName: 'ab_assignment', // optional, default: DEFAULT_COOKIE_NAME
+  cookieMaxAge: 60 * 60 * 24 * 30, // optional, default: DEFAULT_COOKIE_MAX_AGE
+});
+
+export async function proxy(request: NextRequest) {
+  return abTestMiddleware(request);
+}
+```
+
+For static (no blob store) tests:
+
+```ts
+import { createStaticAbTestMiddleware } from '@se-studio/ab-testing';
+
+const abTestMiddleware = createStaticAbTestMiddleware({
+  tests: [
+    {
+      id: 'hero-test',
+      variants: [
+        { id: 'control', path: '/home', weight: 50 },
+        { id: 'variant-a', path: '/home-v2', weight: 50 },
+      ],
+    },
+  ],
+});
+```
+
+## Reading the Assignment (Client / Server)
+
+```ts
+import { useAbTestAssignments } from '@se-studio/ab-testing';
+
+// In a React component:
+const { assignments, isLoading } = useAbTestAssignments({ testIds: ['hero-test'] });
+const variant = assignments['hero-test']; // AbTestAssignment | undefined
+```
+
+## Webhook Handler (Contentful → update test cache)
+
+```ts
+import { createWebhookHandler } from '@se-studio/ab-testing';
+
+const handler = createWebhookHandler({
+  blobStore,
+  secret: process.env.WEBHOOK_SECRET!,
+});
+
+// In a Next.js route handler:
+export const POST = handler.handle;
+```
+
+## Cookie Utilities
+
+```ts
+import {
+  parseCookie,
+  serializeCookie,
+  readCookieFromDocument, // client-side
+  DEFAULT_COOKIE_NAME,
+  DEFAULT_COOKIE_MAX_AGE,
+} from '@se-studio/ab-testing';
+```
+
+## Low-Level Utilities
+
+```ts
+import {
+  selectVariant,       // weighted random variant selection
+  getAssignment,       // read assignment from cookies
+  setAssignment,       // write assignment to response cookies
+  isValidAssignment,   // validate an assignment object
+  normalizePath,       // normalise URL paths for comparison
+  findCanonicalPath,   // resolve variant path back to canonical
+} from '@se-studio/ab-testing';
+```

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@se-studio/ab-testing",
+  "version": "0.0.0-next16-20260822103555",
+  "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"
+    },
+    "./codegen": {
+      "types": "./dist/codegen/index.d.ts",
+      "import": "./dist/codegen/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./reporting": {
+      "types": "./dist/reporting/buildExperimentImpression.d.ts",
+      "import": "./dist/reporting/buildExperimentImpression.js"
+    }
+  },
+  "bin": {
+    "generate-ab-tests": "./dist/codegen/cli.js"
+  },
+  "files": [
+    "dist",
+    "*.md",
+    "docs"
+  ],
+  "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.5.0 <17",
+    "react": "^19.0.0",
+    "@se-studio/core-ui": "0.0.0-next16-20260822103555"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.5",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "next": "^16.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@se-studio/core-ui": "0.0.0-next16-20260822103555"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsc --project tsconfig.build.json --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome lint .",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}