flowgrid-sdk 1.2.0 → 1.3.0

package/dist/lib/tracking/core/experiment.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Experiment tracker — A/B testing API.
+ *
+ * Covers the full A/B test lifecycle:
+ *   1. `define()` — register an experiment (one-time admin setup).
+ *   2. `init()`   — initialise the client-side engine (browser only).
+ *   3. `assign()` / `variant()` — get a user's variant.
+ *   4. `exposure()` — log that the user saw the assigned variant.
+ *   5. `conversion()` — log a success metric.
+ *
+ * The browser flow is the simplest:
+ *   ```ts
+ *   await fg.experiments.init([{ experimentId, variants: [...] }]);
+ *   const variant = fg.experiments.variant(experimentId);
+ *   if (variant === "B") renderNewCheckout();
+ *   await fg.experiments.exposure(experimentId, userId, variant);
+ *   // …user converts…
+ *   await fg.experiments.conversion(experimentId, userId, variant, "purchase", 1);
+ *   ```
+ */
+import { Experiment, ExperimentDefinition, ExperimentInitConfig } from "../../features/core/experiment";
+import type { ServerCookieReader } from "../../utils/identity";
+export declare class ExperimentTracker {
+    readonly client: Experiment;
+    constructor(client: Experiment);
+    /**
+     * Define an experiment. Run this once during admin setup.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.define({
+     *   experimentId: "checkout_v2",
+     *   name: "New checkout flow",
+     *   variants: [
+     *     { id: "control", weight: 50 },
+     *     { id: "B", weight: 50 },
+     *   ],
+     * });
+     * ```
+     */
+    define(definition: ExperimentDefinition): Promise<import("../../features/core/experiment").ExperimentResponse>;
+    /**
+     * Initialise the client-side engine (browser only).
+     *
+     * Verifies experiments, performs weighted-random assignment, and
+     * persists assignments in `localStorage` so the same visitor always
+     * sees the same variant.
+     */
+    init(experiments: ExperimentInitConfig[]): Promise<void>;
+    /**
+     * Synchronously read the locally-cached variant assignment.
+     * Returns `null` if no assignment exists. Browser-only.
+     */
+    variant(experimentId: string): string | null;
+    /**
+     * Explicitly assign (or override) a user's variant. Use this for
+     * targeted assignments or admin overrides.
+     */
+    assign(experimentId: string, userId: string, variantId: string, source?: "random" | "targeted" | "override"): Promise<import("../../features/core/experiment").ExperimentResponse>;
+    /**
+     * Record that a user was exposed to (saw / used) their variant.
+     * Call this when the variant is rendered.
+     */
+    exposure(experimentId: string, userId: string, variantId: string): Promise<import("../../features/core/experiment").ExperimentResponse>;
+    /**
+     * Record a conversion against a specific user's variant (server-side).
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.conversion("checkout_v2", "u_1", "B", "purchase", 49.99);
+     * ```
+     */
+    conversion(experimentId: string, userId: string, variantId: string, metricName: string, value?: number): Promise<import("../../features/core/experiment").ExperimentResponse>;
+    /**
+     * Browser-side conversion using the locally-cached variant assignment.
+     * No-op if the visitor has no assignment for this experiment.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.localConversion("checkout_v2", "purchase", 49.99);
+     * ```
+     */
+    localConversion(experimentId: string, metricName?: string, value?: number): Promise<void>;
+    /**
+     * Hydrate assignments from a server cookie reader (Next.js `cookies()`,
+     * Nuxt `useCookie()`, etc.). Call this once per request before reading
+     * `variant()` server-side.
+     *
+     * @example
+     * ```ts
+     * import { cookies } from "next/headers";
+     * fg.experiments.hydrateFromCookies(cookies());
+     * const variant = fg.experiments.variant("checkout_v2");
+     * ```
+     */
+    hydrateFromCookies(reader: ServerCookieReader): void;
+    /**
+     * Hydrate assignments from a raw `Cookie` header (Workers, Bun, Hono, etc.).
+     */
+    hydrateFromCookieHeader(cookieHeader: string | null | undefined): void;
+    /**
+     * Inject assignments resolved server-side. Use when the assignment was
+     * computed without a cookie (e.g. logged-in user fetched from DB).
+     */
+    injectAssignments(assignments: Record<string, string>): void;
+    /**
+     * Snapshot of all known assignments. Useful for SSR payload hand-off.
+     */
+    getAssignments(): Record<string, string>;
+    /**
+     * Build a `Set-Cookie` header value seeding the visitor's browser with
+     * the current assignment map.
+     *
+     * @example
+     * ```ts
+     * res.headers.set("Set-Cookie", fg.experiments.serializeAssignmentCookie());
+     * ```
+     */
+    serializeAssignmentCookie(): string;
+    /** Wipe all locally-cached assignments (cookie + localStorage). */
+    clearAssignments(): void;
+}

