@drip-apex/sdk 0.1.0

package/dist/types/editor/picker.d.ts

@@ -0,0 +1,23 @@
+type PickerOverlay = {
+    box: HTMLElement;
+    label: HTMLElement;
+};
+export declare class ElementPicker {
+    private readonly overlay;
+    private readonly onSelect;
+    private readonly onActiveChange;
+    private readonly onUnsupported?;
+    private active;
+    private hovered;
+    private selected;
+    constructor(overlay: PickerOverlay, onSelect: (element: Element, selector: string) => void, onActiveChange: (active: boolean) => void, onUnsupported?: (() => void) | undefined);
+    setActive(active: boolean): void;
+    setSelected(element: Element | null): void;
+    destroy(): void;
+    private onPointerMove;
+    private onClick;
+    private onKeyDown;
+    private refresh;
+    private renderOverlay;
+}
+export {};

package/dist/types/editor/selector.d.ts

@@ -0,0 +1,2 @@
+export declare function generateDeterministicSelector(element: Element, root?: ParentNode): string;
+export declare function elementLabel(element: Element): string;

package/dist/types/editor/types.d.ts

@@ -0,0 +1,55 @@
+import type { Mutation } from "../types";
+export type ActiveEditorSession = {
+    sid: string;
+    bearer: string;
+    expiresAt: string;
+    shopId: string;
+    experimentId: string;
+    experimentName?: string | null;
+    initialVariationId: string;
+    targetUrl: string;
+    targetOrigin: string;
+    variations: Array<{
+        id: string;
+        name?: string | null;
+        slug?: string | null;
+    }>;
+};
+export type EditorArtifacts = {
+    mutations: Mutation[];
+    customCss: string;
+    customJs: string;
+};
+export type EditorVariation = {
+    id: string;
+    name: string;
+    artifactHash: string;
+    reviewStatus: string | null;
+};
+export type EditorBrowserCommand = "navigate" | "reload" | "back" | "forward" | "click" | "type" | "wait_for" | "snapshot" | "screenshot" | "eval_readonly" | "console_logs" | "network_logs" | "network_probe" | "current_url" | "select_element" | "apply_artifacts";
+export type ClaimedEditorCommand = {
+    commandId: string;
+    command: EditorBrowserCommand;
+    args: Record<string, unknown>;
+    expiresAt: string | null;
+};
+export type EditorSaveState = "idle" | "saving" | "saved" | "conflict" | "error";
+export type EditorDeviceState = "closed" | "loading" | "active" | "blocked";
+export type EditorState = {
+    variation: EditorVariation | null;
+    artifacts: EditorArtifacts;
+    artifactsEnabled: boolean;
+    pickerActive: boolean;
+    selectedElement: Element | null;
+    selectedSelector: string | null;
+    saveState: EditorSaveState;
+    saveMessage: string | null;
+    dock: "top" | "bottom";
+    canUndo: boolean;
+    canRedo: boolean;
+    jsApplied: boolean;
+    reloadRequired: boolean;
+    deviceState: EditorDeviceState;
+};
+export declare const EMPTY_EDITOR_ARTIFACTS: EditorArtifacts;
+export declare function cloneArtifacts(artifacts: EditorArtifacts): EditorArtifacts;

package/dist/types/editor/view-kit.d.ts

