@drip-apex/sdk 0.1.0

package/src/types.ts

@@ -0,0 +1,991 @@
+export type MutationAction =
+  | "html"
+  | "text"
+  | "setText"
+  | "attribute"
+  | "style"
+  | "setStyle"
+  | "remove"
+  | "insertBefore"
+  | "insertAfter";
+
+export interface Mutation {
+  selector: string;
+  action: MutationAction;
+  html?: string;
+  text?: string;
+  attribute?: { name: string; value: string | null };
+  attributes?: Record<string, string | null>;
+  styles?: Record<string, string>;
+}
+
+export interface UrlRule {
+  type: "regex" | "simple";
+  pattern: string;
+  include?: boolean;
+  matchType?: "exact" | "contains" | "wildcard" | "regex";
+  match_type?: "exact" | "contains" | "wildcard" | "regex";
+}
+
+export interface AttributeRule {
+  attribute: string;
+  operator: "equals" | "contains" | "exists" | "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";
+
+export type SegmentSignal = string;
+
+export type SegmentJsTriggerMode = "predicate" | "activate";
+
+export interface SegmentJsTrigger {
+  code: string;
+  description?: string;
+  mode?: SegmentJsTriggerMode;
+  resetCode?: string;
+}
+
+export interface SegmentCondition {
+  signal: SegmentSignal;
+  operator: SegmentConditionOperator;
+  value?: string | number | boolean | string[];
+  js?: SegmentJsTrigger;
+}
+
+export interface SegmentRules {
+  version: 1;
+  operator: "and" | "or";
+  conditions: SegmentCondition[];
+  groups?: SegmentCondition[][];
+}
+
+export interface SegmentTargetingRule {
+  id: string;
+  name?: string;
+  type?: string;
+  include?: boolean;
+  rules: SegmentRules;
+}
+
+export interface PageTargetingRule {
+  id: string;
+  name?: string;
+  include?: boolean;
+  disabled?: boolean;
+  includeRules?: UrlRule[];
+  excludeRules?: UrlRule[];
+  advancedCondition?: {
+    code?: string;
+    description?: string;
+    pollOnRules?: boolean;
+  } | null;
+  trigger?: {
+    mode?:
+      | "immediate"
+      | "history"
+      | "polling"
+      | "dom"
+      | "manual-callback"
+      | "manual-api";
+    pollOnRules?: boolean;
+    disabled?: boolean;
+    alwaysEmbedInSnippet?: boolean;
+    deactivationMode?: "reset" | "deactivate" | "force-reset" | "persistent";
+    triggerJs?: string;
+    apiName?: string;
+    signal?: string;
+  };
+}
+
+export interface Targeting {
+  deviceType?: "all" | "desktop" | "mobile" | "tablet";
+  url?: UrlRule[];
+  attributes?: AttributeRule[];
+  pages?: Array<{
+    id: string;
+    include?: boolean;
+  }>;
+  pageRules?: PageTargetingRule[];
+  segments?: Array<{
+    id: string;
+    include?: boolean;
+  }>;
+  segmentRules?: SegmentTargetingRule[];
+  lifecycle?: {
+    mode?: "reset" | "deactivate" | "force_reset" | "persistent";
+  };
+}
+
+export interface CaptureRule {
+  /** Output key in the event data (e.g. "price", "product_id") */
+  property: string;
+  /** Where to read the value from */
+  source: "attribute" | "textContent" | "dataset";
+  /** Attribute name when source is "attribute" or "dataset" */
+  attribute?: string;
+}
+
+export interface Goal {
+  id: 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;
+  /** Custom analytics event name that should count as this goal. */
+  eventName?: string;
+  countOnce?: boolean;
+  /** Value capture rules — extract element attribute values on goal fire */
+  capture?: CaptureRule[];
+}
+
+export interface SnippetDeliveryUrlRule {
+  type: "simple" | "regex";
+  pattern: string;
+  include?: boolean;
+}
+
+export type SnippetCriticalMutation = [string, MutationAction, unknown?];
+
+export interface SnippetCriticalMutationPlanVariation {
+  id: string;
+  w: number;
+  c?: 1;
+  m: SnippetCriticalMutation[];
+}
+
+export interface SnippetCriticalMutationPlanItem {
+  e: string;
+  r: SnippetDeliveryUrlRule[];
+  v: SnippetCriticalMutationPlanVariation[];
+}
+
+export interface SnippetDeliveryManifest {
+  version?: 1;
+  revision?: number;
+  deliveryState?:
+    | "no_visual_tests"
+    | "non_critical_visual"
+    | "critical_visual"
+    | "edge_managed"
+    | string;
+  criticalMutationPlan?: SnippetCriticalMutationPlanItem[];
+}
+
+export interface Variation {
+  id: string;
+  name?: string;
+  weight: number;
+  mutations: Mutation[];
+  value?: unknown;
+  css?: string;
+  js?: string;
+  resetJs?: string;
+  antiFlickerSelectors?: string[];
+  externalCssUrl?: string;
+  externalJsUrl?: string;
+  harnessSession?: HarnessSessionInfo;
+  isControl?: boolean;
+}
+
+export interface HarnessSessionInfo {
+  token?: string;
+  version?: number;
+  expiresAt?: string;
+  manifestUrl?: string;
+  pollIntervalMs?: number;
+}
+
+export interface Experiment {
+  id: string;
+  kind?: "experiment" | "feature_flag" | "personalization";
+  name?: string;
+  status?: string;
+  targeting?: Targeting;
+  trafficAllocation?: number;
+  assignmentEpoch?: number;
+  assignmentEpochStartedAt?: string | null;
+  css?: string;
+  js?: string;
+  resetJs?: string;
+  behaviorCapture?: {
+    enabled?: boolean;
+    clicks?: boolean;
+    scrolls?: boolean;
+    moves?: boolean;
+    sampleRate?: number;
+  };
+  variations: Variation[];
+  hashAttribute?: string;
+  goals?: Goal[];
+  featureFlag?: {
+    id?: string;
+    key: string;
+    sourceExperimentId?: string | null;
+    sourceVariationId?: string | null;
+  };
+  personalization?: {
+    id?: string;
+    key: string;
+    ruleId?: string | null;
+    experienceId?: string | null;
+    surface?: string;
+    templateKey?: string | null;
+    priority?: number;
+    stopAfterMatch?: boolean;
+  };
+}
+
+/** A single experiment's membership + priority share inside an exclusion group. */
+export interface ExclusionGroupMemberConfig {
+  experimentId: string;
+  /** Fractional priority weight used to pick the winner when members overlap (0..1). */
+  share: number;
+}
+
+/** Server-authored group that resolves only experiments that overlap for a visitor. */
+export interface ExclusionGroupConfig {
+  id: string;
+  name?: string;
+  /** Bumping the epoch resets group-sticky selections. */
+  epoch?: number;
+  members: ExclusionGroupMemberConfig[];
+}
+
+export interface Assignment {
+  experimentId: string;
+  experimentName?: string;
+  variationId: string;
+  index: number;
+  mutations: Mutation[];
+  value?: unknown;
+  featureFlag?: Experiment["featureFlag"];
+  personalization?: Experiment["personalization"];
+  kind?: Experiment["kind"];
+  experimentCss?: string;
+  experimentJs?: string;
+  experimentResetJs?: string;
+  css?: string;
+  js?: string;
+  resetJs?: string;
+  externalCssUrl?: string;
+  externalJsUrl?: string;
+  harnessSession?: HarnessSessionInfo;
+  isControl: boolean;
+  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 PlatformHint = "auto" | "shopify" | "spa" | "shopware";
+export type RouterMode = "auto" | "history" | "navigation" | "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 PerfFeatureFlags = Partial<Record<PerfFeatureFlag, boolean>>;
+
+export interface ProjectPrerequisites {
+  showVariationsRule?: string;
+  startTrackingRule?: string;
+}
+
+export interface ConsentModeSettings {
+  enabled?: boolean;
+  provider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes";
+  getter?: string;
+  requiredGroup?: string;
+}
+
+export interface DebugSettings {
+  enabled?: boolean;
+  restrictMode?: "off" | "query_param" | "user_ids" | "always";
+  queryParam?: string;
+  token?: string;
+  allowedUserIds?: string[];
+  persist?: boolean;
+  disableCache?: boolean;
+  active?: boolean;
+  expiresAt?: string | null;
+}
+
+export interface SpaSettings {
+  routerMode?: RouterMode;
+  activationMode?: ActivationMode;
+  reinitOnly?: boolean;
+  /** Re-assert mutations after SPA DOM changes. Defaults on for url_change, dom_change, and platformHint: "spa"; set false to opt out. */
+  domChangeTrigger?: boolean;
+  debounceMs?: number;
+  allowIframes?: boolean;
+  applyTiming?: "immediate" | "after_hydration";
+  hydrationTimeoutMs?: number;
+}
+
+export interface PageTriggerSettings {
+  defaultMode?: PageTriggerMode;
+}
+
+export interface ExternalTrackingSettings {
+  domains?: string[];
+  handoverQueryParam?: string;
+  handoverTtlSeconds?: number;
+  handoverMintTimeoutMs?: number;
+  signed?: boolean;
+}
+
+export interface ProjectCodeSettings {
+  enabled?: boolean;
+  css?: string;
+  helperJs?: string;
+  js?: string;
+}
+
+export interface DataLayerSignalMapping {
+  from: string;
+  to: string;
+  valueType?: RuntimeSignalDefinition["valueType"];
+  ttlDays?: number;
+  persist?: boolean;
+}
+
+export interface DataLayerRevenuePropertyMapping {
+  from: string;
+  to: string;
+  valueType?: RuntimeSignalDefinition["valueType"];
+}
+
+export interface DataLayerRevenueTrackingSettings {
+  enabled?: boolean;
+  revenueFrom?: string;
+  orderIdFrom?: string;
+  currencyFrom?: string;
+  costFrom?: string;
+  profitFrom?: string;
+  properties?: DataLayerRevenuePropertyMapping[];
+}
+
+export interface DataLayerTriggerSettings {
+  enabled?: boolean;
+  dataLayerName?: string;
+  eventName: string;
+  reEvaluate?: boolean;
+  trackPageview?: boolean;
+  trackEventName?: string;
+  trackRevenue?: DataLayerRevenueTrackingSettings;
+  mappings?: DataLayerSignalMapping[];
+}
+
+export interface ExposureDataLayerDestination {
+  enabled?: boolean;
+  dataLayerName?: string;
+  eventName?: string;
+  includeMetadata?: boolean;
+}
+
+export interface ExposureHotjarDestination {
+  enabled?: boolean;
+  mode?: "identify" | "event";
+  eventName?: string;
+}
+
+export interface ExposureClarityDestination {
+  enabled?: boolean;
+  /** "set" writes one custom tag per experiment (default); "event" fires a named event; "both" does both. */
+  mode?: "set" | "event" | "both";
+  /** Prefix for the custom tag key. Default "apex ". */
+  tagPrefix?: string;
+  eventName?: string;
+  /** When true, calls clarity("upgrade", ...) once per page so experiment sessions beat Clarity's recording sampling. */
+  upgrade?: boolean;
+}
+
+export interface ExposureContentsquareDestination {
+  enabled?: boolean;
+  /** Prefix for the dynamic variable key. Default "apex ". */
+  keyPrefix?: string;
+}
+
+export interface ExposurePostHogDestination {
+  enabled?: boolean;
+  /** "capture" fires an event per exposure; "register" sets super properties; "both" does both. */
+  mode?: "capture" | "register" | "both";
+  eventName?: string;
+}
+
+export interface ExposureQueueDestination {
+  enabled?: boolean;
+  globalName: string;
+  method?: string;
+  eventName?: string;
+}
+
+export interface ExposureDestinationsSettings {
+  dataLayer?: ExposureDataLayerDestination;
+  hotjar?: ExposureHotjarDestination;
+  clarity?: ExposureClarityDestination;
+  contentsquare?: ExposureContentsquareDestination;
+  posthog?: ExposurePostHogDestination;
+  queues?: ExposureQueueDestination[];
+}
+
+export interface RuntimeEnvironmentSettings {
+  activeKey?: string;
+  items?: Array<{
+    key: string;
+    name: string;
+    isDefault?: boolean;
+    subSnippetEnabled?: boolean;
+  }>;
+}
+
+export interface BucketingCleanupSettings {
+  enabled?: boolean;
+  retentionDays?: number;
+}
+
+export interface DataProtectionSettings {
+  storageMode?: "localStorage" | "sessionStorage" | "cookie" | "memory";
+  encodeStorageValues?: boolean;
+  respectDoNotTrack?: boolean;
+  cookieDomain?: string;
+}
+
+export interface RuntimeControlSettings {
+  disabled?: boolean;
+  reason?: string;
+  disabledAt?: string | null;
+}
+
+export type ActivationGateStatus = "passed" | "failed" | "skipped";
+
+export interface ActivationGateDiagnostic {
+  id: string;
+  label: string;
+  status: ActivationGateStatus;
+  reason?: string;
+  detail?: Record<string, unknown>;
+}
+
+export interface ConditionDiagnostic {
+  id: string;
+  label: string;
+  status: ActivationGateStatus;
+  reason?: string;
+  operator?: string;
+  signal?: string;
+  expected?: unknown;
+  actual?: unknown;
+  source?: string;
+  sourceType?: "js" | "url" | "attribute" | "page_rule" | "segment";
+}
+
+export interface TargetingDiagnostics {
+  matched: boolean;
+  gates: ActivationGateDiagnostic[];
+  conditions: ConditionDiagnostic[];
+}
+
+export interface ExperimentActivationDiagnostic {
+  experimentId: string;
+  experimentName?: string;
+  status: ActivationGateStatus;
+  reason?: string;
+  assignedVariationId?: string;
+  assignedVariationIndex?: number;
+  forced?: boolean;
+  gates: ActivationGateDiagnostic[];
+  targetingConditions?: ConditionDiagnostic[];
+}
+
+export interface ActivationDiagnostics {
+  project: {
+    gates: ActivationGateDiagnostic[];
+  };
+  experiments: ExperimentActivationDiagnostic[];
+}
+
+export interface SdkDiagnostics {
+  /** Public diagnostics redact consent and tracking-gate internals unless SDK debug mode is enabled. */
+  mode: "public" | "debug";
+  initialized: boolean;
+  shopId: string | null;
+  userIdPresent: boolean;
+  assignments: Array<{
+    experimentId: string;
+    variationId: string;
+    kind: Experiment["kind"];
+    isControl: boolean;
+    mutationCount: number;
+    featureFlagKey?: string;
+    personalizationKey?: string;
+    personalizationRuleId?: string | null;
+    personalizationExperienceId?: string | null;
+    personalizationSurface?: string;
+    personalizationTemplateKey?: string | null;
+    personalizationPriority?: number;
+    personalizationStopAfterMatch?: boolean;
+    value?: unknown;
+  }>;
+  experimentsLoaded: number;
+  analyticsStarted: boolean;
+  trackerStarted: boolean;
+  activation: ActivationDiagnostics;
+  trackingBlocked?: boolean;
+  trackingDisabledByDnt?: boolean;
+  trackingPrerequisiteMet?: boolean;
+  consentRequired?: boolean;
+  consentGranted?: boolean;
+  consentModeEnabled?: boolean;
+  qaMode: boolean;
+  qaSessionId: string;
+  screenshotMode: boolean;
+  configSource: "inline" | "cache" | "network" | "none";
+  load: {
+    stage: string;
+    startedAt?: number;
+    updatedAt?: number;
+    configFetchStartedAt?: number;
+    configFetchCompletedAt?: number;
+    configFetchMs?: number;
+    configFetchAttempts?: number;
+    configFetchStatus?:
+      | "idle"
+      | "loading"
+      | "slow"
+      | "ok"
+      | "failed"
+      | "timeout";
+    configFetchStatusCode?: number;
+    configFetchError?: string;
+    assignmentReadyAt?: number;
+    assignmentReadyMs?: number;
+    firstMutationAt?: number;
+    revealAt?: number;
+    pendingMutations?: number;
+    appliedMutations?: number;
+    missedMutations?: number;
+  };
+  platform: PlatformHint;
+  routerMode: RouterMode;
+  activationMode: ActivationMode;
+  storage: {
+    mode: DataProtectionSettings["storageMode"];
+    localStorageAvailable: boolean;
+    sessionStorageAvailable: boolean;
+    cookiesEnabled: boolean;
+  };
+  runtime: {
+    antiFlickerMode?: AntiFlickerMode;
+    antiFlickerTimeoutMs?: number;
+    trackingStart?: TrackingStart;
+    pageTriggerMode?: PageTriggerMode;
+    customJsPolicy?: CustomJsPolicy;
+    externalHandoverDomains: string[];
+    handoverQueryParam: string;
+    handoverMintTimeoutMs?: number;
+    runtimeDisabled?: boolean;
+    runtimeDisabledAt?: string | null;
+  };
+  spa: {
+    lastUrl: string;
+    lastRouteChange?: {
+      previousUrl: string;
+      nextUrl: string;
+      reason: string;
+      at: number;
+      reEvaluated: boolean;
+    };
+    lastDataLayerTrigger?: {
+      eventName: string;
+      dataLayerName: string;
+      at: number;
+      mappedSignals: string[];
+      gtagNormalized?: boolean;
+    };
+    lastShopifyAssignmentSync?: {
+      at: number;
+      status: "pending" | "sent" | "skipped" | "failed";
+      reason?: string;
+      assignmentCount: number;
+    };
+    lastShopifyCartSync?: {
+      at: number;
+      status: "pending" | "sent" | "skipped" | "failed";
+      reason?: string;
+      assignmentCount: number;
+    };
+  };
+  signals: {
+    values: Record<string, unknown>;
+    sources: Record<string, string>;
+  };
+  integrations: {
+    exposureDestinations: Array<{
+      type: string;
+      status: "sent" | "skipped" | "failed";
+      at: number;
+      reason?: string;
+    }>;
+  };
+}
+
+export interface ConfigProfile {
+  platform: PlatformHint;
+  version: 1;
+}
+
+export type SignalCaptureMode =
+  | "manual"
+  | "url_parameter"
+  | "dom_selector"
+  | "global"
+  | "data_layer"
+  | "event_property"
+  | "click_selector"
+  | "computed";
+
+export interface SignalCaptureDefinition {
+  mode: SignalCaptureMode;
+  parameter?: string;
+  eventName?: string;
+  property?: string;
+  selector?: string;
+  source?: "text" | "attribute" | "dataset" | "constant";
+  attribute?: string;
+  value?: string | number | boolean;
+  path?: string;
+  persist?: boolean;
+}
+
+export interface RuntimeSignalDefinition {
+  key: string;
+  label?: string;
+  valueType?: "string" | "number" | "boolean" | "string_array" | "json";
+  ttlDays?: number;
+  capture?: SignalCaptureDefinition;
+}
+
+export interface SemanticTrackingRule {
+  id: string;
+  eventType: string;
+  action: "visibility" | "click";
+  selector: string;
+  pageType?: string;
+  elementRole?: string;
+  label?: string;
+  labelSource?: "text" | "attribute" | "constant";
+  attribute?: string;
+  indexStrategy?: "dom_order" | "none";
+  pathPattern?: string;
+  oncePerSession?: boolean;
+}
+
+export interface SemanticTrackingSettings {
+  enabled?: boolean;
+  sampleRate?: number;
+  visibilityThreshold?: number;
+  minVisibleMs?: number;
+  maxEventsPerSession?: number;
+  rules?: SemanticTrackingRule[];
+}
+
+export interface CommercePriceSettings {
+  revision: number;
+  checksum: string;
+  authorization?: {
+    version: 1;
+    revision: number;
+    checksum: string;
+    experimentIds: string[];
+    cartValidationShop?: string;
+  };
+  experiments: Array<{
+    experiment_id: string;
+    assignment_epoch?: number;
+    currency: string;
+    variants: Record<string, Array<{
+      variant_gid: string;
+      fixedPricePerUnit?: string;
+      compareAt?: { mode: "set"; amount: string } | { mode: "clear" };
+    }>>;
+  }>;
+}
+
+export interface CommerceShippingSettings {
+  authorization?: {
+    version: 1;
+    revision: number;
+    checksum: string;
+    experimentIds: string[];
+  };
+  experiments: Array<{
+    experiment_id: string;
+    assignment_epoch?: number;
+    currency: string;
+    variants: Record<
+      string,
+      {
+        threshold: string | null;
+        treatment:
+          | "progress_bar"
+          | "banner"
+          | "free_shipping"
+          | "flat_rate"
+          | "percent_off"
+          | "none";
+        progressCopy: string;
+        reachedCopy: string;
+        bannerCopy: string;
+        flatRate: string | null;
+        percentOff: number | null;
+        target: { productGids: string[]; variantGids: string[] };
+      }
+    >;
+  }>;
+}
+
+export interface CommerceOffersSettings {
+  authorization?: {
+    version: 1;
+    revision: number;
+    checksum: string;
+    experimentIds: string[];
+    cartValidationShop?: string;
+  };
+  experiments: CommerceOfferExperiment[];
+}
+
+export interface CommerceOfferExperiment {
+  experiment_id: string;
+  assignment_epoch?: number;
+  currency: string;
+  variants: Record<string,
+    | { offer_type: "gwp_threshold"; threshold: string; gift_variant_gid: string; tiers?: Array<{ threshold: string; gift_variant_gid: string; gift_choice_variant_gids?: string[] }> }
+    | { offer_type: string; control: true }
+    | Record<string, unknown>
+  >;
+}
+
+export interface InitConfig {
+  /** Provide experiments inline OR use shopId to auto-fetch from API. */
+  experiments?: Experiment[];
+  /** Request-scoped edge geography used for targeting. */
+  geo?: { country?: string };
+  /** Server-authored exclusion groups. Overlapping members never co-occur; one wins by share. */
+  exclusionGroups?: ExclusionGroupConfig[];
+  /** Active custom signal definitions that the runtime should capture for targeting. */
+  signals?: RuntimeSignalDefinition[];
+  /** Server-authored presentation-only commerce settings. */
+  commerce?: {
+    price?: CommercePriceSettings;
+    shipping?: CommerceShippingSettings;
+    offers?: CommerceOffersSettings;
+  };
+  /** Shop ID – when provided (without experiments), the SDK fetches running experiments from the API. */
+  shopId?: string;
+  /** Base URL for event tracking & config API (e.g. "https://events.drip-apex.com"). */
+  endpoint?: string;
+  /** Optional endpoint for signed storefront audit snapshots. Defaults to Apex production. */
+  auditEndpoint?: string;
+  /** Versioned editor bundle URL emitted by the Apex snippet. */
+  editorBundleUrl?: string;
+  ingestShopId?: string;
+  ingestSignature?: string;
+  attributes?: Record<string, unknown>;
+  userId?: string;
+  url?: string;
+  autoTrack?: boolean;
+  /** 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). */
+  configCacheTtlMs?: number;
+  /** Behavior when async config resolves after anti-flicker has already revealed. Default: "skip". */
+  lateConfigPolicy?: "skip" | "apply";
+  /**
+   * @deprecated Use `trackingStart`.
+   * Legacy compatibility: true -> "idle", false -> "immediate".
+   */
+  deferTracking?: boolean;
+  /**
+   * @deprecated Use `antiFlickerMode`.
+   * Legacy compatibility: true -> "full", false -> "off".
+   */
+  antiFlicker?: boolean;
+  /**
+   * @deprecated Use `antiFlickerTimeoutMs`.
+   * Legacy compatibility timeout in ms.
+   */
+  antiFlickerTimeout?: number;
+
+  /**
+   * Execution mode. Default: "auto".
+   * - "auto": edge-first when proxied, client fallback otherwise.
+   * - "edge": force edge rewrite path only.
+   * - "client": force client-side SDK evaluation only.
+   */
+  executionMode?: ExecutionMode;
+
+  /**
+   * Optional runtime platform hint.
+   * Priority order at runtime:
+   * 1) explicit platformHint
+   * 2) payload profile.platform
+   * 3) auto detection
+   */
+  platformHint?: PlatformHint;
+  /** Optional config payload profile metadata. */
+  profile?: ConfigProfile;
+  /** Router observation mode. Default: auto. */
+  routerMode?: RouterMode;
+  /** Mutation activation mode. Default: auto (observer). */
+  activationMode?: ActivationMode;
+  /** Project-level prerequisite rules evaluated in the browser before variation display/tracking. */
+  projectPrerequisites?: ProjectPrerequisites;
+  /** Strict consent mode: render variants before consent, but avoid persistent storage and tracking until consent. */
+  consentMode?: ConsentModeSettings;
+  /** Restricted debug console settings. */
+  debug?: DebugSettings;
+  /** SPA and dynamic-site support settings. */
+  spa?: SpaSettings;
+  /** Default page activation trigger. "direct" preserves immediate snippet behavior. */
+  pageTrigger?: PageTriggerSettings;
+  /** Cross-domain bucket handover for external checkout, booking, or lead-flow domains. */
+  externalTracking?: ExternalTrackingSettings;
+  /** dataLayer/custom analytics event triggers for SPA storefronts. */
+  dataLayerTriggers?: DataLayerTriggerSettings[];
+  /** External analytics destinations for experiment exposure events. */
+  exposureDestinations?: ExposureDestinationsSettings;
+  /** Advanced project-level CSS and JavaScript. */
+  projectCode?: ProjectCodeSettings;
+  /** Environment metadata included in edge-delivered config. */
+  environments?: RuntimeEnvironmentSettings;
+  /** Browser storage cleanup for stale bucket/QA/config records. */
+  bucketingCleanup?: BucketingCleanupSettings;
+  /** Browser storage/privacy controls. */
+  dataProtection?: DataProtectionSettings;
+  /** Semantic interaction capture for PDP galleries, tabs, CTAs, and other named store behavior. */
+  semanticTracking?: SemanticTrackingSettings;
+  /** Server-authoritative runtime kill switch state. */
+  runtimeControl?: RuntimeControlSettings;
+  /** 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;
+  /** Immutable SDK artifact version selected by the Worker. */
+  sdkVersion?: string;
+  /** Resolved SDK policy mode selected by the Worker. */
+  sdkDeliveryMode?: "global" | "pinned" | "canary" | string;
+  /** Whether the selected SDK artifact is embedded in the snippet or loaded externally. */
+  sdkDeliverySource?: "embedded" | "external" | string;
+  /** Revision of the global SDK delivery policy used to compile the snippet. */
+  sdkPolicyRevision?: string;
+  /** Server-authoritative runtime profile. Unknown values must retain full behavior. */
+  runtimeProfile?: "full" | "empty_project" | "nonvisual_assignment" | string;
+  /** Precompiled delivery manifest emitted by the snippet compiler. */
+  delivery?: SnippetDeliveryManifest;
+  /** Compiled runtime feature profile selected by the Worker for this shop/revision. */
+  runtimeFeatures?: {
+    sdkVariant?: "live" | "heatmap" | "debug" | string;
+    heatmap?: boolean;
+    debug?: boolean;
+    qa?: boolean;
+    harness?: boolean;
+    audit?: boolean;
+  };
+  /** Runtime kill-switches for staged rollout features. */
+  perfFlags?: PerfFeatureFlags;
+
+  /**
+   * Anti-flicker hiding strategy. Default: "scoped".
+   * - "scoped": hide only mutated selectors (lowest visual impact).
+   * - "full": hide entire page (legacy behavior).
+   * - "custom": use `antiFlickerCustomCss`.
+   * - "off": no anti-flicker hiding.
+   */
+  antiFlickerMode?: AntiFlickerMode;
+
+  /** Anti-flicker auto-reveal timeout in ms. Default: 1200. */
+  antiFlickerTimeoutMs?: number;
+  /** CSS used when antiFlickerMode is "custom". */
+  antiFlickerCustomCss?: string;
+
+  /**
+   * When to start analytics/tracking. Default: "idle".
+   * - "idle": defer to requestIdleCallback / timeout (reduces startup cost).
+   * - "immediate": start analytics synchronously after init.
+   */
+  trackingStart?: TrackingStart;
+
+  /** Idle timeout fallback in ms when trackingStart is "idle". Default: 2000. */
+  trackingIdleTimeoutMs?: number;
+
+  /**
+   * 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. */
+  requireConsent?: boolean;
+  /** Initial consent state when requireConsent is enabled. */
+  hasConsent?: boolean;
+  onExperimentViewed?: (assignment: Assignment) => void;
+}
+
+export interface TrackEvent {
+  type: string;
+  data?: Record<string, unknown>;
+  experimentId?: string;
+  variationId?: string;
+  shopId?: string;
+  visitorId?: string;
+  sessionId?: string;
+  url?: string;
+  ts?: number;
+  event_id?: string;
+  environment?: string;
+  qa_mode?: boolean;
+  qa_session_id?: string;
+}