package/dist/lib/tracking/core/experiment.js

@@ -0,0 +1,150 @@
+export class ExperimentTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    // ---------------------------------------------------------------------------
+    // SETUP
+    // ---------------------------------------------------------------------------
+    /**
+     * Define an experiment. Run this once during admin setup.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.define({
+     *   experimentId: "checkout_v2",
+     *   name: "New checkout flow",
+     *   variants: [
+     *     { id: "control", weight: 50 },
+     *     { id: "B", weight: 50 },
+     *   ],
+     * });
+     * ```
+     */
+    define(definition) {
+        return this.client.define(definition);
+    }
+    /**
+     * Initialise the client-side engine (browser only).
+     *
+     * Verifies experiments, performs weighted-random assignment, and
+     * persists assignments in `localStorage` so the same visitor always
+     * sees the same variant.
+     */
+    init(experiments) {
+        return this.client.initExperiments(experiments);
+    }
+    // ---------------------------------------------------------------------------
+    // ASSIGNMENT
+    // ---------------------------------------------------------------------------
+    /**
+     * Synchronously read the locally-cached variant assignment.
+     * Returns `null` if no assignment exists. Browser-only.
+     */
+    variant(experimentId) {
+        return this.client.getLocalVariant(experimentId);
+    }
+    /**
+     * Explicitly assign (or override) a user's variant. Use this for
+     * targeted assignments or admin overrides.
+     */
+    assign(experimentId, userId, variantId, source = "targeted") {
+        return this.client.assign({ experimentId, userId, variantId, source });
+    }
+    // ---------------------------------------------------------------------------
+    // EXPOSURE & CONVERSION
+    // ---------------------------------------------------------------------------
+    /**
+     * Record that a user was exposed to (saw / used) their variant.
+     * Call this when the variant is rendered.
+     */
+    exposure(experimentId, userId, variantId) {
+        return this.client.trackExposure(experimentId, userId, variantId);
+    }
+    /**
+     * Record a conversion against a specific user's variant (server-side).
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.conversion("checkout_v2", "u_1", "B", "purchase", 49.99);
+     * ```
+     */
+    conversion(experimentId, userId, variantId, metricName, value = 1) {
+        return this.client.trackConversion({
+            experimentId,
+            userId,
+            variantId,
+            metricName,
+            value,
+        });
+    }
+    /**
+     * Browser-side conversion using the locally-cached variant assignment.
+     * No-op if the visitor has no assignment for this experiment.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.localConversion("checkout_v2", "purchase", 49.99);
+     * ```
+     */
+    localConversion(experimentId, metricName = "conversion", value = 1) {
+        return this.client.trackLocalConversion(experimentId, metricName, value);
+    }
+    // ---------------------------------------------------------------------------
+    // SSR / COOKIE HYDRATION
+    //
+    // The underlying engine mirrors assignments to a `fg_exp_assignments`
+    // cookie so that server-rendered HTML can pick the right variant before
+    // any JS executes. These helpers wire the cookie into common runtimes.
+    // ---------------------------------------------------------------------------
+    /**
+     * Hydrate assignments from a server cookie reader (Next.js `cookies()`,
+     * Nuxt `useCookie()`, etc.). Call this once per request before reading
+     * `variant()` server-side.
+     *
+     * @example
+     * ```ts
+     * import { cookies } from "next/headers";
+     * fg.experiments.hydrateFromCookies(cookies());
+     * const variant = fg.experiments.variant("checkout_v2");
+     * ```
+     */
+    hydrateFromCookies(reader) {
+        this.client.hydrateFromCookies(reader);
+    }
+    /**
+     * Hydrate assignments from a raw `Cookie` header (Workers, Bun, Hono, etc.).
+     */
+    hydrateFromCookieHeader(cookieHeader) {
+        this.client.hydrateFromCookieHeader(cookieHeader);
+    }
+    /**
+     * Inject assignments resolved server-side. Use when the assignment was
+     * computed without a cookie (e.g. logged-in user fetched from DB).
+     */
+    injectAssignments(assignments) {
+        this.client.injectAssignments(assignments);
+    }
+    /**
+     * Snapshot of all known assignments. Useful for SSR payload hand-off.
+     */
+    getAssignments() {
+        return this.client.getAssignments();
+    }
+    /**
+     * Build a `Set-Cookie` header value seeding the visitor's browser with
+     * the current assignment map.
+     *
+     * @example
+     * ```ts
+     * res.headers.set("Set-Cookie", fg.experiments.serializeAssignmentCookie());
+     * ```
+     */
+    serializeAssignmentCookie() {
+        return this.client.serializeAssignmentCookie();
+    }
+    /** Wipe all locally-cached assignments (cookie + localStorage). */
+    clearAssignments() {
+        this.client.clearAssignments();
+    }
+}
+//# sourceMappingURL=experiment.js.map