@@ -0,0 +1,33 @@
+export declare const ICONS: {
+    readonly pointer: "M4 3l7.6 18 2.3-7.4L21 11.5zM13.9 13.9L19 19";
+    readonly undo: "M9 14L4 9l5-5M4 9h10.5a5.5 5.5 0 015.5 5.5v0a5.5 5.5 0 01-5.5 5.5H11";
+    readonly redo: "M15 14l5-5-5-5M20 9H9.5A5.5 5.5 0 004 14.5v0A5.5 5.5 0 009.5 20H13";
+    readonly monitor: "M3 4h18a1 1 0 011 1v11a1 1 0 01-1 1H3a1 1 0 01-1-1V5a1 1 0 011-1zM8 21h8M12 17v4";
+    readonly tablet: "M6 2h12a2 2 0 012 2v16a2 2 0 01-2 2H6a2 2 0 01-2-2V4a2 2 0 012-2zM12 18h.01";
+    readonly phone: "M8 2h8a2 2 0 012 2v16a2 2 0 01-2 2H8a2 2 0 01-2-2V4a2 2 0 012-2zM11 18h2";
+    readonly wifiOff: "M2 2l20 20M8.5 16.5a5 5 0 015.6-1M5 12.5a10 10 0 015.2-2.7M2 8.8a15 15 0 014.2-2.5M16.6 6.6A15 15 0 0122 8.8M12 20h.01";
+    readonly braces: "M8 3H7a2 2 0 00-2 2v4a2 2 0 01-2 2 2 2 0 012 2v4a2 2 0 002 2h1M16 3h1a2 2 0 012 2v4a2 2 0 002 2 2 2 0 00-2 2v4a2 2 0 01-2 2h-1";
+    readonly collapse: "M9 3v18M3 5a2 2 0 012-2h14a2 2 0 012 2v14a2 2 0 01-2 2H5a2 2 0 01-2-2zM13 10l3 2-3 2";
+    readonly history: "M3 12a9 9 0 113 6.7M3 12H1.5M3 12l-1.8 2M12 7v5l3.5 2";
+    readonly send: "M22 2L11 13M22 2l-7 20-4-9-9-4z";
+    readonly stop: "M6 6h12v12H6z";
+    readonly cursorBox: "M3 3h8M3 3v8M21 13v8h-8M9 9l7 7M16 9v7h-7";
+    readonly check: "M5 13l4 4L19 7";
+    readonly x: "M18 6L6 18M6 6l12 12";
+    readonly chevD: "M6 9l6 6 6-6";
+    readonly chevR: "M9 6l6 6-6 6";
+    readonly refresh: "M3 12a9 9 0 0114.5-7L21 8M21 3v5h-5M21 12a9 9 0 01-14.5 7L3 16M3 21v-5h5";
+    readonly external: "M15 3h6v6M21 3l-9 9M10 5H5a2 2 0 00-2 2v12a2 2 0 002 2h12a2 2 0 002-2v-5";
+    readonly code: "M16 18l6-6-6-6M8 6l-6 6 6 6";
+    readonly clock: "M12 22a10 10 0 100-20 10 10 0 000 20zM12 7v5l3 2";
+    readonly eye: "M2 12s4-7 10-7 10 7 10 7-4 7-10 7-10-7-10-7zM12 15a3 3 0 100-6 3 3 0 000 6z";
+    readonly alert: "M10.3 3.9L1.8 18a2 2 0 001.7 3h17a2 2 0 001.7-3L13.7 3.9a2 2 0 00-3.4 0zM12 9v4M12 17h.01";
+    readonly globe: "M12 2a10 10 0 100 20 10 10 0 000-20zM2 12h20M12 2a15 15 0 010 20M12 2a15 15 0 000 20";
+    readonly play: "M6 4l14 8-14 8z";
+    readonly dot: "M12 12h.01";
+};
+export type IconName = keyof typeof ICONS;
+export declare function icon(name: IconName, size?: number, extra?: string): string;
+export declare function operatorMark(size?: number, color?: string): string;
+export declare function esc(value: string): string;
+export declare const KIT_CSS = "\n:host {\n  --bg0:#08080A;--bg1:#0A0A0C;--raised:#141419;--raised-hi:#1A1A21;--inset:#0B0B0E;\n  --border:rgba(255,255,255,0.06);--border-hi:rgba(255,255,255,0.10);--border-px:rgba(255,255,255,0.14);\n  --text1:#FAFAFA;--text2:rgba(255,255,255,0.66);--text3:rgba(255,255,255,0.42);--text4:rgba(255,255,255,0.26);\n  --purple500:#5B29FF;--purple400:#7C54FF;--purple300:#9B6FFF;--purple200:#C8B4FF;\n  --purple-soft:rgba(91,41,255,0.14);--purple-bd:rgba(124,84,255,0.34);\n  --positive:#3DD68C;--warning:#FACC15;--negative:#EB5252;--negative-soft:#F39797;\n  all:initial;font-family:Inter,system-ui,sans-serif;color:var(--text1);letter-spacing:0;\n  position:fixed;inset:0;z-index:2147483647;pointer-events:none;font-size:12.5px;line-height:1.5;\n}\n*{box-sizing:border-box;letter-spacing:0;margin:0;padding:0}\nbutton,input,select,textarea{font:inherit;color:inherit;font-family:inherit}\nbutton{cursor:pointer;background:none;border:none}\nbutton:disabled{cursor:not-allowed}\n:is(button,textarea,input,a):focus-visible{outline:2px solid var(--purple400);outline-offset:2px}\n@keyframes ee-spin{to{transform:rotate(360deg)}}\n@keyframes ee-pulse{0%{transform:scale(0.7);opacity:0.9}100%{transform:scale(1.6);opacity:0}}\n@keyframes ee-in{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}\n.ee-in{animation:ee-in 160ms ease-out}\n.spin{animation:ee-spin 1s linear infinite}\n@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:0.01ms!important;animation-iteration-count:1!important;transition-duration:0.01ms!important}}\n\n/* Buttons */\n.btn{display:inline-flex;align-items:center;gap:7px;justify-content:center;padding:7px 12px;font-size:13px;font-weight:550;border-radius:8px;border:1px solid transparent;line-height:1.2;white-space:nowrap;transition:background 120ms,border-color 120ms,color 120ms;pointer-events:auto}\n.btn.sm{padding:5px 10px;font-size:12px}\n.btn:disabled{opacity:0.45}\n.btn.primary{background:var(--purple500);color:#fff;border-color:rgba(255,255,255,0.14)}\n.btn.soft{background:var(--purple-soft);color:var(--purple200);border-color:var(--purple-bd)}\n.btn.ghost{background:transparent;color:var(--text2);border-color:var(--border)}\n.btn.ghost:hover{background:var(--raised-hi);color:var(--text1)}\n.btn.bare{background:transparent;color:var(--text2);border-color:transparent}\n.btn.danger{background:rgba(235,82,82,0.14);color:var(--negative-soft);border-color:rgba(235,82,82,0.3)}\n.iconbtn{width:30px;height:30px;display:inline-flex;align-items:center;justify-content:center;border-radius:8px;border:1px solid transparent;background:transparent;color:var(--text2);flex-shrink:0;transition:background 120ms,color 120ms;pointer-events:auto}\n.iconbtn:hover{background:var(--raised-hi);color:var(--text1)}\n.iconbtn.active{background:var(--purple-soft);color:var(--purple200);border-color:var(--purple-bd)}\n.iconbtn:disabled{opacity:0.4}\n.iconbtn.xs{width:22px;height:22px}\n\n/* Status dot */\n.dot{position:relative;width:7px;height:7px;flex-shrink:0;display:inline-block}\n.dot i{position:absolute;inset:0;border-radius:50%}\n.dot.ok i{background:var(--positive)}.dot.warn i{background:var(--warning)}.dot.err i{background:var(--negative)}.dot.purple i{background:var(--purple300)}\n.dot b{position:absolute;inset:-3px;border-radius:50%;border:1px solid currentColor}\n.dot.ok b{color:var(--positive)}.dot.warn b{color:var(--warning)}.dot.err b{color:var(--negative)}.dot.purple b{color:var(--purple300)}\n.dot b{animation:ee-pulse 1.4s ease-out infinite}\n\n/* Save chip */\n.save-chip{display:inline-flex;align-items:center;gap:7px;font-size:12px;font-weight:550;padding:4px 9px;border-radius:7px;background:rgba(255,255,255,0.04);border:1px solid var(--border);white-space:nowrap}\n.save-chip.unsaved{color:var(--warning)}\n.save-chip.saving{color:var(--purple200)}\n.save-chip.saved{color:var(--positive)}\n.save-chip.failed,.save-chip.conflict{color:var(--negative-soft);background:rgba(235,82,82,0.10);border-color:rgba(235,82,82,0.25)}\n.save-chip .retry{border:none;background:rgba(255,255,255,0.1);color:#fff;font-size:11.5px;font-weight:600;border-radius:5px;padding:2px 7px;margin-left:2px;pointer-events:auto}\n\n/* Segmented control */\n.seg{display:inline-flex;background:var(--inset);border-radius:8px;padding:2px;gap:2px;border:1px solid var(--border);pointer-events:auto}\n.seg button{display:inline-flex;align-items:center;gap:6px;justify-content:center;padding:5px 11px;border-radius:6px;border:none;background:transparent;color:var(--text3);font-size:12px;font-weight:550;transition:background 120ms,color 120ms}\n.seg button.sm{padding:4px 8px}\n.seg button[aria-checked=\"true\"]{background:var(--raised-hi);color:var(--text1);box-shadow:inset 0 0 0 1px var(--border-px)}\n\n/* Pills & chips */\n.draft-pill{display:inline-flex;align-items:center;gap:6px;padding:2px 8px;border-radius:999px;background:rgba(250,204,21,0.10);border:1px solid rgba(250,204,21,0.3);font-size:11px;font-weight:600;color:var(--warning);white-space:nowrap}\n.session-chip{display:inline-flex;align-items:center;gap:6px;font-size:12px;font-weight:550;color:var(--warning);padding:4px 9px;border-radius:7px;border:1px solid rgba(250,204,21,0.35);background:rgba(250,204,21,0.08);white-space:nowrap;font-variant-numeric:tabular-nums}\n.session-chip .extend{border:none;background:rgba(250,204,21,0.16);color:var(--warning);font-size:11.5px;font-weight:600;border-radius:5px;padding:2px 7px;pointer-events:auto}\n.session-note{font-size:11px;color:var(--text4);white-space:nowrap}\n.conn-chip{display:inline-flex;align-items:center;gap:7px;font-size:12px;font-weight:550;white-space:nowrap;color:var(--text3)}\n.conn-chip.offline{color:var(--negative-soft)}\n.conn-chip.connecting{color:var(--warning)}\n.ctx-chip{display:inline-flex;align-items:center;gap:7px;max-width:100%;background:var(--purple-soft);border:1px solid var(--purple-bd);border-radius:8px;padding:5px 8px;font-size:11.5px;color:var(--purple200);font-weight:550}\n.ctx-chip .name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.ctx-chip .replace{border:none;background:rgba(255,255,255,0.08);color:var(--text2);font-size:10.5px;font-weight:600;border-radius:5px;padding:2px 7px;pointer-events:auto}\n.ctx-chip .clear{border:none;background:none;color:var(--text3);padding:2px;display:inline-flex;pointer-events:auto}\n\n/* Fields */\n.field{width:100%;background:var(--inset);color:var(--text1);border:1px solid var(--border-hi);border-radius:8px;padding:8px 10px;font-size:12.5px;line-height:1.5;outline:none;resize:vertical;pointer-events:auto}\n.field::placeholder{color:rgba(255,255,255,0.28)}\n.field.code{white-space:pre;font-variant-numeric:tabular-nums;min-height:150px}\n.flabel{display:block;font-size:11.5px;font-weight:550;color:var(--text3);margin-bottom:5px}\n.fhint{display:block;font-size:11px;color:var(--text4);margin-top:4px}\n\n/* Banners */\n.banner{display:flex;align-items:center;gap:9px;padding:8px 12px;border-radius:10px;color:var(--text1);font-size:12.5px;box-shadow:0 12px 32px rgba(0,0,0,0.4);pointer-events:auto;max-width:560px}\n.banner .body{flex:1;min-width:0}\n.banner.info{background:linear-gradient(0deg,rgba(91,41,255,0.16),rgba(91,41,255,0.16)),var(--bg1);border:1px solid var(--purple-bd)}\n.banner.info svg{color:var(--purple200)}\n.banner.warn{background:linear-gradient(0deg,rgba(250,204,21,0.10),rgba(250,204,21,0.10)),var(--bg1);border:1px solid rgba(250,204,21,0.35)}\n.banner.warn svg{color:var(--warning)}\n.banner.error{background:linear-gradient(0deg,rgba(235,82,82,0.12),rgba(235,82,82,0.12)),var(--bg1);border:1px solid rgba(235,82,82,0.35)}\n.banner.error svg{color:var(--negative-soft)}\n\n/* Modal */\n.modal-backdrop{position:fixed;inset:0;z-index:300;display:flex;align-items:center;justify-content:center;background:rgba(5,5,8,0.55);backdrop-filter:blur(3px);pointer-events:auto}\n.modal{width:430px;max-width:calc(100vw - 40px);background:var(--bg1);border:1px solid var(--border-px);border-radius:14px;box-shadow:0 32px 80px rgba(0,0,0,0.55);overflow:hidden;color:var(--text1)}\n.modal .m-head{display:flex;gap:10px;align-items:flex-start;padding:18px 18px 0}\n.modal .m-icon{width:30px;height:30px;border-radius:8px;background:rgba(255,255,255,0.05);border:1px solid var(--border);display:flex;align-items:center;justify-content:center;flex-shrink:0}\n.modal .m-icon.warn{color:var(--warning)}.modal .m-icon.purple{color:var(--purple300)}.modal .m-icon.ok{color:var(--positive)}\n.modal .m-title{font-size:15px;font-weight:600;letter-spacing:-0.015em;padding-top:4px}\n.modal .m-body{padding:12px 18px 4px;font-size:13px;line-height:1.6;color:var(--text2)}\n.modal .m-body p{margin:0}\n.modal .m-body p+p{margin-top:10px}\n.modal .m-actions{display:flex;justify-content:flex-end;gap:8px;padding:14px 18px 18px}\n";

