@drip-apex/sdk 0.1.0 → 0.2.0

package/dist/types/runtime-state.d.ts

@@ -0,0 +1,166 @@
+import { type StorefrontVitalsContext } from "./storefront-vitals";
+import { type ReplayController } from "./replay";
+import type { PerfFlagState } from "./runtime";
+import { Tracker } from "./track";
+import { ActivationMode, Assignment, ActivationDiagnostics, InitConfig, PageTargetingRule, PageActivationDiagnostic, PageDeactivationMode, PageTriggerMode, PlatformHint, RouterMode, TrackEvent, TrackingStart } from "./types";
+import type { HeatmapController, SemanticController, UrlDiffNeeds, PendingPerfEvent, ConfigSource, ResolvedRuntimeConfig, RouteDiagnostic, DataLayerDiagnostic, ShopifySyncDiagnostic, ShopifyAssignmentSyncDiagnostic, ExposureDestinationDiagnostic, PageRuleReconcileScope, RuntimeLoadDiagnostic, PageDetectorMode } from "./config-runtime";
+export type OrderIdentityPlatform = "shopify" | "shopware" | "woocommerce" | "centra" | "custom";
+export type SDKState = {
+    config: InitConfig | null;
+    userId: string | null;
+    tracker: Tracker | null;
+    assignments: Assignment[];
+    pageActivation: Map<string, PageActivationRuntimeState>;
+    stopObserver: (() => void) | null;
+    stopDomObserver: (() => void) | null;
+    stopHandover: (() => void) | null;
+    heatmapController: HeatmapController | null;
+    replayController: ReplayController | null;
+    replayStartPromise: Promise<void> | null;
+    replayGeneration: number;
+    semanticController: SemanticController | null;
+    forceMap: Record<string, string> | null;
+    forcedUnavailable: Array<{
+        experimentId: string;
+        reason: "archived" | "runtime_disabled" | "not_found" | "environment_mismatch" | "not_in_config";
+    }>;
+    edgeDeviceAudienceUnsupported: Array<{
+        experimentId: string;
+        audienceName: string;
+    }>;
+    analyticsStarted: boolean;
+    trackingStart: TrackingStart;
+    trackingIdleTimeoutMs: number;
+    consentRequired: boolean;
+    consentGranted: boolean;
+    consentModeEnabled: boolean;
+    trackingPrerequisiteMet: boolean;
+    variationPrerequisiteMet: boolean;
+    activationDiagnostics: ActivationDiagnostics;
+    trackingDisabledByDnt: boolean;
+    holdout: boolean;
+    analyticsTimeoutId: number | null;
+    analyticsIdleId: number | null;
+    qaMode: boolean;
+    qaSessionId: string;
+    screenshotMode: boolean;
+    platform: PlatformHint;
+    routerMode: RouterMode;
+    activationMode: ActivationMode;
+    perfFlags: PerfFlagState;
+    urlDiffNeeds: UrlDiffNeeds;
+    lastUrl: string;
+    lastAssignmentSignature: string;
+    wiredGoalKeys: Set<string>;
+    wiredGoalUrl: string | null;
+    pendingPerf: PendingPerfEvent | null;
+    configSource: ConfigSource;
+    runtimeConfig: ResolvedRuntimeConfig | null;
+    pageTriggerMode: PageTriggerMode;
+    stopSignalCaptures: (() => void) | null;
+    stopSurfaceSignals: (() => void) | null;
+    stopJsTriggerSignals: (() => void) | null;
+    stopDataLayerTriggers: (() => void) | null;
+    stopConsentListeners: (() => void) | null;
+    stopShopifyCartMutationSync: (() => void) | null;
+    lastRouteChange: RouteDiagnostic | null;
+    lastDataLayerTrigger: DataLayerDiagnostic | null;
+    observerErrors: {
+        count: number;
+        last?: {
+            source: "route" | "data_layer" | "dom";
+            message: string;
+            at: number;
+        };
+    };
+    deferredRouteReevaluationTimer: number | null;
+    lastShopifyAssignmentSync: ShopifyAssignmentSyncDiagnostic | null;
+    lastShopifyCartSync: ShopifySyncDiagnostic | null;
+    shopifyCartToken: string | null;
+    shopwareAttributionEnvelope: string | null;
+    exposureDestinationDiagnostics: ExposureDestinationDiagnostic[];
+    exposedAssignmentKeys: Set<string>;
+    mutationPendingAssignmentKeys: Set<string>;
+    contaminatedAssignmentKeys: Set<string>;
+    authorizedPriceAssignmentKeys: Set<string> | null;
+    authorizedShippingAssignmentKeys: Set<string> | null;
+    authorizedOffersAssignmentKeys: Set<string> | null;
+    initializingAssignments: boolean;
+    pendingInitialApply: Promise<void> | null;
+    queuedRecheck: {
+        reason: "url" | "dom" | "manual" | "prerequisite";
+        forceReapply: boolean;
+        pageRuleScope?: PageRuleReconcileScope;
+    } | null;
+    redirectNavigationPending: boolean;
+    routeAnalyticsGeneration: number;
+    /** Re-entrancy guard and unwind-drain flag for `reevaluateAssignments`. */
+    reconcileInProgress: boolean;
+    reconcilePending: boolean;
+    pendingDeliveryHealth: TrackEvent[];
+    load: RuntimeLoadDiagnostic;
+    orderIdentityInFlight: Set<string>;
+    orderIdentityDetectionUrl: string;
+    orderIdentityDetection: {
+        platform: OrderIdentityPlatform;
+        platformOrderId: string | null;
+        orderNumber: string | null;
+    } | null | undefined;
+    carryImportedAssignmentKeys: Set<string>;
+};
+export type QaAssistantRuntimeSnapshot = {
+    config: InitConfig | null;
+    assignments: Assignment[];
+    activationDiagnostics: ActivationDiagnostics;
+    pageActivation: PageActivationDiagnostic[];
+    goalScopeUrl: string | null;
+    forceMap: Record<string, string> | null;
+    forcedUnavailable: Array<{
+        experimentId: string;
+        reason: "archived" | "runtime_disabled" | "not_found" | "environment_mismatch" | "not_in_config";
+    }>;
+    edgeDeviceAudienceUnsupported: Array<{
+        experimentId: string;
+        audienceName: string;
+    }>;
+    platform: PlatformHint;
+    qaMode: boolean;
+    orderIdentity: {
+        platform: OrderIdentityPlatform;
+        platformOrderId: string | null;
+        orderNumber: string | null;
+    } | null;
+};
+export type PageActivationRuntimeState = {
+    active: boolean;
+    appliedKeys: Set<string>;
+    /** Goal-scope state only; never participates in render transitions. */
+    scopeOnly?: boolean;
+    configuredMode?: PageDeactivationMode;
+    lastTransitionMode?: PageDeactivationMode;
+    isolationFallback?: "whole_experiment";
+    isolationFallbackExperimentId?: string;
+    triggerDetector?: PageDetectorMode;
+    triggerPollAttempts?: number;
+    triggerOutcome?: "activated" | "condition_failed" | "window_expired";
+    triggerElapsedMs?: number;
+};
+export type PageRulePollController = {
+    intervalId: number;
+    startedAt: number;
+};
+export declare const runtimeSharedState: {
+    runtimeBootedTooLateForAntiFlicker: boolean | null;
+    stopEarlyReassert: (() => void) | null;
+    earlyReassertTeardownTimer: ReturnType<typeof setTimeout> | null;
+    storefrontVitalsContext: StorefrontVitalsContext | null;
+    initialPredecidedByExperiment: Map<string, string> | null;
+    shopifyCartSyncGeneration: number;
+    pageDetectorRules: Map<PageDetectorMode, PageTargetingRule[]>;
+    pageDetectorLastUrls: Map<string, string>;
+    pageRulePollControllers: Map<string, PageRulePollController>;
+    qaAssistantRuntimeListeners: Set<() => void>;
+    clearingQaForceFromRoute: boolean;
+    attributionLedger: Map<string, Assignment>;
+};
+export declare const state: SDKState;