package/dist/lib/tracking/core/experiment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/experiment.ts"],"names":[],"mappings":"AA2BA,MAAM,OAAO,iBAAiB;IAC5B,YAA4B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAElD,8EAA8E;IAC9E,QAAQ;IACR,8EAA8E;IAE9E;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,UAAgC;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,WAAmC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;OAGG;IACH,OAAO,CAAC,YAAoB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,MAAM,CACJ,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,SAA6C,UAAU;QAEvD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,8EAA8E;IAC9E,wBAAwB;IACxB,8EAA8E;IAE9E;;;OAGG;IACH,QAAQ,CAAC,YAAoB,EAAE,MAAc,EAAE,SAAiB;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CACR,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,UAAkB,EAClB,QAAgB,CAAC;QAEjB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;YACjC,YAAY;YACZ,MAAM;YACN,SAAS;YACT,UAAU;YACV,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,YAAoB,EAAE,aAAqB,YAAY,EAAE,QAAgB,CAAC;QACxF,OAAO,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,8EAA8E;IAC9E,yBAAyB;IACzB,EAAE;IACF,sEAAsE;IACtE,wEAAwE;IACxE,uEAAuE;IACvE,8EAA8E;IAE9E;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,MAA0B;QAC3C,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,YAAuC;QAC7D,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,WAAmC;QACnD,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACH,yBAAyB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,yBAAyB,EAAE,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,gBAAgB;QACd,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;IACjC,CAAC;CACF"}

package/dist/lib/tracking/core/feature.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Feature usage shortcuts.
+ */
+import { TrackFeature } from "../../features/core/track-feature";
+export type FeatureAction = "viewed" | "used" | "completed" | "abandoned";
+export declare class FeatureTracker {
+    readonly client: TrackFeature;
+    constructor(client: TrackFeature);
+    /** Track that a user used a feature. */
+    used(featureId: string, featureName: string, action?: FeatureAction, properties?: Record<string, unknown>): Promise<import("../../features/core/track-feature").FeatureResponse>;
+    /** Create / register a feature event (advanced — see `client.create`). */
+    create(userId: string, action: string, featureName: string, properties?: Record<string, unknown>): Promise<import("../../features/core/track-feature").FeatureResponse>;
+}

package/dist/lib/tracking/core/feature.js

@@ -0,0 +1,14 @@
+export class FeatureTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Track that a user used a feature. */
+    used(featureId, featureName, action = "used", properties) {
+        return this.client.trackUsage({ featureId, featureName, action, properties });
+    }
+    /** Create / register a feature event (advanced — see `client.create`). */
+    create(userId, action, featureName, properties) {
+        return this.client.create({ userId, action, properties: { featureName, ...properties } });
+    }
+}
+//# sourceMappingURL=feature.js.map