package/dist/types/editor/view.d.ts

@@ -0,0 +1,5 @@
+import type { EditorController } from "./controller";
+export type EditorView = {
+    destroy(): void;
+};
+export declare function mountEditorView(shadow: ShadowRoot, controller: EditorController): EditorView;

package/dist/types/editor-bootstrap.d.ts

@@ -0,0 +1,37 @@
+export declare const EDITOR_FRAGMENT_KEY = "apex-editor";
+export declare const EDITOR_BUNDLE_FILENAME = "editor.js";
+export declare const EDITOR_DEVICE_FRAME_NAME = "apex-editor-device-preview";
+export type EditorLaunchHint = {
+    token: string;
+    sid: string;
+    apiOrigin: string;
+};
+type LocationLike = Pick<Location, "hash" | "href">;
+type HistoryLike = Pick<History, "replaceState" | "state">;
+export type EditorBundleApi = {
+    start: (launch: EditorLaunchHint) => boolean | Promise<boolean>;
+};
+export declare function isEditorDevicePreview(windowLike?: Pick<Window, "name">): boolean;
+export declare function decodeEditorLaunchToken(token: string): Omit<EditorLaunchHint, "token"> | null;
+export declare function consumeEditorLaunchFragment(locationLike?: LocationLike, historyLike?: HistoryLike): EditorLaunchHint | null;
+export declare function resolveEditorBundleUrl(input: {
+    configuredUrl?: string;
+    scriptSrc?: string;
+    pageUrl?: string;
+}): string | null;
+export declare function loadEditorBundle(bundleUrl: string, documentLike?: Document, timeoutMs?: number): Promise<EditorBundleApi>;
+export declare function interceptEditorLaunch(input: {
+    configuredBundleUrl?: string;
+    scriptSrc?: string;
+    pageUrl?: string;
+    onBeforeLoad?: () => void;
+    onFailure: () => void;
+    loadBundle?: (url: string) => Promise<EditorBundleApi>;
+    locationLike?: LocationLike;
+    historyLike?: HistoryLike;
+}): boolean;
+export declare const __test: {
+    getState: () => "idle" | "active" | "starting";
+    resetState: () => void;
+};
+export {};

