@drip-apex/sdk 0.1.0

package/src/debug.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __test, configureDebug, isDebugEnabled } from "./debug";
+
+const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+const originalLocalStorage = Object.getOwnPropertyDescriptor(globalThis, "localStorage");
+
+function setSearch(search: string) {
+  Object.defineProperty(globalThis, "location", {
+    configurable: true,
+    value: { search },
+  });
+}
+
+function installLocalStorage() {
+  const values = new Map<string, string>();
+  Object.defineProperty(globalThis, "localStorage", {
+    configurable: true,
+    value: {
+      getItem: (key: string) => values.get(key) ?? null,
+      setItem: (key: string, value: string) => {
+        values.set(key, value);
+      },
+      removeItem: (key: string) => {
+        values.delete(key);
+      },
+    },
+  });
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  if (originalLocation) {
+    Object.defineProperty(globalThis, "location", originalLocation);
+  } else {
+    delete (globalThis as any).location;
+  }
+  if (originalLocalStorage) {
+    Object.defineProperty(globalThis, "localStorage", originalLocalStorage);
+  } else {
+    delete (globalThis as any).localStorage;
+  }
+  configureDebug({ enabled: false, restrictMode: "off" });
+});
+
+describe("debug console activation", () => {
+  it("enables query-param debug before the backend expiry", () => {
+    vi.setSystemTime(new Date("2026-06-01T10:00:00.000Z"));
+    setSearch("?drip_debug=1");
+    installLocalStorage();
+
+    expect(
+      configureDebug({
+        enabled: true,
+        restrictMode: "query_param",
+        queryParam: "drip_debug",
+        expiresAt: "2026-06-02T10:00:00.000Z",
+      }),
+    ).toBe(true);
+    expect(isDebugEnabled()).toBe(true);
+  });
+
+  it("disables query-param debug after the backend expiry", () => {
+    vi.setSystemTime(new Date("2026-06-02T10:00:01.000Z"));
+    setSearch("?drip_debug=1");
+    installLocalStorage();
+
+    expect(
+      configureDebug({
+        enabled: true,
+        restrictMode: "query_param",
+        queryParam: "drip_debug",
+        expiresAt: "2026-06-02T10:00:00.000Z",
+      }),
+    ).toBe(false);
+    expect(isDebugEnabled()).toBe(false);
+  });
+
+  it("exposes expiry parsing for unit coverage", () => {
+    vi.setSystemTime(new Date("2026-06-01T10:00:00.000Z"));
+    expect(__test.isExpired("2026-06-01T09:59:59.000Z")).toBe(true);
+    expect(__test.isExpired("2026-06-01T10:00:01.000Z")).toBe(false);
+  });
+});

package/src/debug.ts