package/dist/lib/tracking/core/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/feature.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,cAAc;IACzB,YAA4B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAEpD,wCAAwC;IACxC,IAAI,CAAC,SAAiB,EAAE,WAAmB,EAAE,SAAwB,MAAM,EAAE,UAAoC;QAC/G,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,0EAA0E;IAC1E,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,WAAmB,EAAE,UAAoC;QAC9F,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;CACF"}

package/dist/lib/tracking/core/index.d.ts

@@ -0,0 +1,4 @@
+export { ActivationTracker } from "./activation";
+export { ExperimentTracker } from "./experiment";
+export { FeatureTracker } from "./feature";
+export { PromptTracker } from "./prompt";

package/dist/lib/tracking/core/index.js

@@ -0,0 +1,5 @@
+export { ActivationTracker } from "./activation";
+export { ExperimentTracker } from "./experiment";
+export { FeatureTracker } from "./feature";
+export { PromptTracker } from "./prompt";
+//# sourceMappingURL=index.js.map

package/dist/lib/tracking/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/tracking/core/prompt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AI prompt tracking shortcuts.
+ */
+import { TrackPrompt, PromptFeedbackConfig } from "../../features/core/track-prompt";
+export declare class PromptTracker {
+    readonly client: TrackPrompt;
+    constructor(client: TrackPrompt);
+    /** A user submitted a prompt. */
+    submitted(promptId: string, promptType: string, properties?: Record<string, unknown>): Promise<import("../../features/core/track-prompt").PromptResponse>;
+    /** The model returned a response. */
+    responded(promptId: string, responseTime: number, completed: boolean, properties?: Record<string, unknown>): Promise<import("../../features/core/track-prompt").PromptResponse>;
+    /** User feedback on a prompt response (thumbs up/down etc.). */
+    feedback(promptId: string, feedbackType: PromptFeedbackConfig["feedbackType"], properties?: Record<string, unknown>): Promise<import("../../features/core/track-prompt").PromptResponse>;
+    /** Multi-turn conversation summary. */
+    conversation(conversationId: string, userId: string, turnCount: number, totalDuration: number): Promise<import("../../features/core/track-prompt").PromptResponse>;
+    /** Generic prompt event. */
+    event(eventName: string, properties?: Record<string, unknown>): Promise<import("../../features/core/track-prompt").PromptResponse>;
+}

package/dist/lib/tracking/core/prompt.js

