@drip-apex/sdk 0.1.0

package/src/define.ts

@@ -0,0 +1,208 @@
+/**
+ * defineExperiment — typed experiment definitions with validation.
+ *
+ * Usage:
+ *   const hero = defineExperiment({
+ *     slug: "hero-banner-v2",
+ *     name: "Hero Banner V2",
+ *     variations: [
+ *       { id: "control", weight: 0.5, mutations: [], isControl: true },
+ *       { id: "variant-a", weight: 0.5, mutations: [{ selector: ".hero h1", action: "text", text: "New headline" }] },
+ *     ],
+ *     targeting: { url: [{ type: "simple", pattern: "/" }] },
+ *     goals: [{ id: "cta-click", type: "click", selector: ".hero-cta" }],
+ *   });
+ */
+
+import type { Experiment, Goal, Mutation, Targeting, Variation } from "./types";
+
+// ---------------------------------------------------------------------------
+// Input types — looser than runtime types for developer ergonomics
+// ---------------------------------------------------------------------------
+
+export interface ExperimentDefinition {
+  /** Unique slug for GitOps upsert. Required for code-first experiments. */
+  slug: string;
+  /** Human-readable name. */
+  name: string;
+  /** Traffic allocation percentage (0–1). Default: 1. */
+  trafficAllocation?: number;
+  /** Targeting rules. */
+  targeting?: Targeting;
+  /** Hash attribute override (default: visitor cookie). */
+  hashAttribute?: string;
+  /** Variation definitions. At least two required. */
+  variations: VariationDefinition[];
+  /** Goal definitions for conversion tracking. */
+  goals?: GoalDefinition[];
+}
+
+export interface VariationDefinition {
+  /** Variation identifier (used as slug within the experiment). */
+  id: string;
+  /** Display name. Falls back to id if omitted. */
+  name?: string;
+  /** Traffic weight (0–1). All weights should sum to 1. */
+  weight: number;
+  /** DOM mutations to apply. Default: []. */
+  mutations?: Mutation[];
+  /** Optional typed value returned by feature-flag helpers. */
+  value?: unknown;
+  /** Custom CSS injected when this variation is active. */
+  css?: string;
+  /** Custom JavaScript executed when this variation is active. */
+  js?: string;
+  /** Reset JavaScript executed on SPA navigation away. */
+  resetJs?: string;
+  /** External CSS artifact URL loaded when this variation is active. */
+  externalCssUrl?: string;
+  /** External JS artifact URL loaded when this variation is active. */
+  externalJsUrl?: string;
+  /** Mark as control variation. Exactly one variation should be control. */
+  isControl?: boolean;
+}
+
+export interface GoalDefinition {
+  /** Goal identifier (used as slug). */
+  id: string;
+  /** Goal type. */
+  type: "click" | "pageview" | "custom" | "revenue";
+  /** CSS selector for click/element goals. */
+  selector?: string;
+  /** URL pattern for pageview goals. */
+  urlPattern?: string;
+  /** Only count once per session. Default: false. */
+  countOnce?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Validation errors
+// ---------------------------------------------------------------------------
+
+export class ExperimentDefinitionError extends Error {
+  public readonly issues: string[];
+
+  constructor(slug: string, issues: string[]) {
+    super(`Invalid experiment "${slug}": ${issues.join("; ")}`);
+    this.name = "ExperimentDefinitionError";
+    this.issues = issues;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+function validate(def: ExperimentDefinition): string[] {
+  const issues: string[] = [];
+
+  if (!def.slug || typeof def.slug !== "string") {
+    issues.push("slug is required and must be a non-empty string");
+  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(def.slug) && def.slug.length > 1) {
+    issues.push("slug must be lowercase alphanumeric with hyphens (e.g. 'hero-banner-v2')");
+  }
+
+  if (!def.name || typeof def.name !== "string") {
+    issues.push("name is required");
+  }
+
+  if (!Array.isArray(def.variations) || def.variations.length < 2) {
+    issues.push("at least 2 variations are required");
+  } else {
+    const controls = def.variations.filter((v) => v.isControl);
+    if (controls.length === 0) {
+      issues.push("exactly one variation must be marked as control (isControl: true)");
+    } else if (controls.length > 1) {
+      issues.push("only one variation can be the control");
+    }
+
+    const totalWeight = def.variations.reduce((sum, v) => sum + v.weight, 0);
+    if (Math.abs(totalWeight - 1) > 0.01) {
+      issues.push(`variation weights should sum to 1 (got ${totalWeight.toFixed(3)})`);
+    }
+
+    const ids = new Set<string>();
+    for (const v of def.variations) {
+      if (!v.id) issues.push("every variation must have an id");
+      if (ids.has(v.id)) issues.push(`duplicate variation id: "${v.id}"`);
+      ids.add(v.id);
+      if (v.weight < 0 || v.weight > 1) issues.push(`variation "${v.id}" weight must be between 0 and 1`);
+    }
+  }
+
+  if (def.trafficAllocation !== undefined) {
+    if (def.trafficAllocation < 0 || def.trafficAllocation > 1) {
+      issues.push("trafficAllocation must be between 0 and 1");
+    }
+  }
+
+  if (def.goals) {
+    const goalIds = new Set<string>();
+    for (const g of def.goals) {
+      if (!g.id) issues.push("every goal must have an id");
+      if (goalIds.has(g.id)) issues.push(`duplicate goal id: "${g.id}"`);
+      goalIds.add(g.id);
+
+      if (g.type === "click" && !g.selector) {
+        issues.push(`click goal "${g.id}" requires a selector`);
+      }
+    }
+  }
+
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+// defineExperiment
+// ---------------------------------------------------------------------------
+
+/**
+ * Define a typed, validated experiment configuration.
+ *
+ * Returns a frozen Experiment object ready for use with `init({ experiments: [...] })`.
+ * Throws `ExperimentDefinitionError` if the definition is invalid.
+ */
+export function defineExperiment(def: ExperimentDefinition): Experiment & { slug: string } {
+  const issues = validate(def);
+  if (issues.length > 0) {
+    throw new ExperimentDefinitionError(def.slug ?? "(unnamed)", issues);
+  }
+
+  const experiment: Experiment & { slug: string } = {
+    id: def.slug, // slug is used as the id for code-first experiments
+    slug: def.slug,
+    name: def.name,
+    trafficAllocation: def.trafficAllocation ?? 1,
+    targeting: def.targeting,
+    hashAttribute: def.hashAttribute,
+    variations: def.variations.map((v) => ({
+      id: v.id,
+      name: v.name,
+      weight: v.weight,
+      mutations: v.mutations ?? [],
+      value: v.value,
+      css: v.css,
+      js: v.js,
+      resetJs: v.resetJs,
+      externalCssUrl: v.externalCssUrl,
+      externalJsUrl: v.externalJsUrl,
+      isControl: v.isControl ?? false,
+    })),
+    goals: def.goals?.map((g) => ({
+      id: g.id,
+      type: g.type,
+      selector: g.selector,
+      urlPattern: g.urlPattern,
+      countOnce: g.countOnce,
+    })),
+  };
+
+  return Object.freeze(experiment) as Experiment & { slug: string };
+}
+
+/**
+ * Define multiple experiments at once. Validates all, throws on first invalid.
+ */
+export function defineExperiments(defs: ExperimentDefinition[]): Array<Experiment & { slug: string }> {
+  return defs.map(defineExperiment);
+}