@cascayd/experiment 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @cascayd/experiment
+
+A lightweight A/B testing SDK for React applications with server-side analytics integration.
+
+## Installation
+
+```bash
+npm install @cascayd/experiment
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+```typescript
+import { initCascayd } from '@cascayd/experiment'
+
+initCascayd({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://your-api-url.com' // optional, defaults to http://localhost:8000
+})
+```
+
+### 2. Use React Components
+
+```tsx
+import { Experiment, Variant } from '@cascayd/experiment'
+
+function MyComponent() {
+  return (
+    <Experiment id="button-color-test">
+      <Variant id="blue">
+        <button style={{ backgroundColor: 'blue' }}>Click me</button>
+      </Variant>
+      <Variant id="red">
+        <button style={{ backgroundColor: 'red' }}>Click me</button>
+      </Variant>
+    </Experiment>
+  )
+}
+```
+
+### 3. Record Conversions
+
+```typescript
+import { record } from '@cascayd/experiment'
+
+// Record a conversion event
+await record('conversion', {
+  experimentId: 'button-color-test',
+  value: 29.99 // optional numeric value
+})
+```
+
+## API Reference
+
+### `initCascayd(options: InitOptions)`
+
+Initializes the SDK with your API credentials.
+
+**Options:**
+- `apiKey` (required): Your API key for authentication
+- `baseUrl` (optional): Base URL for your API endpoint (defaults to `http://localhost:8000`)
+
+### `Experiment` Component
+
+Wraps your variants and handles variant assignment automatically.
+
+**Props:**
+- `id` (required): Unique identifier for the experiment
+
+**Children:**
+- One or more `Variant` components
+
+### `Variant` Component
+
+Defines a variant in your experiment.
+
+**Props:**
+- `id` (required): Unique identifier for this variant
+- `weight` (optional): Weight for this variant (defaults to equal distribution)
+
+**Example with weights:**
+```tsx
+<Experiment id="pricing-test">
+  <Variant id="control" weight={0.5}>
+    <OldPricing />
+  </Variant>
+  <Variant id="new-pricing" weight={0.5}>
+    <NewPricing />
+  </Variant>
+</Experiment>
+```
+
+### `record(type: EventType, options?: RecordOptions)`
+
+Records an event for analytics.
+
+**Event Types:**
+- `'impression'`: When a variant is shown (automatically recorded)
+- `'conversion'`: Custom conversion events
+
+**Options:**
+- `experimentId` (optional): ID of the experiment
+- `variantId` (optional): ID of the variant (auto-detected if not provided)
+- `value` (optional): Numeric value associated with the event
+
+### `assignVariant(experimentId: string)`
+
+Programmatically assign a variant for an experiment (server-side variant assignment).
+
+**Returns:** Promise with `{ variantId: string, config: ExperimentConfigResponse }`
+
+## Server-Side Usage
+
+For server-side rendering or programmatic variant assignment:
+
+```typescript
+import { assignVariant } from '@cascayd/experiment'
+
+const { variantId, config } = await assignVariant('my-experiment-id')
+```
+
+## TypeScript Support
+
+This package includes full TypeScript definitions. Types are exported from the main entry point:
+
+```typescript
+import type { InitOptions, EventType, RecordOptions } from '@cascayd/experiment'
+```
+
+## Requirements
+
+- React >= 18
+- Node.js >= 18
+
+## License
+
+MIT
+

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+import { InitOptions, ExperimentConfigResponse, EventType, RecordOptions } from './types';
+export declare function initCascayd(opts: InitOptions): void;
+export declare function assignVariant(experimentId: string): Promise<{
+    variantId: string;
+    config: ExperimentConfigResponse;
+}>;
+export declare function record(type: EventType, opts?: RecordOptions): Promise<void>;

package/dist/client.js