package/dist/types/exclusion-groups.d.ts

@@ -0,0 +1,59 @@
+import type { Assignment, ExclusionGroupConfig } from "./types";
+/** A remembered group decision: which member won and at what group epoch. */
+export type PersistedGroupSelection = {
+    experimentId: string;
+    epoch: number;
+};
+/** Pluggable persistence so the runtime uses browser storage and tests use memory. */
+export interface GroupStickyStore {
+    read(groupId: string): PersistedGroupSelection | null;
+    write(groupId: string, selection: PersistedGroupSelection): void;
+}
+type CompactSelection = [string, number];
+type CompactStore = Record<string, CompactSelection>;
+declare function normalizeEpoch(epoch: number | null | undefined): number;
+declare function parseStore(raw: string | null): CompactStore;
+/** Browser-backed store (localStorage + cookie mirror) used by the live runtime. */
+export declare const browserGroupStickyStore: GroupStickyStore;
+/** Remove consent-gated group stickiness from both browser persistence planes. */
+export declare function clearBrowserGroupStickyStore(): void;
+/** In-memory store for tests and non-persistent (QA / no-consent) contexts. */
+export declare function createMemoryGroupStickyStore(): GroupStickyStore;
+export interface ExclusionGroupDecision {
+    groupId: string;
+    /** Eligible, non-forced members that overlapped for this visitor. */
+    conflictingExperimentIds: string[];
+    winnerExperimentId: string | null;
+    suppressedExperimentIds: string[];
+    /** True when the winner was carried over from a prior sticky selection. */
+    sticky: boolean;
+}
+export interface ResolveExclusionGroupsResult {
+    assignments: Assignment[];
+    decisions: ExclusionGroupDecision[];
+}
+/**
+ * Second pass of the overlap-then-pick model.
+ *
+ * `assignments` are the pass-one winners (each experiment already evaluated its
+ * own status, targeting, exposure, sticky assignment and variation split). Here
+ * we detect members of the same exclusion group that BOTH became eligible for
+ * this visitor (overlap) and keep exactly one — chosen by a group-deterministic
+ * hash weighted by each conflicting member's share, re-normalized across only
+ * the conflicting members. A previously assigned member stays sticky while it
+ * remains eligible; if it drops out we reselect among the current conflicting
+ * members. Forced (QA preview) members bypass exclusion entirely.
+ */
+export declare function resolveExclusionGroups(assignments: Assignment[], groups: ExclusionGroupConfig[] | undefined, ctx: {
+    userId: string;
+    forcedExperimentIds?: Iterable<string>;
+    store?: GroupStickyStore;
+    persist?: boolean;
+}): ResolveExclusionGroupsResult;
+export declare const __exclusionGroupInternals: {
+    STORAGE_KEY: string;
+    COOKIE_NAME: string;
+    parseStore: typeof parseStore;
+    normalizeEpoch: typeof normalizeEpoch;
+};
+export {};

