@drip-apex/sdk 0.1.0

package/src/exposure-signals.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import { buildExposureSignalContext } from "./exposure-signals";
+
+describe("buildExposureSignalContext", () => {
+  it("does not attach geo.country to exposure analytics", () => {
+    const context = buildExposureSignalContext({
+      attributes: { "geo.country": "DE" },
+      customSignals: [{ key: "geo.country", valueType: "string" }],
+    });
+    expect(context).toBeNull();
+    expect(JSON.stringify(context)).not.toContain("DE");
+  });
+  it("maps the built-in exposure allowlist", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        "traffic.source": "paid",
+        "visitor.returning": true,
+        "shopify.page_type": "product",
+        "shopify.product_type": "Skincare",
+        "cart.item_count": 3,
+        "navigator.language": "en-US",
+      },
+    })).toEqual({
+      cart_item_count: 3,
+      language: "en-US",
+      page_type: "product",
+      product_type: "Skincare",
+      traffic_source: "paid",
+      visitor_returning: true,
+    });
+  });
+
+  it("excludes private and high-cardinality attributes", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        "cookie.value": "session=secret",
+        "url.path": "/products/a",
+        "url.query": "?token=secret",
+        "utm.source": "newsletter",
+        "device.browser": "Chrome",
+        "geo.city": "Berlin",
+        referrer: "https://search.test",
+        "recently_viewed.handles": ["a", "b"],
+        "search.last_query": "sensitive search",
+        "shopify.customer_tag": ["vip"],
+      },
+      customSignals: [
+        { key: "cookie.value", valueType: "string" },
+        { key: "url.path", valueType: "string" },
+        { key: "recently_viewed.handles", valueType: "string_array" },
+        { key: "shopify.customer_tag", valueType: "string_array" },
+      ],
+    })).toBeNull();
+  });
+
+  it("excludes custom signals whose keys look like PII", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        "customer.email": "jane@example.com",
+        "contact.phone": "+491701234567",
+        "shipping.address": "Some Street 1",
+        "billing.iban": "DE00 0000",
+        "auth.token": "tok_abc",
+        "visitor.dob": "1985-01-01",
+        "customer.name": "Jane Doe",
+        "quiz.answer": "hydration",
+      },
+      customSignals: [
+        { key: "customer.email", valueType: "string" },
+        { key: "contact.phone", valueType: "string" },
+        { key: "shipping.address", valueType: "string" },
+        { key: "billing.iban", valueType: "string" },
+        { key: "auth.token", valueType: "string" },
+        { key: "visitor.dob", valueType: "string" },
+        { key: "customer.name", valueType: "string" },
+        { key: "quiz.answer", valueType: "string" },
+      ],
+    })).toEqual({ quiz_answer: "hydration" });
+  });
+
+  it("detects PII tokens separated by camel-case boundaries", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        customerEmail: "jane@example.com",
+        phoneNumber: "+491701234567",
+        sessionToken: "tok_abc",
+        quizAnswer: "hydration",
+      },
+      customSignals: [
+        { key: "customerEmail", valueType: "string" },
+        { key: "phoneNumber", valueType: "string" },
+        { key: "sessionToken", valueType: "string" },
+        { key: "quizAnswer", valueType: "string" },
+      ],
+    })).toEqual({ quizanswer: "hydration" });
+  });
+
+  it("includes scalar custom signals and filters unsupported value types", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        "quiz.answer": " Dry skin ",
+        "loyalty.tier": "gold",
+        "profile.age": 42,
+        "customer.logged_in": false,
+        "json.payload": { nested: true },
+        "list.values": ["a", "b"],
+        "traffic.source.detail": "custom collision",
+      },
+      customSignals: [
+        { key: "quiz.answer", valueType: "string" },
+        { key: "loyalty.tier", valueType: "string" },
+        { key: "profile.age", valueType: "number" },
+        { key: "customer.logged_in", valueType: "boolean" },
+        { key: "json.payload", valueType: "json" },
+        { key: "list.values", valueType: "string_array" },
+        { key: "traffic.source.detail", valueType: "string" },
+      ],
+    })).toEqual({
+      customer_logged_in: false,
+      loyalty_tier: "gold",
+      profile_age: 42,
+      quiz_answer: "Dry skin",
+    });
+  });
+
+  it("truncates strings and drops empty or non-scalar values", () => {
+    const long = "x".repeat(150);
+    const context = buildExposureSignalContext({
+      attributes: {
+        "traffic.source": ` ${long} `,
+        "navigator.language": "",
+        "cart.item_count": Number.POSITIVE_INFINITY,
+        "shopify.page_type": ["product"],
+        "shopify.product_type": { value: "Serum" },
+      },
+    });
+
+    expect(context).toEqual({ traffic_source: "x".repeat(120) });
+  });
+
+  it("caps output at 24 keys by sorted key order", () => {
+    const attributes: Record<string, unknown> = {};
+    const customSignals = Array.from({ length: 30 }, (_, index) => {
+      const suffix = String(index).padStart(2, "0");
+      const key = `signal.${suffix}`;
+      attributes[key] = suffix;
+      return { key, valueType: "string" as const };
+    });
+
+    const context = buildExposureSignalContext({ attributes, customSignals });
+
+    expect(Object.keys(context ?? {})).toHaveLength(24);
+    expect(context).toHaveProperty("signal_23", "23");
+    expect(context).not.toHaveProperty("signal_24");
+  });
+
+  it("caps serialized payload size by dropping keys from the sorted end", () => {
+    const attributes: Record<string, unknown> = {};
+    const customSignals = Array.from({ length: 24 }, (_, index) => {
+      const suffix = String(index).padStart(2, "0");
+      const key = `oversized.${suffix}`;
+      attributes[key] = `${suffix}-${"x".repeat(118)}`;
+      return { key, valueType: "string" as const };
+    });
+
+    const context = buildExposureSignalContext({ attributes, customSignals });
+
+    expect(JSON.stringify(context).length).toBeLessThanOrEqual(2000);
+    expect(context).toHaveProperty("oversized_00");
+    expect(context).not.toHaveProperty("oversized_23");
+  });
+
+  it("returns null when no allowed values remain", () => {
+    expect(buildExposureSignalContext({
+      attributes: {
+        "traffic.source": " ",
+        "shopify.page_type": null,
+        "cart.item_count": Number.NaN,
+      },
+    })).toBeNull();
+  });
+});