@@ -0,0 +1,60 @@
+import { getOrCreateSession, readVariantChoice } from './cookies';
+let API_KEY = '';
+let BASE_URL = 'http://localhost:8000';
+const SDK_VERSION = '0.1.0-dev';
+export function initCascayd(opts) {
+    API_KEY = opts.apiKey;
+    BASE_URL = opts.baseUrl ?? BASE_URL;
+    const masked = API_KEY ? API_KEY.slice(0, 3) + '***' + API_KEY.slice(-3) : '(empty)';
+    // Visible init log to confirm updated SDK loaded
+    // eslint-disable-next-line no-console
+    console.log('[cascayd-sdk]', SDK_VERSION, { baseUrl: BASE_URL, apiKey: masked });
+}
+async function fetchConfig(experimentId) {
+    const res = await fetch(`${BASE_URL}/experiments/${encodeURIComponent(experimentId)}/config`);
+    if (!res.ok)
+        throw new Error(`Config load failed: ${res.status}`);
+    return (await res.json());
+}
+function chooseByWeight(variants) {
+    const total = variants.reduce((s, v) => s + v.weight, 0);
+    const r = Math.random() * total;
+    let acc = 0;
+    for (const v of variants) {
+        acc += v.weight;
+        if (r <= acc)
+            return v.id;
+    }
+    return variants[variants.length - 1]?.id ?? 'control';
+}
+export async function assignVariant(experimentId) {
+    const cfg = await fetchConfig(experimentId);
+    const variantId = chooseByWeight(cfg.variants);
+    return { variantId, config: cfg };
+}
+export async function record(type, opts = {}) {
+    const sessionId = getOrCreateSession();
+    const body = {
+        type,
+        session_id: sessionId,
+    };
+    if (opts.experimentId) {
+        body.experiment_id = opts.experimentId;
+        const fromCookie = readVariantChoice(opts.experimentId);
+        const variantId = opts.variantId || fromCookie;
+        if (variantId)
+            body.variant_id = variantId;
+    }
+    if (typeof opts.value === 'number')
+        body.value = opts.value;
+    const res = await fetch(`${BASE_URL}/events`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${API_KEY}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`Record failed: ${res.status}`);
+}

package/dist/cookies.d.ts

@@ -0,0 +1,4 @@
+export declare function getOrCreateSession(): string;
+export declare function getVariantCookieKey(experimentId: string): string;
+export declare function readVariantChoice(experimentId: string): string | null;
+export declare function persistVariantChoice(experimentId: string, variantId: string): void;

package/dist/cookies.js