@@ -0,0 +1,26 @@
+export class PromptTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** A user submitted a prompt. */
+    submitted(promptId, promptType, properties) {
+        return this.client.trackSubmission({ promptId, promptType, properties });
+    }
+    /** The model returned a response. */
+    responded(promptId, responseTime, completed, properties) {
+        return this.client.trackResponse({ promptId, responseTime, completed, properties });
+    }
+    /** User feedback on a prompt response (thumbs up/down etc.). */
+    feedback(promptId, feedbackType, properties) {
+        return this.client.trackFeedback({ promptId, feedbackType, properties });
+    }
+    /** Multi-turn conversation summary. */
+    conversation(conversationId, userId, turnCount, totalDuration) {
+        return this.client.trackConversation(conversationId, userId, turnCount, totalDuration);
+    }
+    /** Generic prompt event. */
+    event(eventName, properties = {}) {
+        return this.client.create({ eventName, properties });
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/lib/tracking/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/prompt.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,aAAa;IACxB,YAA4B,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAEnD,iCAAiC;IACjC,SAAS,CAAC,QAAgB,EAAE,UAAkB,EAAE,UAAoC;QAClF,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,qCAAqC;IACrC,SAAS,CAAC,QAAgB,EAAE,YAAoB,EAAE,SAAkB,EAAE,UAAoC;QACxG,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,gEAAgE;IAChE,QAAQ,CAAC,QAAgB,EAAE,YAAkD,EAAE,UAAoC;QACjH,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,uCAAuC;IACvC,YAAY,CAAC,cAAsB,EAAE,MAAc,EAAE,SAAiB,EAAE,aAAqB;QAC3F,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IACzF,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,SAAiB,EAAE,aAAsC,EAAE;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/cart.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cart shortcuts.
+ */
+import { CartTracking } from "../../features/ecommerce/cart";
+import type { Product, Cart } from "../../types";
+export declare class CartTracker {
+    readonly client: CartTracking;
+    constructor(client: CartTracking);
+    /** Add a product to cart. */
+    add(product: Product, quantity?: number, cartId?: string): Promise<import("../../features/ecommerce/cart").CartResponse>;
+    /** Remove a product from cart. */
+    remove(product: Product, quantity?: number, cartId?: string): Promise<import("../../features/ecommerce/cart").CartResponse>;
+    /** Change the quantity of a cart item. */
+    update(product: Product, previousQuantity: number, newQuantity: number, cartId?: string): Promise<import("../../features/ecommerce/cart").CartResponse>;
+    /** Track a cart view. */
+    view(cart: Cart): Promise<import("../../features/ecommerce/cart").CartResponse>;
+}

package/dist/lib/tracking/ecommerce/cart.js

@@ -0,0 +1,22 @@
+export class CartTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Add a product to cart. */
+    add(product, quantity = 1, cartId) {
+        return this.client.addItem({ product, quantity, cartId });
+    }
+    /** Remove a product from cart. */
+    remove(product, quantity = 1, cartId) {
+        return this.client.removeItem({ product, quantity, cartId });
+    }
+    /** Change the quantity of a cart item. */
+    update(product, previousQuantity, newQuantity, cartId) {
+        return this.client.updateItem({ product, previousQuantity, newQuantity, cartId });
+    }
+    /** Track a cart view. */
+    view(cart) {
+        return this.client.view({ cart });
+    }
+}
+//# sourceMappingURL=cart.js.map

package/dist/lib/tracking/ecommerce/cart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/cart.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,WAAW;IACtB,YAA4B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAEpD,6BAA6B;IAC7B,GAAG,CAAC,OAAgB,EAAE,QAAQ,GAAG,CAAC,EAAE,MAAe;QACjD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,kCAAkC;IAClC,MAAM,CAAC,OAAgB,EAAE,QAAQ,GAAG,CAAC,EAAE,MAAe;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,OAAgB,EAAE,gBAAwB,EAAE,WAAmB,EAAE,MAAe;QACrF,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,yBAAyB;IACzB,IAAI,CAAC,IAAU;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/checkout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checkout shortcuts.
+ */
+import { Checkout } from "../../features/ecommerce/checkout";
+import type { Cart, ShippingInfo, PaymentInfo, CheckoutStep } from "../../types";
+export declare class CheckoutTracker {
+    readonly client: Checkout;
+    constructor(client: Checkout);
+    /** Begin checkout for the current cart. */
+    begin(cart: Cart): Promise<import("../../features/ecommerce/checkout").CheckoutResponse>;
+    /** Move to a checkout step. */
+    step(step: CheckoutStep, stepNumber: number, cart: Cart): Promise<import("../../features/ecommerce/checkout").CheckoutResponse>;
+    /** Add shipping info. */
+    shipping(cart: Cart, shipping: ShippingInfo): Promise<import("../../features/ecommerce/checkout").CheckoutResponse>;
+    /** Add payment info. */
+    payment(cart: Cart, payment: PaymentInfo): Promise<import("../../features/ecommerce/checkout").CheckoutResponse>;
+}

package/dist/lib/tracking/ecommerce/checkout.js

@@ -0,0 +1,22 @@
+export class CheckoutTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Begin checkout for the current cart. */
+    begin(cart) {
+        return this.client.begin({ cart });
+    }
+    /** Move to a checkout step. */
+    step(step, stepNumber, cart) {
+        return this.client.step({ step, stepNumber, cart });
+    }
+    /** Add shipping info. */
+    shipping(cart, shipping) {
+        return this.client.addShipping({ cart, shipping });
+    }
+    /** Add payment info. */
+    payment(cart, payment) {
+        return this.client.addPayment({ cart, payment });
+    }
+}
+//# sourceMappingURL=checkout.js.map

