@se-studio/ab-testing 1.0.82 → 1.0.84

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/ab-testing
 
+## 1.0.84
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.83
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.82
 
 ### Patch Changes

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 middleware.
+
+## 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
+// middleware.ts
+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 middleware(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

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/ab-testing",
-  "version": "1.0.82",
+  "version": "1.0.84",
   "description": "Server-side A/B testing framework for Next.js applications with Contentful CMS",
   "repository": {
     "type": "git",
@@ -42,7 +42,8 @@
   },
   "files": [
     "dist",
-    "*.md"
+    "*.md",
+    "docs"
   ],
   "keywords": [
     "ab-testing",