package/src/exposure-signals.ts

@@ -0,0 +1,110 @@
+import type { RuntimeSignalDefinition } from "./types";
+import { containsPiiToken } from "./pii-keys";
+
+type ExposureSignalValue = string | number | boolean;
+
+const BUILT_IN_SIGNALS: Array<[source: string, output: string]> = [
+  ["traffic.source", "traffic_source"],
+  ["visitor.returning", "visitor_returning"],
+  ["shopify.page_type", "page_type"],
+  ["shopify.product_type", "product_type"],
+  ["cart.item_count", "cart_item_count"],
+  ["navigator.language", "language"],
+];
+
+const BUILT_IN_OUTPUT_KEYS = new Set(BUILT_IN_SIGNALS.map(([, output]) => output));
+const MAX_KEYS = 24;
+const MAX_JSON_CHARS = 2000;
+const MAX_STRING_CHARS = 120;
+const EXCLUDED_CUSTOM_KEYS = new Set([
+  "cookie.value",
+  "referrer",
+  "search.last_query",
+  "shopify.customer_tag",
+]);
+const EXCLUDED_CUSTOM_PREFIXES = [
+  "url.",
+  "utm.",
+  "device.",
+  "geo.",
+  "recently_viewed.",
+];
+
+// Custom signal keys are merchant-defined, so key-syntax validation alone
+// cannot stop PII-shaped signals (customer.email, phone, …) from reaching
+// analytics. Any key containing one of these tokens is never attached to
+// exposure events, regardless of merchant configuration.
+function normalizeValue(value: unknown): ExposureSignalValue | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? trimmed.slice(0, MAX_STRING_CHARS) : undefined;
+  }
+  return undefined;
+}
+
+function outputKeyForCustomSignal(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+
+function collidesWithBuiltInPrefix(key: string): boolean {
+  if (!key) return true;
+  for (const builtInKey of BUILT_IN_OUTPUT_KEYS) {
+    if (key === builtInKey || key.startsWith(`${builtInKey}_`)) return true;
+  }
+  return false;
+}
+
+function isExcludedCustomSignalKey(key: string): boolean {
+  const normalized = key.trim().toLowerCase();
+  if (EXCLUDED_CUSTOM_KEYS.has(normalized)) return true;
+  if (EXCLUDED_CUSTOM_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return true;
+  }
+  return containsPiiToken(key);
+}
+
+function compactToLimits(values: Record<string, ExposureSignalValue>): Record<string, ExposureSignalValue> | null {
+  const keys = Object.keys(values).sort();
+  while (keys.length > MAX_KEYS) {
+    const key = keys.pop();
+    if (key) delete values[key];
+  }
+
+  while (keys.length > 0 && JSON.stringify(values).length > MAX_JSON_CHARS) {
+    const key = keys.pop();
+    if (key) delete values[key];
+  }
+
+  if (Object.keys(values).length === 0) return null;
+  return Object.fromEntries(
+    Object.keys(values).sort().map((key) => [key, values[key]]),
+  ) as Record<string, ExposureSignalValue>;
+}
+
+export function buildExposureSignalContext(input: {
+  attributes: Record<string, unknown>;
+  customSignals?: RuntimeSignalDefinition[];
+}): Record<string, ExposureSignalValue> | null {
+  const values: Record<string, ExposureSignalValue> = {};
+
+  for (const [sourceKey, outputKey] of BUILT_IN_SIGNALS) {
+    const value = normalizeValue(input.attributes[sourceKey]);
+    if (value !== undefined) values[outputKey] = value;
+  }
+
+  for (const signal of input.customSignals ?? []) {
+    if (!signal.key) continue;
+    if (isExcludedCustomSignalKey(signal.key)) continue;
+    if (!["string", "number", "boolean"].includes(signal.valueType ?? "string")) continue;
+    const outputKey = outputKeyForCustomSignal(signal.key);
+    if (collidesWithBuiltInPrefix(outputKey)) continue;
+    if (Object.prototype.hasOwnProperty.call(values, outputKey)) continue;
+    const value = normalizeValue(input.attributes[signal.key]);
+    if (value !== undefined) values[outputKey] = value;
+  }
+
+  return compactToLimits(values);
+}

package/src/flags.test.ts

@@ -0,0 +1,322 @@
+import { describe, expect, it } from "vitest";
+import {
+  evaluateFlag,
+  evaluateFlagAssignment,
+  evaluateFlagValue,
+  defineFlagExperiment,
+} from "./flags";
+import type { Experiment } from "./types";
+
+describe("defineFlagExperiment", () => {
+  it("creates exactly 2 variations", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 50,
+    });
+    expect(flag.variations).toHaveLength(2);
+  });
+
+  it("has one control variation with isControl: true", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 50,
+    });
+    const control = flag.variations.find((v) => v.id === "control");
+    expect(control).toBeDefined();
+    expect(control!.isControl).toBe(true);
+  });
+
+  it("has one enabled variation", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 50,
+    });
+    const enabled = flag.variations.find((v) => v.id === "enabled");
+    expect(enabled).toBeDefined();
+    expect(enabled!.isControl).toBe(false);
+  });
+
+  it("stores typed off and on values", () => {
+    const flag = defineFlagExperiment({
+      slug: "offer-copy",
+      name: "Offer Copy",
+      rolloutPercent: 100,
+      offValue: "standard",
+      onValue: { headline: "VIP offer" },
+    });
+
+    expect(flag.featureFlag?.key).toBe("offer-copy");
+    expect(flag.variations[0].value).toBe("standard");
+    expect(flag.variations[1].value).toEqual({ headline: "VIP offer" });
+  });
+
+  it("weights sum to 1", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 73,
+    });
+    const total = flag.variations.reduce((sum, v) => sum + v.weight, 0);
+    expect(total).toBeCloseTo(1, 10);
+  });
+
+  it("control has empty mutations", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 50,
+    });
+    const control = flag.variations.find((v) => v.id === "control");
+    expect(control!.mutations).toEqual([]);
+  });
+
+  it("rolloutPercent 50 produces weights [0.5, 0.5]", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 50,
+    });
+    expect(flag.variations[0].weight).toBeCloseTo(0.5);
+    expect(flag.variations[1].weight).toBeCloseTo(0.5);
+  });
+
+  it("rolloutPercent 0 produces weights [1, 0]", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 0,
+    });
+    expect(flag.variations[0].weight).toBe(1);
+    expect(flag.variations[1].weight).toBe(0);
+  });
+
+  it("rolloutPercent 100 produces weights [0, 1]", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    expect(flag.variations[0].weight).toBe(0);
+    expect(flag.variations[1].weight).toBe(1);
+  });
+
+  it("clamps rolloutPercent > 100 to 100", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 150,
+    });
+    expect(flag.variations[0].weight).toBe(0);
+    expect(flag.variations[1].weight).toBe(1);
+  });
+
+  it("clamps rolloutPercent < 0 to 0", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: -50,
+    });
+    expect(flag.variations[0].weight).toBe(1);
+    expect(flag.variations[1].weight).toBe(0);
+  });
+});
+
+describe("evaluateFlag", () => {
+  it("returns true when rolloutPercent is 100 (all users enabled)", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    // With weight [0, 1] all users land in "enabled"
+    const result = evaluateFlag("test-flag", [flag], { userId: "user-abc" });
+    expect(result).toBe(true);
+  });
+
+  it("returns false when rolloutPercent is 0 (all users control)", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 0,
+    });
+    // With weight [1, 0] all users land in "control"
+    const result = evaluateFlag("test-flag", [flag], { userId: "user-abc" });
+    expect(result).toBe(false);
+  });
+
+  it("returns false when flag is not found in experiments", () => {
+    const result = evaluateFlag("nonexistent", [], { userId: "user-abc" });
+    expect(result).toBe(false);
+  });
+
+  it("does not check experiment.status", () => {
+    // evaluateFlag does not filter by status; it only checks targeting and traffic
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    // Manually set status to "paused" — evaluateFlag should still return true
+    const withStatus = { ...flag, status: "paused" } as Experiment;
+    const result = evaluateFlag("test-flag", [withStatus], {
+      userId: "user-abc",
+    });
+    expect(result).toBe(true);
+  });
+
+  it("returns false when targeting does not match", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    // Add targeting that requires a specific URL
+    const targeted: Experiment = {
+      ...flag,
+      targeting: {
+        url: [{ type: "simple", pattern: "*.example.com/special/*" }],
+      },
+    };
+    const result = evaluateFlag("test-flag", [targeted], {
+      userId: "user-abc",
+      url: "https://other.test/page",
+    });
+    expect(result).toBe(false);
+  });
+});
+
+describe("evaluateFlagAssignment", () => {
+  it("returns a full Assignment object when flag is enabled", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    const assignment = evaluateFlagAssignment("test-flag", [flag], {
+      userId: "user-abc",
+    });
+    expect(assignment).not.toBeNull();
+    expect(assignment!.experimentId).toBe("test-flag");
+    expect(assignment!.variationId).toBe("enabled");
+    expect(assignment!.isControl).toBe(false);
+    expect(assignment!.mutations).toEqual([]);
+  });
+
+  it("returns null when flag is not found", () => {
+    const assignment = evaluateFlagAssignment("nonexistent", [], {
+      userId: "user-abc",
+    });
+    expect(assignment).toBeNull();
+  });
+
+  it("returns assignment with isControl true when rolloutPercent is 0", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 0,
+    });
+    const assignment = evaluateFlagAssignment("test-flag", [flag], {
+      userId: "user-abc",
+    });
+    expect(assignment).not.toBeNull();
+    expect(assignment!.variationId).toBe("control");
+    expect(assignment!.isControl).toBe(true);
+  });
+
+  it("keeps variation buckets balanced inside partial traffic allocation", () => {
+    const flag: Experiment = {
+      ...defineFlagExperiment({
+        slug: "test-flag",
+        name: "Test Flag",
+        rolloutPercent: 50,
+      }),
+      trafficAllocation: 0.5,
+    };
+
+    const assignments = Array.from({ length: 2000 }, (_, index) =>
+      evaluateFlagAssignment("test-flag", [flag], { userId: `user-${index}` }),
+    ).filter((assignment): assignment is NonNullable<typeof assignment> =>
+      assignment !== null,
+    );
+
+    const control = assignments.filter((assignment) => assignment.variationId === "control").length;
+    const enabled = assignments.filter((assignment) => assignment.variationId === "enabled").length;
+
+    expect(assignments.length).toBeGreaterThan(900);
+    expect(assignments.length).toBeLessThan(1100);
+    expect(control / assignments.length).toBeGreaterThan(0.45);
+    expect(enabled / assignments.length).toBeGreaterThan(0.45);
+  });
+
+  it("returns null when targeting does not match", () => {
+    const flag = defineFlagExperiment({
+      slug: "test-flag",
+      name: "Test Flag",
+      rolloutPercent: 100,
+    });
+    const targeted: Experiment = {
+      ...flag,
+      targeting: {
+        url: [{ type: "simple", pattern: "*.example.com/special/*" }],
+      },
+    };
+    const assignment = evaluateFlagAssignment("test-flag", [targeted], {
+      userId: "user-abc",
+      url: "https://other.test/page",
+    });
+    expect(assignment).toBeNull();
+  });
+});
+
+describe("evaluateFlagValue", () => {
+  it("returns the typed on value for enabled visitors", () => {
+    const flag = defineFlagExperiment({
+      slug: "offer-copy",
+      name: "Offer Copy",
+      rolloutPercent: 100,
+      offValue: "control",
+      onValue: "personalized",
+    });
+
+    expect(
+      evaluateFlagValue("offer-copy", [flag], { userId: "user-abc" }, "fallback"),
+    ).toBe("personalized");
+  });
+
+  it("returns the fallback when targeting does not match", () => {
+    const flag = defineFlagExperiment({
+      slug: "vip-offer",
+      name: "VIP Offer",
+      rolloutPercent: 100,
+      onValue: { badge: "VIP" },
+      targeting: {
+        segmentRules: [
+          {
+            id: "11111111-1111-4111-8111-111111111111",
+            rules: {
+              version: 1,
+              operator: "and",
+              conditions: [
+                {
+                  signal: "shopify.customer_tag",
+                  operator: "contains",
+                  value: "VIP",
+                },
+              ],
+            },
+          },
+        ],
+      },
+    });
+
+    expect(
+      evaluateFlagValue("vip-offer", [flag], {
+        userId: "user-abc",
+        attributes: { "shopify.customer_tag": ["Regular"] },
+      }, "fallback"),
+    ).toBe("fallback");
+  });
+});