package/dist/lib/tracking/ecommerce/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/checkout.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,eAAe;IAC1B,YAA4B,MAAgB;QAAhB,WAAM,GAAN,MAAM,CAAU;IAAG,CAAC;IAEhD,2CAA2C;IAC3C,KAAK,CAAC,IAAU;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC,IAAkB,EAAE,UAAkB,EAAE,IAAU;QACrD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,yBAAyB;IACzB,QAAQ,CAAC,IAAU,EAAE,QAAsB;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,wBAAwB;IACxB,OAAO,CAAC,IAAU,EAAE,OAAoB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/index.d.ts

@@ -0,0 +1,10 @@
+export { ProductTracker } from "./products";
+export { CartTracker } from "./cart";
+export { CheckoutTracker } from "./checkout";
+export { PurchaseTracker } from "./purchases";
+export { RefundTracker } from "./refunds";
+export { PromotionTracker } from "./promotions";
+export { WishlistTracker } from "./wishlist";
+export { SubscriptionTracker } from "./subscriptions";
+export { LTVTracker } from "./ltv";
+export { SearchTracker } from "./search";

package/dist/lib/tracking/ecommerce/index.js

@@ -0,0 +1,11 @@
+export { ProductTracker } from "./products";
+export { CartTracker } from "./cart";
+export { CheckoutTracker } from "./checkout";
+export { PurchaseTracker } from "./purchases";
+export { RefundTracker } from "./refunds";
+export { PromotionTracker } from "./promotions";
+export { WishlistTracker } from "./wishlist";
+export { SubscriptionTracker } from "./subscriptions";
+export { LTVTracker } from "./ltv";
+export { SearchTracker } from "./search";
+//# sourceMappingURL=index.js.map

package/dist/lib/tracking/ecommerce/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/tracking/ecommerce/ltv.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Customer LTV shortcuts.
+ */
+import { CustomerLTV } from "../../features/ecommerce/ltv";
+import type { MoneyValue } from "../../types";
+type LTVSegment = "low" | "medium" | "high" | "vip";
+export declare class LTVTracker {
+    readonly client: CustomerLTV;
+    constructor(client: CustomerLTV);
+    /** Record a customer acquisition cost (CAC). */
+    acquisitionCost(userId: string, cost: MoneyValue, channel: string): Promise<import("../../features/ecommerce/ltv").LTVResponse>;
+    /** Move a user into a different LTV segment. */
+    segment(userId: string, newSegment: LTVSegment): Promise<import("../../features/ecommerce/ltv").LTVResponse>;
+}
+export {};

package/dist/lib/tracking/ecommerce/ltv.js

@@ -0,0 +1,14 @@
+export class LTVTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Record a customer acquisition cost (CAC). */
+    acquisitionCost(userId, cost, channel) {
+        return this.client.recordAcquisitionCost({ userId, cost, channel });
+    }
+    /** Move a user into a different LTV segment. */
+    segment(userId, newSegment) {
+        return this.client.updateSegment(userId, newSegment);
+    }
+}
+//# sourceMappingURL=ltv.js.map

package/dist/lib/tracking/ecommerce/ltv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ltv.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/ltv.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,UAAU;IACrB,YAA4B,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAEnD,gDAAgD;IAChD,eAAe,CAAC,MAAc,EAAE,IAAgB,EAAE,OAAe;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,gDAAgD;IAChD,OAAO,CAAC,MAAc,EAAE,UAAsB;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/products.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Product shortcuts.
+ */
+import { Products } from "../../features/ecommerce/products";
+import type { Product } from "../../types";
+export declare class ProductTracker {
+    readonly client: Products;
+    constructor(client: Products);
+    /** Track a product detail view. */
+    view(product: Pick<Product, "productId" | "name" | "price" | "currency"> & Partial<Product>, properties?: Record<string, unknown>): Promise<import("../../features/ecommerce/products").ProductResponse>;
+    /** Track a product list impression. */
+    impression(listId: string, listName: string, products: Product[]): Promise<import("../../features/ecommerce/products").ProductResponse>;
+    /** Track a click on a product in a list. */
+    click(product: Product, listId: string, position: number): Promise<import("../../features/ecommerce/products").ProductResponse>;
+}