@@ -0,0 +1,33 @@
+function getCookie(name) {
+    const match = document.cookie.match(new RegExp('(?:^|; )' + name.replace(/[.$?*|{}()\[\]\\\/\+^]/g, '\\$&') + '=([^;]*)'));
+    return match ? decodeURIComponent(match[1]) : null;
+}
+function setCookie(name, value) {
+    document.cookie = `${name}=${encodeURIComponent(value)}; path=/; SameSite=Lax`;
+}
+function randomId() {
+    // lightweight uuid v4-ish
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (crypto.getRandomValues(new Uint8Array(1))[0] & 0xf) >>> 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export function getOrCreateSession() {
+    const key = 'cascayd:session';
+    let id = getCookie(key);
+    if (id)
+        return id;
+    id = randomId();
+    setCookie(key, id);
+    return id;
+}
+export function getVariantCookieKey(experimentId) {
+    return `cascayd:${experimentId}`;
+}
+export function readVariantChoice(experimentId) {
+    return getCookie(getVariantCookieKey(experimentId));
+}
+export function persistVariantChoice(experimentId, variantId) {
+    setCookie(getVariantCookieKey(experimentId), variantId);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { initCascayd, record, assignVariant } from './client';
+export { Experiment } from './react/Experiment';
+export { Variant } from './react/Variant';
+export type { InitOptions, EventType, RecordOptions } from './types';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { initCascayd, record, assignVariant } from './client';
+export { Experiment } from './react/Experiment';
+export { Variant } from './react/Variant';

package/dist/react/Experiment.d.ts

@@ -0,0 +1,5 @@
+export type ExperimentProps = {
+    id: string;
+    children: React.ReactNode;
+};
+export declare function Experiment({ id, children }: ExperimentProps): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>> | null;

package/dist/react/Experiment.js

@@ -0,0 +1,75 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { record } from '../client';
+import { getOrCreateSession, persistVariantChoice, readVariantChoice } from '../cookies';
+const sentImpressions = new Set();
+export function Experiment({ id, children }) {
+    const [active, setActive] = useState(null);
+    const hasRunRef = useRef(false);
+    // collect variant children (with optional weights)
+    const childrenArray = useMemo(() => {
+        const arr = [];
+        for (const child of [].concat(children)) {
+            if (!child || child.type?.displayName !== 'CascaydVariant')
+                continue;
+            arr.push({ id: child.props.id, weight: child.props.weight, element: child });
+        }
+        return arr;
+    }, [children]);
+    function chooseByWeight(items) {
+        const total = items.reduce((s, i) => s + i.weight, 0) || 1;
+        const r = Math.random() * total;
+        let acc = 0;
+        for (const it of items) {
+            acc += it.weight;
+            if (r <= acc)
+                return it.id;
+        }
+        return items[items.length - 1]?.id || 'control';
+    }
+    useEffect(() => {
+        if (hasRunRef.current)
+            return;
+        hasRunRef.current = true;
+        const existing = readVariantChoice(id);
+        if (existing) {
+            setActive(existing);
+            if (!sentImpressions.has(id)) {
+                sentImpressions.add(id);
+                void record('impression', { experimentId: id, variantId: existing });
+            }
+            return;
+        }
+        let cancelled = false;
+        getOrCreateSession();
+        // Decide assignment: use provided weights if any, else split evenly among variant children
+        const provided = childrenArray.filter((c) => typeof c.weight === 'number');
+        let chosen = null;
+        if (provided.length > 0) {
+            const normalized = (() => {
+                const sum = provided.reduce((s, c) => s + c.weight, 0) || 1;
+                return provided.map((c) => ({ id: c.id, weight: c.weight / sum }));
+            })();
+            chosen = chooseByWeight(normalized);
+        }
+        else if (childrenArray.length > 0) {
+            const equal = 1 / childrenArray.length;
+            const items = childrenArray.map((c) => ({ id: c.id, weight: equal }));
+            chosen = chooseByWeight(items);
+        }
+        if (chosen && !cancelled) {
+            persistVariantChoice(id, chosen);
+            setActive(chosen);
+            if (!sentImpressions.has(id)) {
+                sentImpressions.add(id);
+                void record('impression', { experimentId: id, variantId: chosen });
+            }
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [id]);
+    if (!active)
+        return null;
+    const match = childrenArray.find((c) => c.id === active);
+    return match ? match.element : null;
+}

package/dist/react/Variant.d.ts

@@ -0,0 +1,9 @@
+export type VariantProps = {
+    id: string;
+    weight?: number;
+    children?: React.ReactNode;
+};
+export declare function Variant({ id, children }: VariantProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Variant {
+    var displayName: string;
+}

package/dist/react/Variant.js

@@ -0,0 +1,5 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+export function Variant({ id, children }) {
+    return _jsx(_Fragment, { children: children });
+}
+Variant.displayName = 'CascaydVariant';

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export type InitOptions = {
+    apiKey: string;
+    baseUrl?: string;
+};
+export type VariantConfig = {
+    id: string;
+    weight: number;
+};
+export type ExperimentConfigResponse = {
+    experiment_id: string;
+    variants: VariantConfig[];
+};
+export type EventType = 'impression' | 'conversion';
+export type RecordOptions = {
+    experimentId?: string;
+    value?: number;
+    variantId?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cascayd/experiment",
+  "version": "0.1.0",
+  "description": "A lightweight A/B testing SDK for React applications with server-side analytics integration",
+  "keywords": [
+    "ab-testing",
+    "experimentation",
+    "react",
+    "sdk",
+    "analytics",
+    "variant",
+    "split-testing"
+  ],
+  "author": "cascayd",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/Experiment.d.ts",
+      "import": "./dist/react/Experiment.js",
+      "default": "./dist/react/Experiment.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ertersy40/ab-mvp-sdk.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}