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

package/README.md

@@ -0,0 +1,412 @@
+# @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/proxy.ts (Next 16) or src/middleware.ts (Next 15)
+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 proxy(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).*)'],
+};
+```
+
+#### Page-test route (static rebuild pattern)
+
+When using `createStaticAbTestMiddleware` with `variantPathPrefix: '/page-test'`, add a `/page-test/[...slugs]` route that rewrites serve variant content on the control URL. Use `findCanonicalPath(testsByPath, variantSlug)` to resolve the user-facing path, then call the paired handlers from `@se-studio/core-ui/server`:
+
+- `generatePageTestMetadata` — control `indexed` and canonical path in `<head>`
+- `generatePageTest` — variant body with control identity for breadcrumbs, `href`, and JSON-LD
+
+See the `se-marketing-sites-create-page` skill for the full route template. Direct visits to a variant's own CMS URL (normal page route) should keep using `generatePage`.
+
+### 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', { expire: 0 }),
+});
+```
+
+### 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`
+
+## URL parameter injection
+
+Page tests may define per-bucket `url_params` (or bare `utm_content` in configuration). Those values are stored on the assignment cookie for analytics.
+
+**Address-bar injection is opt-in.** Both middleware and `AbTestUtmScript` apply `url_params` to the URL **only when** the test has `injectUrlParams: true` (stored on the cookie assignment as `injectUrlParams: true`). Default is **false**.
+
+- Legacy cookies without `injectUrlParams` do **not** inject.
+- Keep `<AbTestUtmScript />` in the root layout so opt-in tests still surface params for GTM before hydration.
+
+## License
+
+MIT
+

package/dist/codegen/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/codegen/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/codegen/cli.ts"],"names":[],"mappings":""}