package/dist/lib/tracking/ecommerce/products.js

@@ -0,0 +1,18 @@
+export class ProductTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Track a product detail view. */
+    view(product, properties) {
+        return this.client.view({ ...product, properties });
+    }
+    /** Track a product list impression. */
+    impression(listId, listName, products) {
+        return this.client.impression({ list: { listId, listName, products } });
+    }
+    /** Track a click on a product in a list. */
+    click(product, listId, position) {
+        return this.client.click({ product, listId, position });
+    }
+}
+//# sourceMappingURL=products.js.map

package/dist/lib/tracking/ecommerce/products.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"products.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/products.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,cAAc;IACzB,YAA4B,MAAgB;QAAhB,WAAM,GAAN,MAAM,CAAU;IAAG,CAAC;IAEhD,mCAAmC;IACnC,IAAI,CAAC,OAAsF,EAAE,UAAoC;QAC/H,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,uCAAuC;IACvC,UAAU,CAAC,MAAc,EAAE,QAAgB,EAAE,QAAmB;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,OAAgB,EAAE,MAAc,EAAE,QAAgB;QACtD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/promotions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Promotion shortcuts.
+ */
+import { Promotions } from "../../features/ecommerce/promotions";
+export declare class PromotionTracker {
+    readonly client: Promotions;
+    constructor(client: Promotions);
+    /** A user saw a promotion. */
+    view(promotionId: string, name: string, creative: string, position: string): Promise<import("../../features/ecommerce/promotions").PromotionResponse>;
+    /** A user clicked a promotion. */
+    click(promotionId: string, name: string, creative: string, position: string): Promise<import("../../features/ecommerce/promotions").PromotionResponse>;
+    /** A coupon was applied. */
+    coupon(code: string, orderId: string, discountValue: number, discountType: "percentage" | "fixed", orderValueBefore: number, orderValueAfter: number): Promise<import("../../features/ecommerce/promotions").PromotionResponse>;
+}

package/dist/lib/tracking/ecommerce/promotions.js

@@ -0,0 +1,25 @@
+export class PromotionTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** A user saw a promotion. */
+    view(promotionId, name, creative, position) {
+        return this.client.view({ promotionId, name, creative, position });
+    }
+    /** A user clicked a promotion. */
+    click(promotionId, name, creative, position) {
+        return this.client.click({ promotionId, name, creative, position });
+    }
+    /** A coupon was applied. */
+    coupon(code, orderId, discountValue, discountType, orderValueBefore, orderValueAfter) {
+        return this.client.couponUsed({
+            code,
+            orderId,
+            discountValue,
+            discountType,
+            orderValueBefore,
+            orderValueAfter,
+        });
+    }
+}
+//# sourceMappingURL=promotions.js.map

package/dist/lib/tracking/ecommerce/promotions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotions.js","sourceRoot":"","sources":["../../../../src/lib/tracking/ecommerce/promotions.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,gBAAgB;IAC3B,YAA4B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAElD,8BAA8B;IAC9B,IAAI,CAAC,WAAmB,EAAE,IAAY,EAAE,QAAgB,EAAE,QAAgB;QACxE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,WAAmB,EAAE,IAAY,EAAE,QAAgB,EAAE,QAAgB;QACzE,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,4BAA4B;IAC5B,MAAM,CACJ,IAAY,EACZ,OAAe,EACf,aAAqB,EACrB,YAAoC,EACpC,gBAAwB,EACxB,eAAuB;QAEvB,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;YAC5B,IAAI;YACJ,OAAO;YACP,aAAa;YACb,YAAY;YACZ,gBAAgB;YAChB,eAAe;SAChB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/lib/tracking/ecommerce/purchases.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Purchase shortcuts.
+ */
+import { Purchases } from "../../features/ecommerce/purchases";
+import type { Order } from "../../types";
+export declare class PurchaseTracker {
+    readonly client: Purchases;
+    constructor(client: Purchases);
+    /** Track a completed purchase. */
+    complete(order: Order): Promise<import("../../features/ecommerce/purchases").PurchaseResponse>;
+}