@drip-apex/sdk 0.1.0 → 0.3.0

package/src/types.ts

@@ -29,7 +29,7 @@ export interface UrlRule {
 
 export interface AttributeRule {
   attribute: string;
-  operator: "equals" | "contains" | "exists" | "in";
+  operator: "equals" | "contains" | "exists" | "in" | "not_in";
   value?: string | string[];
 }
 
@@ -94,7 +94,6 @@ export interface PageTargetingRule {
   advancedCondition?: {
     code?: string;
     description?: string;
-    pollOnRules?: boolean;
   } | null;
   trigger?: {
     mode?:
@@ -130,6 +129,8 @@ export interface Targeting {
   segmentRules?: SegmentTargetingRule[];
   lifecycle?: {
     mode?: "reset" | "deactivate" | "force_reset" | "persistent";
+    explicit?: boolean;
+    source?: "author" | "page";
   };
 }
 
@@ -144,11 +145,14 @@ export interface CaptureRule {
 
 export interface Goal {
   id: string;
+  name?: string;
   type: "click" | "pageview" | "custom" | "revenue";
   selector?: string;
   /** Case-insensitive text content match. When set, the clicked element's textContent must include this string. */
   textMatch?: string;
   urlPattern?: string;
+  /** Optional Page scope. The goal is active only while this Page matches. */
+  pageId?: string;
   /** Custom analytics event name that should count as this goal. */
   eventName?: string;
   countOnce?: boolean;
@@ -189,11 +193,21 @@ export interface SnippetDeliveryManifest {
   criticalMutationPlan?: SnippetCriticalMutationPlanItem[];
 }
 
+export interface UrlBlock {
+  id: string;
+  name: string;
+  urlRules: UrlRule[];
+  mutations: Mutation[];
+  css?: string;
+  js?: string;
+}
+
 export interface Variation {
   id: string;
   name?: string;
   weight: number;
   mutations: Mutation[];
+  urlBlocks?: UrlBlock[];
   value?: unknown;
   css?: string;
   js?: string;
@@ -203,6 +217,10 @@ export interface Variation {
   externalJsUrl?: string;
   harnessSession?: HarnessSessionInfo;
   isControl?: boolean;
+  /** Destination for redirect experiments; absent on the control variation. */
+  redirectUrl?: string;
+  /** Persistence provenance used by runtime safety policy. */
+  artifactSource?: string;
 }
 
 export interface HarnessSessionInfo {
@@ -218,7 +236,14 @@ export interface Experiment {
   kind?: "experiment" | "feature_flag" | "personalization";
   name?: string;
   status?: string;
+  runtime_disabled?: boolean | null;
+  environment_key?: string | null;
+  weekdaySchedule?: import("./weekday-schedule").WeekdaySchedule;
+  /** Delivery classification authored by Apex (`mutation` or `redirect`). */
+  experimentType?: "mutation" | "redirect";
   targeting?: Targeting;
+  /** Page definitions used only to decide whether page-scoped goals listen. */
+  goalPageRules?: PageTargetingRule[];
   trafficAllocation?: number;
   assignmentEpoch?: number;
   assignmentEpochStartedAt?: string | null;
@@ -232,6 +257,10 @@ export interface Experiment {
     moves?: boolean;
     sampleRate?: number;
   };
+  replayCapture?: {
+    enabled?: boolean;
+    sampleRate?: number;
+  };
   variations: Variation[];
   hashAttribute?: string;
   goals?: Goal[];
@@ -273,6 +302,10 @@ export interface Assignment {
   experimentId: string;
   experimentName?: string;
   variationId: string;
+  /** Whether this assignment may render and activate page-scoped behavior here. */
+  pageActive: boolean;
+  /** Identifies the selected per-URL artifact without retaining its content. */
+  activeUrlBlockId?: string;
   index: number;
   mutations: Mutation[];
   value?: unknown;
@@ -289,6 +322,8 @@ export interface Assignment {
   externalJsUrl?: string;
   harnessSession?: HarnessSessionInfo;
   isControl: boolean;
+  redirectUrl?: string;
+  artifactSource?: string;
   hashValue: string;
   assignmentEpoch?: number;
 }
@@ -296,16 +331,12 @@ export interface Assignment {
 export type ExecutionMode = "auto" | "edge" | "client";
 export type AntiFlickerMode = "scoped" | "full" | "off" | "custom";
 export type TrackingStart = "idle" | "immediate";
-export type CustomJsPolicy = "strict" | "hybrid" | "flex";
+export type CustomJsPolicy = "strict" | "hybrid";
 export type PlatformHint = "auto" | "shopify" | "spa" | "shopware";
-export type RouterMode = "auto" | "history" | "navigation" | "none";
+export type RouterMode = "auto" | "history" | "navigation" | "polling" | "none";
 export type ActivationMode = "auto" | "observer" | "manual";
 export type PageTriggerMode = "direct" | "url_change" | "dom_change" | "manual";
-export type PerfFeatureFlag =
-  | "perf_platform_router_v1"
-  | "perf_shopify_pixel_buffer_v1"
-  | "perf_spa_incremental_reapply_v1"
-  | "perf_empty_project_v1";
+export type PerfFeatureFlag = "perf_empty_project_v1";
 export type PerfFeatureFlags = Partial<Record<PerfFeatureFlag, boolean>>;
 
 export interface ProjectPrerequisites {
@@ -315,7 +346,7 @@ export interface ProjectPrerequisites {
 
 export interface ConsentModeSettings {
   enabled?: boolean;
-  provider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes";
+  provider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes" | "cookiescript" | "borlabs";
   getter?: string;
   requiredGroup?: string;
 }
@@ -325,6 +356,7 @@ export interface DebugSettings {
   restrictMode?: "off" | "query_param" | "user_ids" | "always";
   queryParam?: string;
   token?: string;
+  tokenRequired?: boolean;
   allowedUserIds?: string[];
   persist?: boolean;
   disableCache?: boolean;
@@ -340,12 +372,15 @@ export interface SpaSettings {
   domChangeTrigger?: boolean;
   debounceMs?: number;
   allowIframes?: boolean;
-  applyTiming?: "immediate" | "after_hydration";
+  applyTiming?: "immediate" | "after_hydration" | "early_reassert";
   hydrationTimeoutMs?: number;
 }
 
 export interface PageTriggerSettings {
   defaultMode?: PageTriggerMode;
+  urlPollIntervalMs?: number;
+  rulePollWindowMs?: number;
+  rulePollIntervalMs?: number;
 }
 
 export interface ExternalTrackingSettings {
@@ -527,6 +562,27 @@ export interface ActivationDiagnostics {
   experiments: ExperimentActivationDiagnostic[];
 }
 
+export type PageDeactivationMode =
+  | "reset"
+  | "deactivate"
+  | "force_reset"
+  | "persistent";
+
+export interface PageActivationDiagnostic {
+  pageId: string;
+  pageName?: string;
+  active: boolean;
+  appliedArtifactCount: number;
+  alwaysEmbedInSnippet?: boolean;
+  lastTransitionMode?: PageDeactivationMode;
+  isolationFallback?: "whole_experiment";
+  isolationFallbackExperimentId?: string;
+  triggerDetector?: "history" | "polling" | "dom";
+  triggerPollAttempts?: number;
+  triggerOutcome?: "activated" | "condition_failed" | "window_expired";
+  triggerElapsedMs?: number;
+}
+
 export interface SdkDiagnostics {
   /** Public diagnostics redact consent and tracking-gate internals unless SDK debug mode is enabled. */
   mode: "public" | "debug";
@@ -549,6 +605,7 @@ export interface SdkDiagnostics {
     personalizationStopAfterMatch?: boolean;
     value?: unknown;
   }>;
+  pageActivation: PageActivationDiagnostic[];
   experimentsLoaded: number;
   analyticsStarted: boolean;
   trackerStarted: boolean;
@@ -625,11 +682,20 @@ export interface SdkDiagnostics {
       mappedSignals: string[];
       gtagNormalized?: boolean;
     };
+    observerErrors: {
+      count: number;
+      last?: {
+        source: "route" | "data_layer" | "dom";
+        message: string;
+        at: number;
+      };
+    };
     lastShopifyAssignmentSync?: {
       at: number;
-      status: "pending" | "sent" | "skipped" | "failed";
+      status: "pending" | "sent" | "cookie_fallback" | "skipped" | "failed";
       reason?: string;
       assignmentCount: number;
+      truncatedAssignmentCount?: number;
     };
     lastShopifyCartSync?: {
       at: number;
@@ -789,7 +855,27 @@ export interface CommerceOfferExperiment {
   >;
 }
 
+export interface AggregateModeSettings {
+  enabled?: boolean;
+  constructions?: {
+    loggedInSegment?: boolean;
+  };
+}
+
 export interface InitConfig {
+  /** QA-only diagnostics for forced experiments omitted from the served config. */
+  qa_warnings?: Array<{
+    code: "forced_experiment_unavailable" | "edge_device_audience_unsupported";
+    experiment_id: string;
+    reason?: "archived" | "runtime_disabled" | "not_found" | "environment_mismatch";
+    /** Named audience that the edge runtime cannot reproduce. */
+    audience_name?: string;
+  }>;
+  /** Global program holdout. Missing or malformed values fail open. */
+  holdout_v1_enabled?: boolean;
+  holdout_pct?: number;
+  /** ISO timestamp for the reporting epoch that produced the holdout cohort. */
+  holdout_config_updated_at?: string | null;
   /** Provide experiments inline OR use shopId to auto-fetch from API. */
   experiments?: Experiment[];
   /** Request-scoped edge geography used for targeting. */
@@ -806,18 +892,29 @@ export interface InitConfig {
   };
   /** Shop ID – when provided (without experiments), the SDK fetches running experiments from the API. */
   shopId?: string;
+  /** Canonical storefront origin used to scope host-agnostic redirect source rules. */
+  storeOrigin?: string;
+  /** Registered public storefront origins accepted for host-agnostic redirect source rules. */
+  storeOrigins?: string[];
   /** Base URL for event tracking & config API (e.g. "https://events.drip-apex.com"). */
   endpoint?: string;
+  /** Prefer same-origin Shopify App Proxy delivery, with direct-worker fallback. */
+  proxyEventDelivery?: { enabled: boolean; path?: string };
+  assetFallback?: boolean;
   /** Optional endpoint for signed storefront audit snapshots. Defaults to Apex production. */
   auditEndpoint?: string;
   /** Versioned editor bundle URL emitted by the Apex snippet. */
   editorBundleUrl?: string;
+  /** Versioned replay recorder URL emitted by the Apex snippet. */
+  replayRecorderUrl?: string;
   ingestShopId?: string;
   ingestSignature?: string;
   attributes?: Record<string, unknown>;
   userId?: string;
   url?: string;
   autoTrack?: boolean;
+  /** Per-page storefront Core Web Vitals sample rate. Defaults to 0.1. */
+  storefrontVitalsSampleRate?: number;
   /** Persist fetched config in localStorage for faster repeat loads. Default: true. */
   configCache?: boolean;
   /** Fresh cache window in ms for local config cache. Default: 300000 (5m). */
@@ -890,6 +987,14 @@ export interface InitConfig {
   semanticTracking?: SemanticTrackingSettings;
   /** Server-authoritative runtime kill switch state. */
   runtimeControl?: RuntimeControlSettings;
+  /** Write assignment sync to a shared-domain cookie when Shopify's analytics bus is unavailable. Default: true. */
+  assignmentCookieSync?: boolean;
+  /** Legal-gated server-side aggregate-mode constructions. Missing values are off. */
+  aggregateMode?: AggregateModeSettings;
+  /** Selects whether the SDK or an external integration owns Shopify cart attribute writes. */
+  cartAttributeWrite?: "sdk" | "external";
+  /** Selects which assignment labels an external cart integration can read. */
+  cartAttributeScope?: "consented" | "all";
   /** Snippet compiler delivery state for SDK performance telemetry. */
   deliveryState?:
     | "no_visual_tests"
@@ -911,6 +1016,8 @@ export interface InitConfig {
     | "shopify_app_embed"
     | "legacy_shopify_redirect"
     | string;
+  /** Exact snippet URL used for a per-visitor debug-build handoff. */
+  snippetUrl?: string;
   /** Immutable SDK artifact version selected by the Worker. */
   sdkVersion?: string;
   /** Resolved SDK policy mode selected by the Worker. */
@@ -931,6 +1038,7 @@ export interface InitConfig {
     qa?: boolean;
     harness?: boolean;
     audit?: boolean;
+    debugLoader?: boolean;
   };
   /** Runtime kill-switches for staged rollout features. */
   perfFlags?: PerfFeatureFlags;
@@ -963,7 +1071,6 @@ export interface InitConfig {
    * Custom JS execution policy. Default: "hybrid".
    * - "strict": no custom JS execution in production.
    * - "hybrid": custom JS allowed with safety guards (sourceURL, error isolation).
-   * - "flex": unrestricted custom JS (legacy behavior).
    */
   customJsPolicy?: CustomJsPolicy;
 

package/src/wait.test.ts

@@ -93,4 +93,27 @@ describe("waitForElement", () => {
     vi.advanceTimersByTime(1001);
     expect(onMiss).not.toHaveBeenCalled();
   });
+
+  it("does not apply a pending-root match after its final owner tears down", async () => {
+    const { resetWaitEntriesForOwner, waitForElement } = await import("./wait");
+    const callback = vi.fn();
+    const node = {
+      nodeType: 1,
+      matches: vi.fn(() => {
+        resetWaitEntriesForOwner("page-a");
+        return true;
+      }),
+      querySelectorAll: vi.fn(() => []),
+    } as unknown as Element;
+
+    waitForElement(".late-node", callback, { ownerKeys: ["page-a"] });
+    observerCallback?.(
+      [{ type: "childList", addedNodes: [node] } as unknown as MutationRecord],
+      {} as MutationObserver,
+    );
+
+    await Promise.resolve();
+    expect(callback).not.toHaveBeenCalled();
+    expect(disconnect).toHaveBeenCalled();
+  });
 });

package/src/wait.ts

@@ -1,13 +1,22 @@
 import { Mutation } from "./types";
-import { applyTrackedMutation, isInsertAction, isInsertDuplicate, getMutationKey } from "./mutate";
+import { applyTrackedMutation, getMutationKey, rejectTrackedMutation } from "./mutate";
+import type { MutationJournalEntry } from "./mutate";
+import { extractCurrencyTokens, type CurrencyToken } from "./money";
+import { onShadowMutations, queryAllDeep } from "./shadow";
 
 type WaitEntry = {
+  seq: number;
+  artifactId: string;
+  epoch: number;
   selector: string;
   callback: (el: Element) => void;
   handled: WeakSet<Element>;
   matched: boolean;
   expiresAt: number;
   onMiss?: () => void;
+  ownerKeys: Set<string>;
+  requiresOwner: boolean;
+  state: "applied" | "invalidated";
 };
 
 const entries: WaitEntry[] = [];
@@ -16,6 +25,8 @@ let pending = false;
 const pendingRoots = new Set<ParentNode>();
 const DEFAULT_WAIT_TTL_MS = 30_000;
 let expiryTimer: ReturnType<typeof setTimeout> | null = null;
+let waitSequence = 0;
+let stopShadowListener: (() => void) | null = null;
 
 function isElement(node: Node): node is Element {
   return node.nodeType === Node.ELEMENT_NODE;
@@ -27,6 +38,7 @@ function hasQuerySelectorAll(node: ParentNode): node is ParentNode & { querySele
 
 function applyToEntry(entry: WaitEntry, element: Element): void {
   if (entry.expiresAt <= Date.now()) return;
+  if (entry.requiresOwner && entry.ownerKeys.size === 0) return;
   if (entry.handled.has(element)) return;
   entry.handled.add(element);
   entry.matched = true;
@@ -69,6 +81,8 @@ function pruneExpiredEntries(): void {
     pending = false;
     pendingRoots.clear();
     clearExpiryTimer();
+    stopShadowListener?.();
+    stopShadowListener = null;
   } else {
     scheduleExpiryPrune();
   }
@@ -116,7 +130,7 @@ function checkAllEntries(): void {
   const selectorMap = buildSelectorMap();
   for (const [selector, selectorEntries] of selectorMap) {
     try {
-      const elements = document.querySelectorAll(selector);
+      const elements = queryAllDeep(selector);
       elements.forEach((el) => {
         selectorEntries.forEach((entry) => applyToEntry(entry, el));
       });
@@ -177,17 +191,34 @@ function ensureObserver(): void {
     childList: true,
     subtree: true,
   });
+  stopShadowListener ??= onShadowMutations((records) => {
+    for (const record of records) {
+      if (record.type === "childList") {
+        record.addedNodes.forEach((node) => pendingRoots.add(node as ParentNode));
+      } else {
+        pendingRoots.add(record.target as ParentNode);
+      }
+    }
+    if (pendingRoots.size > 0) debouncedCheck();
+  });
 }
 
 export function waitForElement(
   selector: string,
   callback: (el: Element) => void,
-  options: { ttlMs?: number; onMiss?: () => void } = {},
+  options: {
+    ttlMs?: number;
+    onMiss?: () => void;
+    ownerKeys?: readonly string[];
+    ownerKeysSet?: Set<string>;
+    artifactId?: string;
+    epoch?: number;
+  } = {},
 ): void {
   const handled = new WeakSet<Element>();
   let matched = false;
   try {
-    const existing = document.querySelectorAll(selector);
+    const existing = queryAllDeep(selector);
     existing.forEach((el) => {
       handled.add(el);
       matched = true;
@@ -198,7 +229,21 @@ export function waitForElement(
     return;
   }
   const ttlMs = Math.max(1_000, Math.min(options.ttlMs ?? DEFAULT_WAIT_TTL_MS, 120_000));
-  entries.push({ selector, callback, handled, matched, expiresAt: Date.now() + ttlMs, onMiss: options.onMiss });
+  entries.push({
+    seq: ++waitSequence,
+    artifactId: options.artifactId ?? options.ownerKeys?.[0] ?? "wait:" + selector,
+    epoch: options.epoch ?? 0,
+    selector,
+    callback,
+    handled,
+    matched,
+    expiresAt: Date.now() + ttlMs,
+    onMiss: options.onMiss,
+    ownerKeys: options.ownerKeysSet ?? new Set(options.ownerKeys ?? []),
+    requiresOwner:
+      options.ownerKeysSet !== undefined || (options.ownerKeys?.length ?? 0) > 0,
+    state: "applied",
+  });
   scheduleExpiryPrune();
   ensureObserver();
 }
@@ -206,26 +251,97 @@ export function waitForElement(
 export function applyMutationWithWait(
   mutation: Mutation,
   index: number,
-  onApplied?: ((mutation: Mutation, element: Element, index: number) => void) | null,
+  onApplied?: ((mutation: Mutation, element: Element, index: number, journalSeq?: number) => void) | null,
   onMiss?: ((mutation: Mutation, index: number) => void) | null,
+  ownerKeys: readonly string[] = [],
+  artifactId?: string,
+  epoch = 0,
+  pricePreservation?: {
+    enabled: boolean;
+    onViolation: (input: { selector: string; originalPriceTokens: CurrencyToken[] }) => void;
+  },
 ): void {
+  const mutableOwnerKeys = new Set(ownerKeys);
   const key = getMutationKey(mutation, index);
+  let resolved = false;
   waitForElement(mutation.selector, (element) => {
-    if (isInsertAction(mutation.action)) {
-      if (isInsertDuplicate(element, key)) {
-        onApplied?.(mutation, element, index);
+    if (resolved) return;
+    const originalPrices = pricePreservation?.enabled &&
+        (mutation.action === "html" || mutation.action === "text" || mutation.action === "setText")
+      ? extractCurrencyTokens(element.textContent ?? "")
+      : [];
+    const originalHtml = originalPrices.length > 0 ? element.innerHTML : null;
+    let journalSeq: number | undefined;
+    let journalEntry: MutationJournalEntry | undefined;
+    applyTrackedMutation(
+      mutation,
+      element,
+      key,
+      Array.from(mutableOwnerKeys),
+      artifactId,
+      (entry) => { journalSeq = entry.seq; journalEntry = entry; },
+      epoch,
+    );
+    if (originalHtml !== null) {
+      const remaining = extractCurrencyTokens(element.textContent ?? "");
+      const preserved = originalPrices.every((token) => remaining.some((candidate) =>
+        candidate.symbol === token.symbol && candidate.cents === token.cents));
+      if (!preserved) {
+        rejectTrackedMutation(journalEntry, element, originalHtml);
+        pricePreservation?.onViolation({ selector: mutation.selector, originalPriceTokens: originalPrices });
+        resolved = true;
+        onMiss?.(mutation, index);
         return;
       }
-      applyTrackedMutation(mutation, element, key);
-    } else {
-      applyTrackedMutation(mutation, element, key);
     }
-    onApplied?.(mutation, element, index);
+    onApplied?.(mutation, element, index, journalSeq);
   }, {
     onMiss: () => onMiss?.(mutation, index),
+    ownerKeysSet: mutableOwnerKeys,
+    artifactId,
+    epoch,
   });
 }
 
+export function addWaitEntryOwners(
+  existingOwnerKeys: ReadonlySet<string>,
+  ownerKeys: readonly string[],
+  artifactId?: string,
+): void {
+  if (existingOwnerKeys.size === 0 || ownerKeys.length === 0) return;
+  for (const entry of entries) {
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (
+      !Array.from(existingOwnerKeys).some((ownerKey) =>
+        entry.ownerKeys.has(ownerKey)
+      )
+    ) continue;
+    ownerKeys.forEach((ownerKey) => entry.ownerKeys.add(ownerKey));
+  }
+}
+
+export function resetWaitEntriesForOwner(
+  ownerKey: string,
+  artifactId?: string,
+): void {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (!entry.ownerKeys.has(ownerKey)) continue;
+    entry.ownerKeys.delete(ownerKey);
+    if (entry.ownerKeys.size === 0) entries.splice(i, 1);
+  }
+  if (entries.length > 0) {
+    scheduleExpiryPrune();
+    return;
+  }
+  pending = false;
+  pendingRoots.clear();
+  observer?.disconnect();
+  observer = null;
+  clearExpiryTimer();
+}
+
 export function resetWaitEntries(): void {
   entries.length = 0;
   pending = false;

package/src/weekday-delivery.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __test } from "./index";
+import type { Experiment } from "./types";
+
+// Hermeticity: weekday tests pin the most recent UTC Monday at 12:00 instead
+// of a literal calendar date.
+const RECENT_MONDAY_NOON = (() => {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 6) % 7));
+  d.setUTCHours(12, 0, 0, 0);
+  return d;
+})();
+
+const excludedExperiment: Experiment = {
+  id: "weekday",
+  name: "Weekday test",
+  status: "running",
+  weekdaySchedule: {
+    excludedDays: ["monday"],
+    timezone: "UTC",
+  },
+  trafficAllocation: 1,
+  variations: [{
+    id: "variation",
+    weight: 1,
+    mutations: [{ action: "text", selector: "h1", text: "Variant" }],
+  }],
+};
+
+describe("SDK weekday delivery sites", () => {
+  afterEach(() => vi.useRealTimers());
+
+  it("does not collect anti-flicker selectors on an excluded day", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(RECENT_MONDAY_NOON));
+    expect(__test.collectScopedSelectors([excludedExperiment])).toEqual([]);
+  });
+
+  it("does not build critical-path work on an excluded day", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(RECENT_MONDAY_NOON));
+    const result = __test.buildCriticalPathAssignments(
+      [excludedExperiment],
+      [{
+        e: "weekday",
+        v: [{ id: "variation", w: 1, m: [["h1", "text", "Variant"]] }],
+      }],
+      { url: "https://shop.test/", attributes: {}, userId: "visitor" },
+    );
+    expect(result.assignments).toEqual([]);
+    expect(result.skippedDiagnostics[0]).toMatchObject({
+      reason: "excluded_weekday",
+      gates: [{ id: "weekday", label: "Weekday schedule", status: "failed" }],
+    });
+  });
+});