@drip-apex/sdk 0.1.0 → 0.2.0

package/dist/types/types.d.ts

@@ -20,7 +20,7 @@ export interface UrlRule {
 }
 export interface AttributeRule {
     attribute: string;
-    operator: "equals" | "contains" | "exists" | "in";
+    operator: "equals" | "contains" | "exists" | "in" | "not_in";
     value?: string | string[];
 }
 export type SegmentConditionOperator = "equals" | "not_equals" | "contains" | "not_contains" | "starts_with" | "ends_with" | "is_set" | "is_empty" | "in" | "not_in" | "matches_wildcard" | "matches_regex" | "greater_than" | "greater_than_or_equal" | "less_than" | "less_than_or_equal";
@@ -61,7 +61,6 @@ export interface PageTargetingRule {
     advancedCondition?: {
         code?: string;
         description?: string;
-        pollOnRules?: boolean;
     } | null;
     trigger?: {
         mode?: "immediate" | "history" | "polling" | "dom" | "manual-callback" | "manual-api";
@@ -90,6 +89,8 @@ export interface Targeting {
     segmentRules?: SegmentTargetingRule[];
     lifecycle?: {
         mode?: "reset" | "deactivate" | "force_reset" | "persistent";
+        explicit?: boolean;
+        source?: "author" | "page";
     };
 }
 export interface CaptureRule {
@@ -102,11 +103,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;
@@ -136,11 +140,20 @@ export interface SnippetDeliveryManifest {
     deliveryState?: "no_visual_tests" | "non_critical_visual" | "critical_visual" | "edge_managed" | string;
     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;
@@ -150,6 +163,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 {
     token?: string;
@@ -163,7 +180,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;
@@ -177,6 +201,10 @@ export interface Experiment {
         moves?: boolean;
         sampleRate?: number;
     };
+    replayCapture?: {
+        enabled?: boolean;
+        sampleRate?: number;
+    };
     variations: Variation[];
     hashAttribute?: string;
     goals?: Goal[];
@@ -215,6 +243,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;
@@ -231,18 +263,20 @@ export interface Assignment {
     externalJsUrl?: string;
     harnessSession?: HarnessSessionInfo;
     isControl: boolean;
+    redirectUrl?: string;
+    artifactSource?: string;
     hashValue: string;
     assignmentEpoch?: number;
 }
 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 {
     showVariationsRule?: string;
@@ -250,7 +284,7 @@ export interface ProjectPrerequisites {
 }
 export interface ConsentModeSettings {
     enabled?: boolean;
-    provider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes";
+    provider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes" | "cookiescript";
     getter?: string;
     requiredGroup?: string;
 }
@@ -259,6 +293,7 @@ export interface DebugSettings {
     restrictMode?: "off" | "query_param" | "user_ids" | "always";
     queryParam?: string;
     token?: string;
+    tokenRequired?: boolean;
     allowedUserIds?: string[];
     persist?: boolean;
     disableCache?: boolean;
@@ -273,11 +308,14 @@ 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 {
     domains?: string[];
@@ -435,6 +473,21 @@ 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";
@@ -457,6 +510,7 @@ export interface SdkDiagnostics {
         personalizationStopAfterMatch?: boolean;
         value?: unknown;
     }>;
+    pageActivation: PageActivationDiagnostic[];
     experimentsLoaded: number;
     analyticsStarted: boolean;
     trackerStarted: boolean;
@@ -527,11 +581,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;
@@ -679,7 +742,26 @@ export interface CommerceOfferExperiment {
         control: true;
     } | Record<string, unknown>>;
 }
+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. */
@@ -698,18 +780,32 @@ 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). */
@@ -780,12 +876,22 @@ 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" | "non_critical_visual" | "critical_visual" | "edge_managed" | string;
     /** Worker/cache source label for SDK performance telemetry. */
     scriptCacheSource?: "edge" | "kv" | "origin" | "precompile" | "precompiled" | string;
     /** Install surface that emitted this script. */
     installSurface?: "direct_script" | "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. */
@@ -806,6 +912,7 @@ export interface InitConfig {
         qa?: boolean;
         harness?: boolean;
         audit?: boolean;
+        debugLoader?: boolean;
     };
     /** Runtime kill-switches for staged rollout features. */
     perfFlags?: PerfFeatureFlags;
@@ -833,7 +940,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;
     /** If true, analytics/goal tracking starts only after consent is granted. */

package/dist/types/wait.d.ts

@@ -1,7 +1,20 @@
 import { Mutation } from "./types";
+import { type CurrencyToken } from "./money";
 export declare function waitForElement(selector: string, callback: (el: Element) => void, options?: {
     ttlMs?: number;
     onMiss?: () => void;
+    ownerKeys?: readonly string[];
+    ownerKeysSet?: Set<string>;
+    artifactId?: string;
+    epoch?: number;
 }): void;
-export declare function applyMutationWithWait(mutation: Mutation, index: number, onApplied?: ((mutation: Mutation, element: Element, index: number) => void) | null, onMiss?: ((mutation: Mutation, index: number) => void) | null): void;
+export declare function applyMutationWithWait(mutation: Mutation, index: number, onApplied?: ((mutation: Mutation, element: Element, index: number, journalSeq?: number) => void) | null, onMiss?: ((mutation: Mutation, index: number) => void) | null, ownerKeys?: readonly string[], artifactId?: string, epoch?: number, pricePreservation?: {
+    enabled: boolean;
+    onViolation: (input: {
+        selector: string;
+        originalPriceTokens: CurrencyToken[];
+    }) => void;
+}): void;
+export declare function addWaitEntryOwners(existingOwnerKeys: ReadonlySet<string>, ownerKeys: readonly string[], artifactId?: string): void;
+export declare function resetWaitEntriesForOwner(ownerKey: string, artifactId?: string): void;
 export declare function resetWaitEntries(): void;

package/dist/types/weekday-schedule.d.ts

@@ -0,0 +1,3 @@
+export { isWeekdayExcluded, resetWeekdayScheduleWarningsForTests, WEEKDAYS, } from "@drip/shared-runtime/weekday-schedule";
+export type { Weekday, WeekdaySchedule, } from "@drip/shared-runtime/weekday-schedule";
+export declare function weekdayScheduleBlocksDelivery(schedule: unknown, now: Date): boolean;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@drip-apex/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
-  "main": "dist/drip.js",
+  "main": "./dist/drip.cjs",
   "types": "dist/types/index.d.ts",
   "publishConfig": {
     "access": "public"
@@ -10,15 +10,21 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "default": "./dist/drip.js"
+      "import": "./dist/drip.mjs",
+      "require": "./dist/drip.cjs",
+      "default": "./dist/drip.mjs"
     },
     "./define": {
       "types": "./dist/types/define.d.ts",
-      "default": "./src/define.ts"
+      "import": "./dist/define.mjs",
+      "require": "./dist/define.cjs",
+      "default": "./dist/define.mjs"
     },
     "./flags": {
       "types": "./dist/types/flags.d.ts",
-      "default": "./src/flags.ts"
+      "import": "./dist/flags.mjs",
+      "require": "./dist/flags.cjs",
+      "default": "./dist/flags.mjs"
     },
     "./react": {
       "types": "./dist/types/react/index.d.ts",
@@ -37,7 +43,7 @@
   "scripts": {
     "build": "node build.mjs && npm run build:types",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly --outDir dist/types",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "deploy:pages": "npm run build && ../worker/node_modules/.bin/wrangler pages deploy dist --project-name drip-sdk",
     "deploy:pages:staging": "npm run build && ../worker/node_modules/.bin/wrangler pages deploy dist --project-name ${SDK_PAGES_PROJECT_STAGING:-drip-sdk-staging}",
     "test": "vitest run && npm run build && node --test bundle-report.test.mjs package-entry.test.mjs",
@@ -53,15 +59,18 @@
     }
   },
   "devDependencies": {
-    "@testing-library/react": "^16.3.1",
     "@drip/event-schema": "file:../event-schema",
+    "@drip/shared-runtime": "file:../shared-runtime",
+    "@testing-library/react": "^16.3.1",
     "@types/react": "^19.2.14",
     "esbuild": "0.28.1",
+    "fflate": "0.8.2",
     "jsdom": "^27.3.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
+    "rrweb": "2.1.1",
     "terser": "5.48.0",
-    "typescript": "^5.6.3",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.6"
   },
   "overrides": {