@@ -0,0 +1,138 @@
+/**
+ * Debug console for Drip SDK.
+ *
+ * Project-configured debug console. By default debug is off; the snippet can
+ * enable it for a specific request, query parameter, or user id.
+ */
+
+import type { DebugSettings } from "./types";
+
+let enabled = false;
+let configured: DebugSettings = { enabled: false, restrictMode: "off" };
+
+function getQueryValue(param: string): string | null {
+  try {
+    return new URLSearchParams(location.search).get(param);
+  } catch {
+    return null;
+  }
+}
+
+function tokenMatches(value: string | null, token?: string): boolean {
+  if (!value) return false;
+  if (!token) return value === "1" || value === "true";
+  return value === token;
+}
+
+function isExpired(expiresAt?: string | null): boolean {
+  if (!expiresAt) return false;
+  const timestamp = Date.parse(expiresAt);
+  return Number.isFinite(timestamp) && timestamp <= Date.now();
+}
+
+export function configureDebug(
+  settings?: DebugSettings,
+  userId?: string | null,
+  options?: { storageAllowed?: boolean },
+): boolean {
+  const storageAllowed = options?.storageAllowed !== false;
+  configured = storageAllowed
+    ? (settings ?? { enabled: false, restrictMode: "off" })
+    : { ...(settings ?? { enabled: false, restrictMode: "off" }), persist: false };
+  enabled = false;
+  if (!configured.enabled || configured.restrictMode === "off" || isExpired(configured.expiresAt)) {
+    if (storageAllowed) {
+      try {
+        localStorage.removeItem("drip_debug");
+      } catch {}
+    }
+    return false;
+  }
+
+  if (configured.active === true || configured.restrictMode === "always") {
+    enabled = true;
+  } else if (configured.restrictMode === "user_ids") {
+    enabled = Boolean(userId && configured.allowedUserIds?.includes(userId));
+  } else {
+    const queryParam = configured.queryParam || "drip_debug";
+    const value = getQueryValue(queryParam);
+    if (value === "0" || value === "false") {
+      if (storageAllowed) {
+        try {
+          localStorage.removeItem("drip_debug");
+        } catch {}
+      }
+      enabled = false;
+    } else {
+      enabled = tokenMatches(value, configured.token);
+    }
+  }
+
+  if (configured.persist && storageAllowed) {
+    try {
+      if (enabled) localStorage.setItem("drip_debug", "1");
+      else if (localStorage.getItem("drip_debug") === "1") enabled = true;
+    } catch {}
+  }
+
+  return enabled;
+}
+
+export function isDebugEnabled(): boolean {
+  if (enabled) return true;
+  if (isExpired(configured.expiresAt)) return false;
+  try {
+    enabled = configured.enabled === true
+      && configured.persist === true
+      && localStorage.getItem("drip_debug") === "1";
+  } catch {
+    enabled = false;
+  }
+  return enabled;
+}
+
+const PREFIX = "%c[drip]";
+const STYLE = "color: #8b5cf6; font-weight: bold;";
+const DIMMED = "color: #6b6f7b;";
+
+export function debugLog(category: string, message: string, data?: unknown): void {
+  if (!isDebugEnabled()) return;
+  if (typeof console === "undefined") return;
+
+  const timestamp = new Date().toISOString().slice(11, 23);
+  if (data !== undefined) {
+    console.log(`${PREFIX} %c${timestamp} %c[${category}] ${message}`, STYLE, DIMMED, "", data);
+  } else {
+    console.log(`${PREFIX} %c${timestamp} %c[${category}] ${message}`, STYLE, DIMMED, "");
+  }
+}
+
+export function debugWarn(category: string, message: string, data?: unknown): void {
+  if (!isDebugEnabled()) return;
+  if (typeof console === "undefined") return;
+
+  const timestamp = new Date().toISOString().slice(11, 23);
+  if (data !== undefined) {
+    console.warn(`${PREFIX} %c${timestamp} %c[${category}] ${message}`, STYLE, DIMMED, "", data);
+  } else {
+    console.warn(`${PREFIX} %c${timestamp} %c[${category}] ${message}`, STYLE, DIMMED, "");
+  }
+}
+
+export function debugGroup(label: string): void {
+  if (!isDebugEnabled()) return;
+  if (typeof console === "undefined") return;
+  console.group(`${PREFIX} ${label}`, STYLE);
+}
+
+export function debugGroupEnd(): void {
+  if (!isDebugEnabled()) return;
+  if (typeof console === "undefined") return;
+  console.groupEnd();
+}
+
+/** @internal — exposed for unit testing only. Tree-shaken from production build. */
+export const __test = {
+  isExpired,
+  tokenMatches,
+};

package/src/define.test.ts