package/dist/types/exposure-signals.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeSignalDefinition } from "./types";
+type ExposureSignalValue = string | number | boolean;
+export declare function buildExposureSignalContext(input: {
+    attributes: Record<string, unknown>;
+    customSignals?: RuntimeSignalDefinition[];
+}): Record<string, ExposureSignalValue> | null;
+export {};

package/dist/types/flags.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Feature flags — thin wrapper over experiment assignments.
+ *
+ * A feature flag is simply a two-variation experiment where:
+ *   - control = flag OFF
+ *   - variant = flag ON
+ *
+ * Usage:
+ *   import { evaluateFlag, defineFlagExperiment } from "@drip-apex/sdk/flags";
+ *
+ *   const darkMode = defineFlagExperiment({
+ *     slug: "dark-mode-rollout",
+ *     name: "Dark Mode Rollout",
+ *     rolloutPercent: 25,
+ *   });
+ *
+ *   const isEnabled = evaluateFlag("dark-mode-rollout", [darkMode], { userId: "user-123" });
+ */
+import type { Experiment, Assignment } from "./types";
+export interface FlagContext {
+    url?: string;
+    attributes?: Record<string, unknown>;
+    userId?: string;
+}
+/**
+ * Evaluate whether a feature flag is enabled.
+ *
+ * @param flagId - The experiment slug/id of the flag experiment.
+ * @param experiments - Array of experiment configs to search (from init or defineExperiment).
+ * @param context - Optional user context for targeting/bucketing.
+ * @returns `true` if the user is bucketed into a non-control variation.
+ */
+export declare function evaluateFlag(flagId: string, experiments: Experiment[], context?: FlagContext): boolean;
+/**
+ * Evaluate a flag and return the full assignment (or null if flag is off / not found).
+ */
+export declare function evaluateFlagAssignment(flagId: string, experiments: Experiment[], context?: FlagContext): Assignment | null;
+/**
+ * Evaluate a typed feature flag value.
+ *
+ * Returns the assigned variation value for boolean, string, number, or JSON
+ * flags. If the visitor is not eligible, the flag is missing, or no assignment
+ * can be made, the fallback is returned.
+ */
+export declare function evaluateFlagValue<T = unknown>(flagId: string, experiments: Experiment[], context?: FlagContext, fallback?: T): T | unknown;
+export interface FlagDefinition {
+    /** Unique slug for the flag. */
+    slug: string;
+    /** Human-readable name. */
+    name: string;
+    /** Percentage of traffic to enable the flag for (0–100). Default: 0 (off). */
+    rolloutPercent?: number;
+    /** Targeting rules. */
+    targeting?: Experiment["targeting"];
+    /** Value returned when the flag is disabled. Default: false. */
+    offValue?: unknown;
+    /** Value returned when the flag is enabled. Default: true. */
+    onValue?: unknown;
+}
+/**
+ * Create a flag-style experiment with two variations: control (OFF) and enabled (ON).
+ */
+export declare function defineFlagExperiment(def: FlagDefinition): Experiment & {
+    slug: string;
+};

package/dist/types/goals.d.ts

@@ -0,0 +1,16 @@
+import { Goal, Assignment } from "./types";
+type GoalCallback = (goalId: string, assignment: Assignment, data?: Record<string, unknown>) => void;
+export declare function setupGoals(assignments: Assignment[], experiments: {
+    id: string;
+    goals?: Goal[];
+}[], callback: GoalCallback): void;
+export declare function triggerGoal(goalId: string, assignments: Assignment[], experiments: {
+    id: string;
+    goals?: Goal[];
+}[], data?: Record<string, unknown>): void;
+export declare function triggerGoalsForEvent(eventName: string, assignments: Assignment[], experiments: {
+    id: string;
+    goals?: Goal[];
+}[], data?: Record<string, unknown>): void;
+export declare function cleanupGoals(): void;
+export {};