package/dist/types/sanitize.d.ts

@@ -1,3 +1,4 @@
+export declare function isSafeMutationAttribute(name: string, value: string | null): boolean;
 /**
  * Lightweight HTML sanitizer using the browser's DOMParser.
  * Strips <script> tags, on* event handlers, and javascript: URLs.

package/dist/types/shadow.d.ts

@@ -0,0 +1,3 @@
+export declare function queryAllDeep(selector: string): Element[];
+export declare function shadowRootFor(element: Element): ShadowRoot | null;
+export declare function onShadowMutations(listener: (records: MutationRecord[], root: ShadowRoot) => void): () => void;

package/dist/types/shopify-cart.d.ts

@@ -3,9 +3,14 @@ export type CartAssignment = {
     variationId: string;
     assignmentEpoch?: number;
     commercePriceOnly?: boolean;
+    pageActive?: boolean;
 };
 export type CartAttributeSyncInput = {
     assignments: CartAssignment[];
+    /** Allows an explicit empty control stamp to clear prior treatment attributes. */
+    controlStamp?: boolean;
+    /** Writes only storefront identity without disturbing existing treatment attributes. */
+    identityOnly?: boolean;
     requiredAssignments?: CartAssignment[];
     visitorId: string;
     sessionId: string;
@@ -14,6 +19,8 @@ export type CartAttributeSyncInput = {
     ingestSignature?: string;
     url?: string;
     environment?: string;
+    platform?: string;
+    onAttributionEnvelope?: (envelope: string) => void;
     cartToken?: string;
     offersAuthorizationRevision?: number;
     offersExperimentIds?: string[];
@@ -30,6 +37,8 @@ export type CartAttributeSyncInput = {
     authorizePriceDisplayAssignments?: (assignments: CartAssignment[]) => void;
     authorizeShippingDisplayAssignments?: (assignments: CartAssignment[]) => void;
     authorizeOffersDisplayAssignments?: (assignments: CartAssignment[]) => void;
+    /** Receives the normalized Shopify cart token already observed by this sync. */
+    onCartToken?: (cartToken: string) => void;
     /** Receives the parsed /cart/update.js response body after a successful stamp write. */
     onCartSnapshot?: (cart: unknown) => void;
     exclusionGroupSelections?: Array<{
@@ -42,6 +51,18 @@ export type CartAttributeEntry = {
     key: string;
     value: string;
 };
+export type CartMetafieldInput = {
+    key: string;
+    type: string;
+    value: string;
+};
+export type CartMetafieldKeyInput = Pick<CartMetafieldInput, "key">;
+/** Every Shopify cart attribute key owned and replaced by Apex. */
+export declare const APEX_CART_ATTRIBUTE_KEYS: ReadonlySet<string>;
+/** Normalize Shopify metafield namespaces accepted by the Apex cart mirror. */
+export declare function normalizeCartMetafieldNamespace(namespace?: string): string;
+/** Return every Apex cart-metafield key missing from the supplied mirror. */
+export declare function getCartMetafieldStaleKeys(currentMetafields: readonly CartMetafieldKeyInput[], namespace?: string): string[];
 export type CartAttributeSyncResult = {
     status: "sent" | "skipped" | "failed";
     reason?: string;
@@ -50,7 +71,7 @@ export type CartAttributeSyncOptions = {
     /** Re-write after a real cart mutation even if this assignment was stamped earlier. */
     force?: boolean;
 };
-/** Prevent an obsolete authorization response from reaching the cart write. */
+/** Prevent an obsolete authorization response or pending request from reaching the cart. */
 export declare function invalidateShopifyCartAttributeSync(): void;
 export declare function cannotRequestRequiredCommerceAuthorization(input: CartAttributeSyncInput): boolean;
 export declare function isShopifyStorefront(): boolean;
@@ -58,5 +79,8 @@ export declare function isShopifyStorefront(): boolean;
 export declare function shopifyRoutesRoot(): string;
 export declare function shopifyCartPath(): string;
 export declare function syncShopifyCartAttributes(input: CartAttributeSyncInput, options?: CartAttributeSyncOptions): Promise<CartAttributeSyncResult>;
+export declare function mintShopwareAttributionEnvelope(input: CartAttributeSyncInput): Promise<void>;
 export declare function buildSignedCartAttributeEntries(input: CartAttributeSyncInput): Promise<CartAttributeEntry[]>;
 export declare function buildCartAttributeEntries(input: CartAttributeSyncInput, commerceAuthorization?: string | null): CartAttributeEntry[];
+/** Build a Storefront API cart-metafield mirror of the canonical attribution stamp. */
+export declare function buildCartMetafieldInputs(input: CartAttributeSyncInput, namespace?: string): CartMetafieldInput[];

package/dist/types/storefront-vitals.d.ts

@@ -0,0 +1,24 @@
+export type StorefrontVitalsContext = {
+    endpoint: string;
+    proxyEventDelivery?: {
+        enabled: boolean;
+        path?: string;
+    };
+    shopId: string;
+    ingestShopId?: string;
+    ingestSignature?: string;
+    visitorId?: string;
+    sampleRate?: number;
+    experimentActive: boolean;
+    sdkBootToInitMs?: number;
+    getAntiFlickerInsertedToRevealMs?: () => number | undefined;
+    sdkInitStartToAssignmentReadyMs?: number;
+};
+export type VitalRating = "good" | "needs-improvement" | "poor";
+declare const RATING_THRESHOLDS: Record<string, [number, number]>;
+export declare function rateVital(metric: keyof typeof RATING_THRESHOLDS, value: number | undefined): VitalRating | undefined;
+/** Starts one dependency-free, observer-only storefront vitals sample. */
+export declare function startStorefrontVitals(context: StorefrontVitalsContext, random?: () => number): void;
+export declare function stopStorefrontVitals(): void;
+export declare function resetStorefrontVitalsForTest(): void;
+export {};

package/dist/types/targeting-diagnostics.d.ts

@@ -2,4 +2,5 @@ import type { Targeting, TargetingDiagnostics } from "./types";
 export declare function evaluateTargetingGatesWithConditionDiagnostics(targeting: Targeting | undefined, ctx: {
     url: string;
     attributes: Record<string, unknown>;
+    hostAgnosticIncludeOrigin?: string | string[];
 }): TargetingDiagnostics;

package/dist/types/targeting.d.ts

@@ -1,7 +1,9 @@
 import { AttributeRule, ActivationGateDiagnostic, Experiment, PageTargetingRule, SegmentCondition, Targeting, TargetingDiagnostics, UrlRule } from "./types";
-export declare function evalUrlRule(url: string, rule: UrlRule): boolean;
+import { evaluateUrlRule } from "@drip/event-schema/targeting-core";
+export declare const evalUrlRule: typeof evaluateUrlRule;
 export declare function normalizeRuntimeUrlRules(targeting: Targeting | undefined): UrlRule[];
-export declare function matchUrlRules(url: string, rules: UrlRule[]): boolean;
+export declare function matchUrlRules(url: string, rules: UrlRule[], hostAgnosticIncludeOrigin?: string | string[]): boolean;
+export declare function evalUrlRuleForIncludeOrigin(url: string, rule: UrlRule, origins?: string | string[]): boolean;
 type BooleanDiagnosticResult = {
     matched: boolean;
     reason?: string;
@@ -14,7 +16,16 @@ export declare function evaluatePageAdvancedConditionResult(rule: PageTargetingR
 export declare function pageManualTriggerMatches(rule: PageTargetingRule, ctx: {
     attributes: Record<string, unknown>;
 }): boolean;
+export declare function matchPageTargetingRule(rule: PageTargetingRule, ctx: {
+    url: string;
+    attributes: Record<string, unknown>;
+}): boolean;
+export declare function matchedPageRuleIds(rules: PageTargetingRule[], ctx: {
+    url: string;
+    attributes: Record<string, unknown>;
+}): Set<string>;
 export declare function matchAttributeRule(attrs: Record<string, unknown>, rule: AttributeRule): boolean;
+export declare function readShopifySignal(signal: string): unknown;
 export declare function buildTargetingAttributes(baseAttributes?: Record<string, unknown>, currentUrl?: string, options?: {
     persistSignals?: boolean;
 }): Record<string, unknown>;
@@ -34,15 +45,18 @@ export declare function matchSegmentConditionValues(condition: SegmentCondition,
 export declare function matchesTargeting(targeting: Targeting | undefined, ctx: {
     url: string;
     attributes: Record<string, unknown>;
+    hostAgnosticIncludeOrigin?: string | string[];
 }): boolean;
 export declare function targetingHasJsTriggers(experiments: Experiment[]): boolean;
 export declare function evaluateTargetingGatesDetailed(targeting: Targeting | undefined, ctx: {
     url: string;
     attributes: Record<string, unknown>;
+    hostAgnosticIncludeOrigin?: string | string[];
 }): TargetingDiagnostics;
 export declare function evaluateTargetingGates(targeting: Targeting | undefined, ctx: {
     url: string;
     attributes: Record<string, unknown>;
+    hostAgnosticIncludeOrigin?: string | string[];
 }): {
     matched: boolean;
     gates: ActivationGateDiagnostic[];

package/dist/types/track.d.ts

@@ -1,6 +1,11 @@
 import { TrackEvent } from "./types";
 type TrackerOptions = {
     endpoint: string;
+    proxyEventDelivery?: {
+        enabled: boolean;
+        path?: string;
+    };
+    assetFallback?: boolean;
     shopId?: string;
     ingestShopId?: string;
     ingestSignature?: string;
@@ -20,9 +25,16 @@ type TrackerOptions = {
     qaSessionId?: string;
     /** Active Apex environment stamped onto every outgoing event. */
     environment?: string;
+    /** Global cohort stamped on every event while program holdout is enabled. */
+    cohort?: "holdout" | "active";
+    /** Reporting epoch of the configuration that produced the global cohort. */
+    holdoutConfigEpoch?: number;
 };
+export declare function getOrCreateSessionId(): string;
+export declare function createEventId(): string;
 export declare class Tracker {
     private endpoint;
+    private proxyEndpoint;
     private shopId;
     private ingestShopId;
     private ingestSignature;
@@ -44,6 +56,9 @@ export declare class Tracker {
     private qaMode;
     private qaSessionId;
     private environment;
+    private cohort;
+    private holdoutConfigEpoch;
+    private assetFallback;
     private pagehideHandler;
     private beforeUnloadHandler;
     private pageshowHandler;
@@ -52,7 +67,6 @@ export declare class Tracker {
     private pageLifecycleFlushed;
     private pageTeardownStarted;
     constructor(options: TrackerOptions);
-    private getOrCreateSessionId;
     /** Public accessor for the session ID (used by the Shopify pixel bridge). */
     getSessionId(): string;
     start(): void;