@@ -0,0 +1,327 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineExperiment,
+  defineExperiments,
+  ExperimentDefinitionError,
+} from "./define";
+
+describe("defineExperiment", () => {
+  const validDef = {
+    slug: "hero-banner",
+    name: "Hero Banner Test",
+    variations: [
+      { id: "control", weight: 0.5, mutations: [], isControl: true },
+      {
+        id: "variant-a",
+        weight: 0.5,
+        mutations: [
+          { selector: ".hero", action: "text" as const, text: "New" },
+        ],
+      },
+    ],
+  };
+
+  // --- happy path -----------------------------------------------------------
+
+  it("returns a valid experiment for a correct definition", () => {
+    const result = defineExperiment(validDef);
+    expect(result).toBeDefined();
+    expect(result.id).toBe("hero-banner");
+    expect(result.name).toBe("Hero Banner Test");
+    expect(result.variations).toHaveLength(2);
+  });
+
+  it("returns a frozen object", () => {
+    const result = defineExperiment(validDef);
+    expect(Object.isFrozen(result)).toBe(true);
+  });
+
+  it("uses slug as the id in output", () => {
+    const result = defineExperiment(validDef);
+    expect(result.id).toBe(validDef.slug);
+    expect(result.slug).toBe(validDef.slug);
+  });
+
+  it("defaults trafficAllocation to 1", () => {
+    const result = defineExperiment(validDef);
+    expect(result.trafficAllocation).toBe(1);
+  });
+
+  it("defaults mutations to empty array when omitted from variation", () => {
+    const def = {
+      slug: "no-mutations",
+      name: "No Mutations",
+      variations: [
+        { id: "control", weight: 0.5, isControl: true },
+        { id: "variant-a", weight: 0.5 },
+      ],
+    };
+    const result = defineExperiment(def);
+    expect(result.variations[0].mutations).toEqual([]);
+    expect(result.variations[1].mutations).toEqual([]);
+  });
+
+  it("defaults isControl to false when omitted", () => {
+    const result = defineExperiment(validDef);
+    const nonControl = result.variations.find((v) => v.id === "variant-a");
+    expect(nonControl?.isControl).toBe(false);
+  });
+
+  // --- slug validation ------------------------------------------------------
+
+  it("throws for missing slug", () => {
+    const def = { ...validDef, slug: undefined } as any;
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for empty slug", () => {
+    const def = { ...validDef, slug: "" };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for uppercase slug", () => {
+    const def = { ...validDef, slug: "Hero-Banner" };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for slug with special characters", () => {
+    const def = { ...validDef, slug: "hero_banner!" };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("accepts single-char slug", () => {
+    // The code only applies the regex when slug.length > 1, so "a" passes.
+    const def = { ...validDef, slug: "a" };
+    const result = defineExperiment(def);
+    expect(result.id).toBe("a");
+  });
+
+  // --- name validation ------------------------------------------------------
+
+  it("throws for missing name", () => {
+    const def = { ...validDef, name: "" };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  // --- variation validation -------------------------------------------------
+
+  it("throws for less than 2 variations", () => {
+    const def = {
+      ...validDef,
+      variations: [{ id: "control", weight: 1, mutations: [], isControl: true }],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws when no control variation is present", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "a", weight: 0.5, mutations: [] },
+        { id: "b", weight: 0.5, mutations: [] },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws when multiple control variations are present", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "c1", weight: 0.5, mutations: [], isControl: true },
+        { id: "c2", weight: 0.5, mutations: [], isControl: true },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws when weights sum to more than 1 (beyond tolerance)", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "control", weight: 0.6, mutations: [], isControl: true },
+        { id: "variant-a", weight: 0.5, mutations: [] },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("accepts weights summing to 0.98 (within 0.01 tolerance)", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "control", weight: 0.49, mutations: [], isControl: true },
+        { id: "variant-a", weight: 0.49, mutations: [] },
+      ],
+    };
+    // 0.49 + 0.49 = 0.98, diff from 1 = 0.02 > 0.01 → should throw
+    // Wait: Math.abs(0.98 - 1) = 0.02 > 0.01 → throws.
+    // Use 0.995 instead: let's check the actual tolerance.
+    // Tolerance is 0.01. 0.98 diff = 0.02 → actually throws.
+    // Let me use 0.495 + 0.495 = 0.99, diff = 0.01, 0.01 > 0.01 is false → passes.
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("accepts weights summing to 0.995 (within 0.01 tolerance)", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "control", weight: 0.495, mutations: [], isControl: true },
+        { id: "variant-a", weight: 0.5, mutations: [] },
+      ],
+    };
+    // 0.495 + 0.5 = 0.995, diff = 0.005 <= 0.01 → passes
+    const result = defineExperiment(def);
+    expect(result).toBeDefined();
+  });
+
+  it("throws for duplicate variation IDs", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "same", weight: 0.5, mutations: [], isControl: true },
+        { id: "same", weight: 0.5, mutations: [] },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for negative variation weight", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "control", weight: -0.1, mutations: [], isControl: true },
+        { id: "variant-a", weight: 1.1, mutations: [] },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for variation weight greater than 1", () => {
+    const def = {
+      ...validDef,
+      variations: [
+        { id: "control", weight: 0, mutations: [], isControl: true },
+        { id: "variant-a", weight: 1.5, mutations: [] },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  // --- trafficAllocation validation -----------------------------------------
+
+  it("throws for negative trafficAllocation", () => {
+    const def = { ...validDef, trafficAllocation: -0.1 };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for trafficAllocation above 1", () => {
+    const def = { ...validDef, trafficAllocation: 1.1 };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("accepts trafficAllocation = 0", () => {
+    const def = { ...validDef, trafficAllocation: 0 };
+    const result = defineExperiment(def);
+    expect(result.trafficAllocation).toBe(0);
+  });
+
+  it("accepts trafficAllocation = 0.5", () => {
+    const def = { ...validDef, trafficAllocation: 0.5 };
+    const result = defineExperiment(def);
+    expect(result.trafficAllocation).toBe(0.5);
+  });
+
+  // --- goal validation ------------------------------------------------------
+
+  it("throws for duplicate goal IDs", () => {
+    const def = {
+      ...validDef,
+      goals: [
+        { id: "click-cta", type: "click" as const, selector: ".cta" },
+        { id: "click-cta", type: "click" as const, selector: ".other" },
+      ],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("throws for click goal without selector", () => {
+    const def = {
+      ...validDef,
+      goals: [{ id: "click-cta", type: "click" as const }],
+    };
+    expect(() => defineExperiment(def)).toThrow(ExperimentDefinitionError);
+  });
+
+  // --- error shape ----------------------------------------------------------
+
+  it("error has issues array with specific messages", () => {
+    const def = {
+      slug: "",
+      name: "",
+      variations: [],
+    } as any;
+    try {
+      defineExperiment(def);
+      expect.unreachable("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(ExperimentDefinitionError);
+      const err = e as ExperimentDefinitionError;
+      expect(Array.isArray(err.issues)).toBe(true);
+      expect(err.issues.length).toBeGreaterThan(0);
+      expect(err.issues.some((i) => i.includes("slug"))).toBe(true);
+      expect(err.issues.some((i) => i.includes("name"))).toBe(true);
+    }
+  });
+});
+
+describe("defineExperiments", () => {
+  it("throws on first invalid definition in batch", () => {
+    const defs = [
+      {
+        slug: "INVALID",
+        name: "Bad",
+        variations: [
+          { id: "control", weight: 0.5, mutations: [], isControl: true },
+          { id: "v", weight: 0.5, mutations: [] },
+        ],
+      },
+      {
+        slug: "valid-one",
+        name: "Good",
+        variations: [
+          { id: "control", weight: 0.5, mutations: [], isControl: true },
+          { id: "v", weight: 0.5, mutations: [] },
+        ],
+      },
+    ];
+    expect(() => defineExperiments(defs)).toThrow(ExperimentDefinitionError);
+  });
+
+  it("returns array of frozen experiments for valid batch", () => {
+    const defs = [
+      {
+        slug: "exp-one",
+        name: "Exp One",
+        variations: [
+          { id: "control", weight: 0.5, mutations: [], isControl: true },
+          { id: "v", weight: 0.5, mutations: [] },
+        ],
+      },
+      {
+        slug: "exp-two",
+        name: "Exp Two",
+        variations: [
+          { id: "control", weight: 0.5, mutations: [], isControl: true },
+          { id: "v", weight: 0.5, mutations: [] },
+        ],
+      },
+    ];
+    const results = defineExperiments(defs);
+    expect(results).toHaveLength(2);
+    expect(results[0].id).toBe("exp-one");
+    expect(results[1].id).toBe("exp-two");
+    expect(Object.isFrozen(results[0])).toBe(true);
+    expect(Object.isFrozen(results[1])).toBe(true);
+  });
+});