package/dist/types/guards.d.ts

@@ -0,0 +1,39 @@
+export declare function isBot(): boolean;
+export declare function isIframe(): boolean;
+export declare function isDuplicate(): boolean;
+export declare function isOptedOut(options?: {
+    storageAllowed?: boolean;
+}): boolean;
+export declare function isScreenshotMode(): boolean;
+declare function parseForceParams(params: URLSearchParams): Record<string, string> | null;
+export declare function parseForceParam(options?: {
+    cookieFallback?: boolean;
+}): Record<string, string> | null;
+declare function parseForceString(value: string): Record<string, string> | null;
+export declare function isQaMode(options?: {
+    cookieFallback?: boolean;
+}): boolean;
+/**
+ * Persist the force map in a cookie so QA sessions survive navigation.
+ * Cookie expires after 30 minutes.
+ */
+export declare function persistQaForce(forceMap: Record<string, string>): void;
+declare function sanitizeQaSessionId(value: string | null): string | null;
+export declare function getQaSessionId(fallback: () => string, options?: {
+    storageAllowed?: boolean;
+}): string;
+/**
+ * Exit QA mode: clear the force cookie and remove drip_qa/drip_force from URL.
+ */
+export declare function exitQaMode(): void;
+export declare function readCookie(name: string): string | null;
+export declare function writeCookie(name: string, value: string, maxAge: number): void;
+export declare function deleteCookie(name: string): void;
+/** @internal — exposed for unit testing only. Tree-shaken from production build. */
+export declare const __test: {
+    parseForceString: typeof parseForceString;
+    parseForceParams: typeof parseForceParams;
+    sanitizeQaSessionId: typeof sanitizeQaSessionId;
+    BOT_RE: RegExp;
+};
+export {};

package/dist/types/handover.d.ts

@@ -0,0 +1,10 @@
+import type { Assignment, ExternalTrackingSettings } from "./types";
+export type HandoverData = {
+    visitorId?: string;
+    forceMap?: Record<string, string>;
+};
+export declare function handoverMintTimeoutMs(settings?: ExternalTrackingSettings): number;
+export declare function readBucketingHandover(settings: ExternalTrackingSettings | undefined, shopId: string, verifyToken: (token: string) => Promise<unknown>): Promise<HandoverData | null>;
+export declare function hasBucketingHandover(settings?: ExternalTrackingSettings): boolean;
+export declare function createBucketingHandoverPayload(visitorId: string, assignments: Assignment[], settings?: ExternalTrackingSettings): string;
+export declare function installBucketingHandover(settings: ExternalTrackingSettings | undefined, getPayload: () => string | null, mintPayload?: () => Promise<string | null>): () => void;

package/dist/types/hash.d.ts

@@ -0,0 +1,19 @@
+type StorageMode = "localStorage" | "sessionStorage" | "cookie" | "memory";
+export declare function murmurhash3_32_gc(key: string, seed?: number): number;
+export declare function hashToFloat(seed: string, value: string): number;
+export declare function variationHashToFloat(experimentId: string, value: string): number;
+export declare function configureIdentityStorage(settings?: {
+    storageMode?: StorageMode;
+    encodeStorageValues?: boolean;
+    cookieDomain?: string;
+}): void;
+/**
+ * Lifetime (cross-session) storage permitted by the configured identity
+ * storage mode. Only localStorage mode has one; sessionStorage/memory/cookie
+ * modes return null so lifetime counters stay unpersisted under them.
+ */
+export declare function lifetimeIdentityStorage(): Storage | null;
+export declare function getUserId(provided?: string): string;
+export declare function getEphemeralUserId(provided?: string): string;
+export declare function adoptUserId(value: string): void;
+export {};

package/dist/types/heatmap.d.ts

@@ -0,0 +1,8 @@
+import type { Assignment, Experiment } from "./types";
+type TrackFn = (type: string, data: Record<string, unknown>, experimentId: string, variationId: string) => void;
+type HeatmapController = {
+    stop: () => void;
+    update: (assignments: Assignment[], experiments: Experiment[]) => void;
+};
+export declare function startHeatmapCapture(assignments: Assignment[], experiments: Experiment[], track: TrackFn): HeatmapController;
+export {};

package/dist/types/hideflicker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Anti-flicker reveal module.
+ *
+ * The Worker's /s/<shopId>.js snippet injects
+ * <style id="drip-hide">…</style> as early as possible.
+ * In optimized mode this style is selector-scoped and only falls back
+ * to full-page hiding when scoped selectors are unavailable.
+ *
+ * This module provides revealAll() which the SDK calls once all mutations
+ * have been applied, making the page visible with the correct variant.
+ * A snippet safety timeout guarantees the page is always revealed even if
+ * the SDK encounters an error.
+ */
+/** Remove the anti-flicker style injected by the snippet */
+export declare function revealAll(): void;

package/dist/types/hydration.d.ts