package/dist/codegen/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/** biome-ignore-all lint/suspicious/noConsole: CLI script */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { transformPageTest } from '../webhook/handler.js';
+import { buildStaticTestsByPath, generateAbTestsFileContent } from './generator.js';
+async function loadEnvFile(path) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eq = trimmed.indexOf('=');
+            if (eq === -1)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            const val = trimmed
+                .slice(eq + 1)
+                .trim()
+                .replace(/^["']|["']$/g, '');
+            if (key && !(key in process.env))
+                process.env[key] = val;
+        }
+    }
+    catch {
+        // .env.local not present — rely on process.env
+    }
+}
+function getOutputPath() {
+    const outputArg = process.argv.find((a) => a.startsWith('--output='));
+    if (outputArg)
+        return outputArg.slice('--output='.length);
+    return process.env['AB_TESTS_OUTPUT'] ?? './src/generated/abTests.ts';
+}
+async function main() {
+    await loadEnvFile('.env.local');
+    const draftOnly = process.env['DRAFT_ONLY'] === 'true';
+    const spaceId = process.env['CONTENTFUL_SPACE_ID'];
+    const accessToken = draftOnly
+        ? process.env['CONTENTFUL_PREVIEW_ACCESS_TOKEN']
+        : process.env['CONTENTFUL_ACCESS_TOKEN'];
+    const environment = process.env['CONTENTFUL_ENVIRONMENT'] ?? process.env['CONTENTFUL_ENVIRONMENT_NAME'] ?? 'master';
+    if (!spaceId || !accessToken) {
+        console.error(draftOnly
+            ? 'Missing CONTENTFUL_SPACE_ID or CONTENTFUL_PREVIEW_ACCESS_TOKEN'
+            : 'Missing CONTENTFUL_SPACE_ID or CONTENTFUL_ACCESS_TOKEN');
+        process.exit(1);
+    }
+    const host = draftOnly ? 'preview.contentful.com' : 'cdn.contentful.com';
+    const url = `https://${host}/spaces/${spaceId}/environments/${environment}/entries?content_type=pageTest&include=1`;
+    console.log(`Fetching A/B tests from Contentful (environment: ${environment}, preview: ${String(draftOnly)})...`);
+    const response = await fetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+        console.error(`Contentful API error: ${response.status} ${response.statusText}`);
+        process.exit(1);
+    }
+    const data = (await response.json());
+    const rawCount = data.items?.length ?? 0;
+    const includesCount = data.includes?.Entry?.length ?? 0;
+    console.log(`  → ${rawCount} pageTest entry(s) returned, ${includesCount} linked entry(s) in includes`);
+    const includesMap = new Map();
+    for (const entry of data.includes?.Entry ?? []) {
+        includesMap.set(entry.sys.id, entry);
+    }
+    const rawTests = (data.items ?? []).map((item) => {
+        const { fields, sys } = item;
+        const controlRef = fields['control'];
+        const controlEntry = controlRef ? includesMap.get(controlRef.sys.id) : undefined;
+        if (controlRef && !controlEntry) {
+            console.warn(`  → Test ${sys.id} ("${fields['cmsLabel']}"): control entry ${controlRef.sys.id} not found in includes (not published?)`);
+        }
+        const variantRefs = fields['variants'] ?? [];
+        const variantItems = variantRefs
+            .map((ref) => {
+            const entry = includesMap.get(ref.sys.id);
+            if (!entry) {
+                console.warn(`  → Test ${sys.id}: variant entry ${ref.sys.id} not found in includes (not published?)`);
+                return null;
+            }
+            return { sys: ref.sys, slug: entry.fields['slug'] };
+        })
+            .filter((v) => v !== null);
+        console.log(`  → Test "${fields['cmsLabel']}" (${sys.id}): enabled=${String(fields['enabled'])}, control slug="${controlEntry?.fields['slug'] ?? 'MISSING'}", ${variantItems.length} variant(s)`);
+        return {
+            sys,
+            cmsLabel: fields['cmsLabel'],
+            trackingLabel: fields['trackingLabel'],
+            enabled: fields['enabled'],
+            searchParameters: fields['searchParameters'],
+            injectUrlParams: fields['injectUrlParams'],
+            configuration: fields['configuration'],
+            control: controlRef && controlEntry
+                ? { sys: controlRef.sys, slug: controlEntry.fields['slug'] }
+                : null,
+            variantsCollection: { items: variantItems },
+        };
+    });
+    const tests = rawTests
+        .map((raw) => transformPageTest(raw, (id, reason) => console.warn(`  → Skipping test ${id}: ${reason}`)))
+        .filter((t) => t !== null);
+    console.log(`Found ${tests.length} active test(s)`);
+    for (const test of tests) {
+        console.log(`  → "${test.cmsLabel}" on /${test.controlSlug} with ${test.variants.length} variant(s)`);
+    }
+    const testsByPath = buildStaticTestsByPath(tests);
+    const pathCount = Object.keys(testsByPath).length;
+    console.log(`Mapped to ${pathCount} path(s): ${Object.keys(testsByPath).join(', ')}`);
+    const content = generateAbTestsFileContent(testsByPath);
+    const outputPath = resolve(getOutputPath());
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, content);
+    console.log(`Written to ${outputPath}`);
+}
+main().catch((error) => {
+    console.error('Failed to generate A/B test config:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/codegen/cli.js.map

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

package/dist/codegen/generator.d.ts

@@ -0,0 +1,42 @@
+import type { CachedAbTest } from '../middleware/types';
+import type { AbTest } from '../types';
+/**
+ * Build a plain-object testsByPath map suitable for static generation.
+ *
+ * This is the Record-based equivalent of the internal Map used at runtime.
+ * The result is JSON-serialisable and can be written to a generated TypeScript file
+ * with `generateAbTestsFileContent`.
+ *
+ * @param tests - Array of AbTest entries (e.g. from `transformPageTest`)
+ * @returns Record of normalised control path → CachedAbTest[]
+ */
+export declare function buildStaticTestsByPath(tests: AbTest[]): Record<string, CachedAbTest[]>;
+export interface GenerateAbTestsFileOptions {
+    /**
+     * The package to import `CachedAbTest` from in the generated file.
+     * @default "@se-studio/ab-testing"
+     */
+    importPath?: string;
+}
+/**
+ * Generate the content of a static TypeScript file exporting a `testsByPath` constant.
+ *
+ * Apps write this content to e.g. `src/lib/__generated/abTests.ts` at build time,
+ * then import `testsByPath` directly in their middleware — zero async overhead, no KV store needed.
+ *
+ * @example
+ * ```typescript
+ * // management/generateAbTests.ts
+ * import { writeFile } from 'node:fs/promises';
+ * import { transformPageTest } from '@se-studio/ab-testing/webhook';
+ * import { buildStaticTestsByPath, generateAbTestsFileContent } from '@se-studio/ab-testing/codegen';
+ * import { fetchRawPageTests } from '../src/cms/pageTests';
+ *
+ * const raw = await fetchRawPageTests();
+ * const tests = raw.map(r => transformPageTest(r)).filter(t => t !== null);
+ * const testsByPath = buildStaticTestsByPath(tests);
+ * await writeFile('./src/lib/__generated/abTests.ts', generateAbTestsFileContent(testsByPath));
+ * ```
+ */
+export declare function generateAbTestsFileContent(testsByPath: Record<string, CachedAbTest[]>, options?: GenerateAbTestsFileOptions): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/codegen/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/codegen/generator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAetF;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAC3C,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAWR"}

package/dist/codegen/generator.js

@@ -0,0 +1,56 @@
+import { computeCachedTest, normalizePath } from '../middleware/cache.js';
+/**
+ * Build a plain-object testsByPath map suitable for static generation.
+ *
+ * This is the Record-based equivalent of the internal Map used at runtime.
+ * The result is JSON-serialisable and can be written to a generated TypeScript file
+ * with `generateAbTestsFileContent`.
+ *
+ * @param tests - Array of AbTest entries (e.g. from `transformPageTest`)
+ * @returns Record of normalised control path → CachedAbTest[]
+ */
+export function buildStaticTestsByPath(tests) {
+    const result = {};
+    for (const test of tests) {
+        if (!test.enabled)
+            continue;
+        const path = normalizePath(test.controlSlug);
+        const cached = computeCachedTest(test);
+        const existing = result[path] ?? [];
+        existing.push(cached);
+        result[path] = existing;
+    }
+    return result;
+}
+/**
+ * Generate the content of a static TypeScript file exporting a `testsByPath` constant.
+ *
+ * Apps write this content to e.g. `src/lib/__generated/abTests.ts` at build time,
+ * then import `testsByPath` directly in their middleware — zero async overhead, no KV store needed.
+ *
+ * @example
+ * ```typescript
+ * // management/generateAbTests.ts
+ * import { writeFile } from 'node:fs/promises';
+ * import { transformPageTest } from '@se-studio/ab-testing/webhook';
+ * import { buildStaticTestsByPath, generateAbTestsFileContent } from '@se-studio/ab-testing/codegen';
+ * import { fetchRawPageTests } from '../src/cms/pageTests';
+ *
+ * const raw = await fetchRawPageTests();
+ * const tests = raw.map(r => transformPageTest(r)).filter(t => t !== null);
+ * const testsByPath = buildStaticTestsByPath(tests);
+ * await writeFile('./src/lib/__generated/abTests.ts', generateAbTestsFileContent(testsByPath));
+ * ```
+ */
+export function generateAbTestsFileContent(testsByPath, options = {}) {
+    const { importPath = '@se-studio/ab-testing' } = options;
+    const json = JSON.stringify(testsByPath, null, 2);
+    return `// This file is automatically generated from Contentful CMS — do not edit manually.
+// Re-generate: pnpm generate:ab-tests  (runs automatically via predev/prebuild)
+
+import type { CachedAbTest } from '${importPath}';
+
+export const testsByPath: Record<string, CachedAbTest[]> = ${json};
+`;
+}
+//# sourceMappingURL=generator.js.map

package/dist/codegen/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../src/codegen/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAI1E;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAe;IACpD,MAAM,MAAM,GAAmC,EAAE,CAAC;IAElD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,SAAS;QAE5B,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAEvC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IAC1B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,0BAA0B,CACxC,WAA2C,EAC3C,UAAsC,EAAE;IAExC,MAAM,EAAE,UAAU,GAAG,uBAAuB,EAAE,GAAG,OAAO,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAElD,OAAO;;;qCAG4B,UAAU;;6DAEc,IAAI;CAChE,CAAC;AACF,CAAC"}

package/dist/codegen/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @se-studio/ab-testing/codegen
+ *
+ * Build-time utilities for generating a static A/B test configuration file.
+ * Import these in a Node.js management script, not in edge/browser code.
+ */
+export type { GenerateAbTestsFileOptions } from './generator';
+export { buildStaticTestsByPath, generateAbTestsFileContent, } from './generator';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,aAAa,CAAC"}