@@ -0,0 +1,11 @@
+import type { Assignment, CommercePriceSettings } from "./types";
+export declare function detectSsrFramework(): "nuxt" | "next" | "server-rendered" | null;
+export declare function holdMutations(): number;
+export declare function releaseMutations(): number;
+export declare function hasMutationHold(): boolean;
+export declare function signalHydrated(): void;
+export declare function awaitHydration(timeoutMs: number, options?: {
+    waitForHydration?: boolean;
+}): Promise<void>;
+export declare function resetHydrationState(): void;
+export declare function assignmentsHaveVisualWork(assignments: Assignment[], priceSettings?: CommercePriceSettings): boolean;

package/dist/types/index.d.ts

@@ -0,0 +1,144 @@
+import { type CartAttributeEntry } from "./shopify-cart";
+import { type ApexRuntimeTools } from "./runtime-tools";
+import { ActivationMode, AntiFlickerMode, Assignment, ActivationDiagnostics, ConfigProfile, ConsentModeSettings, CustomJsPolicy, DebugSettings, ExecutionMode, Experiment, ExclusionGroupConfig, ExclusionGroupMemberConfig, Goal, InitConfig, PageTargetingRule, PageTriggerMode, PageTriggerSettings, PerfFeatureFlag, PerfFeatureFlags, PlatformHint, ProjectPrerequisites, RouterMode, SpaSettings, ExternalTrackingSettings, ProjectCodeSettings, RuntimeEnvironmentSettings, SdkDiagnostics, BucketingCleanupSettings, DataProtectionSettings, TrackEvent, TrackingStart, Variation } from "./types";
+type FetchAttemptInfo = {
+    attempt: number;
+    elapsedMs: number;
+    error?: string;
+    status?: number;
+    timedOut?: boolean;
+};
+type FetchRetryOptions = {
+    timeoutMs?: number;
+    firstAttemptTimeoutMs?: number;
+    slowMs?: number;
+    onAttemptStart?: (attempt: number) => void;
+    onAttemptEnd?: (info: FetchAttemptInfo) => void;
+    onSlow?: (info: {
+        attempt: number;
+        elapsedMs: number;
+    }) => void;
+};
+declare function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response>;
+declare function fetchWithRetry(url: string, retries?: number, delayMs?: number, options?: FetchRetryOptions): Promise<Response>;
+declare function normalizePageApiName(value: unknown): string;
+declare function triggerPage(apiName: unknown, active?: unknown): void;
+declare function installPageTriggerRule(rule: PageTargetingRule, onChange: () => void): () => void;
+type OrderIdentityPlatform = "shopify" | "shopware" | "woocommerce" | "centra" | "custom";
+type QaAssistantRuntimeSnapshot = {
+    config: InitConfig | null;
+    assignments: Assignment[];
+    activationDiagnostics: ActivationDiagnostics;
+    forceMap: Record<string, string> | null;
+    platform: PlatformHint;
+    qaMode: boolean;
+    orderIdentity: {
+        platform: OrderIdentityPlatform;
+        platformOrderId: string | null;
+        orderNumber: string | null;
+    } | null;
+};
+declare function getConfigCacheKey(shopId: string, environmentKey?: string): string;
+declare function withRuntimeSettings(config: InitConfig, runtime: unknown, profile?: InitConfig["profile"]): InitConfig;
+export declare function evaluate(experiments: Experiment[], context?: {
+    url?: string;
+    attributes?: Record<string, unknown>;
+    userId?: string;
+    persistSignals?: boolean;
+    exclusionGroups?: ExclusionGroupConfig[];
+}): Assignment[];
+export declare function __getQaAssistantRuntimeSnapshot(): QaAssistantRuntimeSnapshot;
+export declare function __subscribeQaAssistantRuntime(listener: () => void): () => void;
+export declare function __forceQaAssistantVariation(experimentId: string, variationId: string): void;
+export declare function __resetQaAssistantForce(experimentId?: string): void;
+export declare function init(config: InitConfig): Assignment[];
+export declare function track(type: string, data?: Record<string, unknown>, experimentId?: string, variationId?: string): void;
+/**
+ * Track a virtual funnel step that has no reliable browser event by default,
+ * such as a postcode form submit, embedded quiz step, or third-party handoff.
+ */
+export declare function trackStep(name: string, data?: Record<string, unknown>): void;
+export declare function trackGoal(goalId: string, data?: Record<string, unknown>): void;
+export declare function setConsent(granted: boolean): void;
+export declare function hold(): number;
+export declare function release(): number;
+export declare function hydrated(): void;
+export declare function recheckPrerequisites(): void;
+export declare function reInit(forceReapply?: boolean): Assignment[];
+/**
+ * Track a revenue/purchase event. Convenience method that fires a "purchase" event
+ * with revenue data for all active experiments.
+ *
+ * Usage: drip.trackRevenue(49.99) or drip.trackRevenue(49.99, { orderId: "123", currency: "EUR" })
+ */
+export type RevenueEventData = Record<string, unknown> & {
+    currency?: string;
+};
+export declare function trackRevenue(revenue: number, data?: RevenueEventData): void;
+export declare function flush(): Promise<void>;
+export declare function getAssignments(): Assignment[];
+export declare function getCartAttributes(): CartAttributeEntry[];
+/**
+ * Build cart attributes for a headless Shopify Storefront API cart.
+ *
+ * Integrator contract: pass the cart's full Storefront Cart GID (including its
+ * `?key=` secret), write every returned entry to that same cart, and verify the
+ * Storefront API mutation succeeded with no `userErrors`. Only then call
+ * {@link confirmCartAttributesWritten} with the same Cart GID. Returning signed
+ * attributes does not authorize treatment display or exposure by itself. An
+ * empty result is fail-closed and must not be replaced with unsigned attributes.
+ * Theme storefronts use the SDK-managed `/cart/update.js` path and do not call
+ * either headless API.
+ */
+export declare function getSignedCartAttributes(cartToken?: string): Promise<CartAttributeEntry[]>;
+/**
+ * Acknowledge that the latest signed headless cart attributes were persisted.
+ *
+ * Call this only after the Storefront API cart-attributes mutation succeeded
+ * and returned no `userErrors`. The Cart GID must match the one passed to the
+ * latest {@link getSignedCartAttributes} call. Stale-generation, mismatched,
+ * or repeated acknowledgements are no-ops and cannot grant or change display
+ * and exposure authorization. When a staged offer adoption can no longer
+ * apply, the acknowledgement is rejected (`false`) with retryable pending
+ * state and no authorization is granted.
+ *
+ * @returns `true` only when the latest matching acknowledgement was accepted.
+ */
+export declare function confirmCartAttributesWritten(cartToken?: string): boolean;
+export declare function getExperiments(): Experiment[];
+export declare function getRuntimeValue(key: string): unknown;
+export declare function getRuntimeTools(): ApexRuntimeTools;
+export declare function evaluateFlag(flagId: string, context?: {
+    url?: string;
+    attributes?: Record<string, unknown>;
+    userId?: string;
+}): boolean;
+export declare function evaluateFlagAssignment(flagId: string, context?: {
+    url?: string;
+    attributes?: Record<string, unknown>;
+    userId?: string;
+}): Assignment | null;
+export declare function evaluateFlagValue<T = unknown>(flagId: string, fallback?: T, context?: {
+    url?: string;
+    attributes?: Record<string, unknown>;
+    userId?: string;
+}): T | unknown;
+export declare function getDiagnostics(): SdkDiagnostics;
+export { defineExperiment, defineExperiments } from "./define";
+export { defineFlagExperiment } from "./flags";
+export { getSignals, rememberProduct, setCartSignals, setSearchSignal, setSignal, } from "./signals";
+export { createApexRuntimeTools } from "./runtime-tools";
+export declare const __test: {
+    fetchWithTimeout: typeof fetchWithTimeout;
+    fetchWithRetry: typeof fetchWithRetry;
+    getConfigCacheKey: typeof getConfigCacheKey;
+    installPageTriggerRule: typeof installPageTriggerRule;
+    normalizePageApiName: typeof normalizePageApiName;
+    triggerPage: typeof triggerPage;
+    withRuntimeSettings: typeof withRuntimeSettings;
+};
+export type { ActivationMode, AntiFlickerMode, Assignment, ConfigProfile, ConsentModeSettings, CustomJsPolicy, ExecutionMode, Experiment, ExclusionGroupConfig, ExclusionGroupMemberConfig, Goal, InitConfig, PageTriggerMode, PageTriggerSettings, PerfFeatureFlag, PerfFeatureFlags, PlatformHint, RouterMode, TrackEvent, TrackingStart, Variation, DebugSettings, ProjectPrerequisites, SpaSettings, ExternalTrackingSettings, ProjectCodeSettings, RuntimeEnvironmentSettings, SdkDiagnostics, BucketingCleanupSettings, DataProtectionSettings, };
+export type { ExperimentDefinition, VariationDefinition, GoalDefinition } from "./define";
+export type { FlagDefinition, FlagContext } from "./flags";
+export type { CartAttributeEntry } from "./shopify-cart";
+export type { ApexRuntimeTools, DataLayerOptions, DomChangedOptions, ElementInViewOptions, WaitForElementOptions, } from "./runtime-tools";

package/dist/types/js.d.ts

@@ -0,0 +1,6 @@
+import type { CustomJsPolicy } from "./types";
+export declare function setJsPolicy(policy: CustomJsPolicy): void;
+export declare function isStrictJsPolicy(): boolean;
+export declare function execJs(code: string, sourceLabel?: string): void;
+export declare function loadExternalJs(url: string, sourceLabel: string): Promise<void>;
+export declare function removeAllExternalJs(): void;

package/dist/types/module.d.ts

@@ -0,0 +1,4 @@
+import { type PendingGiftChoice } from "./commerce-gift";
+export declare function getPendingGiftChoices(experimentId?: string): PendingGiftChoice[];
+export declare function selectGiftOption(experimentId: string, variantGid: string): Promise<void>;
+export type { PendingGiftChoice };

package/dist/types/money.d.ts

@@ -0,0 +1,14 @@
+export type MoneyConvention = {
+    decimal: "." | ",";
+    group: string;
+    decimals: number;
+    minorUnits: number;
+};
+export type DisplayedMoney = {
+    cents: number;
+    convention: MoneyConvention;
+    start: number;
+    end: number;
+};
+export declare function parseDisplayedCents(text: string, minorUnits?: number): DisplayedMoney | null;
+export declare function formatCentsLike(cents: number, convention: MoneyConvention): string;