flowgrid-sdk 1.2.1 → 1.4.1

package/dist/lib/tracking/analytics/identify.js

@@ -0,0 +1,22 @@
+export class IdentifyTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Identify a user with traits. */
+    user(userId, traits, anonymousId) {
+        return this.client.user({ userId, anonymousId, traits: traits });
+    }
+    /** Update traits on an existing user. */
+    updateTraits(userId, traits) {
+        return this.client.updateTraits(userId, traits);
+    }
+    /** Alias an anonymous ID to a known user ID. */
+    alias(previousId, userId) {
+        return this.client.alias({ previousId, userId });
+    }
+    /** Associate a user with a group/company. */
+    group(userId, groupId, traits) {
+        return this.client.group({ userId, groupId, traits: traits });
+    }
+}
+//# sourceMappingURL=identify.js.map

package/dist/lib/tracking/analytics/identify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/identify.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,eAAe;IAC1B,YAA4B,MAAgB;QAAhB,WAAM,GAAN,MAAM,CAAU;IAAG,CAAC;IAEhD,mCAAmC;IACnC,IAAI,CAAC,MAAc,EAAE,MAAgC,EAAE,WAAoB;QACzE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,yCAAyC;IACzC,YAAY,CAAC,MAAc,EAAE,MAA+B;QAC1D,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,gDAAgD;IAChD,KAAK,CAAC,UAAkB,EAAE,MAAc;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,MAAc,EAAE,OAAe,EAAE,MAAgC;QACrE,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;CACF"}

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

@@ -0,0 +1,10 @@
+export { EventTracker } from "./events";
+export { PageViewTracker } from "./page-views";
+export { SessionTracker } from "./sessions";
+export { IdentifyTracker } from "./identify";
+export { FunnelTracker } from "./funnels";
+export { RetentionTracker } from "./retention";
+export { AttributionTracker } from "./attribution";
+export { HeatmapTracker } from "./heatmaps";
+export { PerformanceTracker } from "./performance";
+export { ReplayTracker } from "./replay";

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

@@ -0,0 +1,11 @@
+export { EventTracker } from "./events";
+export { PageViewTracker } from "./page-views";
+export { SessionTracker } from "./sessions";
+export { IdentifyTracker } from "./identify";
+export { FunnelTracker } from "./funnels";
+export { RetentionTracker } from "./retention";
+export { AttributionTracker } from "./attribution";
+export { HeatmapTracker } from "./heatmaps";
+export { PerformanceTracker } from "./performance";
+export { ReplayTracker } from "./replay";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/tracking/analytics/page-views.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Page view shortcuts. Browser fields auto-detected when available.
+ */
+import { PageViews } from "../../features/analytics/page-views";
+export declare class PageViewTracker {
+    readonly client: PageViews;
+    constructor(client: PageViews);
+    /**
+     * Track a page view. With no args, auto-detects from `window`/`document`.
+     * Pass a path or full URL to override.
+     */
+    view(pathOrUrl?: string, properties?: Record<string, unknown>, opts?: {
+        title?: string;
+        referrer?: string;
+        userId?: string;
+        sessionId?: string;
+    }): Promise<import("../../features/analytics/page-views").PageViewResponse>;
+    /** Record scroll depth (0-100). */
+    scroll(path: string, scrollDepth: number, timeAtDepth?: number): Promise<import("../../features/analytics/page-views").PageViewResponse>;
+    /** Record time spent on a page (seconds). */
+    time(path: string, duration: number): Promise<import("../../features/analytics/page-views").PageViewResponse>;
+    /** Record page exit. */
+    exit(path: string, duration: number, scrollDepth: number): Promise<import("../../features/analytics/page-views").PageViewResponse>;
+    /** Auto-track SPA route changes, scroll-depth thresholds, and time-on-page. */
+    autoTrack(options?: {
+        userId?: string;
+        sessionId?: string;
+    }): import("../../utils/browser").Teardown;
+}

package/dist/lib/tracking/analytics/page-views.js

@@ -0,0 +1,50 @@
+function browserDefaults() {
+    const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+    return {
+        url: isBrowser ? window.location.href : "",
+        path: isBrowser ? window.location.pathname : "",
+        title: isBrowser ? document.title : undefined,
+        referrer: isBrowser ? document.referrer : undefined,
+    };
+}
+export class PageViewTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Track a page view. With no args, auto-detects from `window`/`document`.
+     * Pass a path or full URL to override.
+     */
+    view(pathOrUrl, properties, opts) {
+        const d = browserDefaults();
+        const isFullUrl = pathOrUrl && /^https?:\/\//i.test(pathOrUrl);
+        const url = isFullUrl ? pathOrUrl : d.url;
+        const path = isFullUrl ? new URL(pathOrUrl).pathname : (pathOrUrl ?? d.path);
+        return this.client.track({
+            url,
+            path,
+            title: opts?.title ?? d.title,
+            referrer: opts?.referrer ?? d.referrer,
+            userId: opts?.userId,
+            sessionId: opts?.sessionId,
+            properties,
+        });
+    }
+    /** Record scroll depth (0-100). */
+    scroll(path, scrollDepth, timeAtDepth) {
+        return this.client.trackScrollDepth({ path, scrollDepth, timeAtDepth });
+    }
+    /** Record time spent on a page (seconds). */
+    time(path, duration) {
+        return this.client.trackTimeOnPage({ path, duration });
+    }
+    /** Record page exit. */
+    exit(path, duration, scrollDepth) {
+        return this.client.trackExit(path, duration, scrollDepth);
+    }
+    /** Auto-track SPA route changes, scroll-depth thresholds, and time-on-page. */
+    autoTrack(options) {
+        return this.client.autoTrack(options);
+    }
+}
+//# sourceMappingURL=page-views.js.map

package/dist/lib/tracking/analytics/page-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-views.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/page-views.ts"],"names":[],"mappings":"AAKA,SAAS,eAAe;IACtB,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,CAAC;IACnF,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAC1C,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;QAC/C,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAC7C,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,eAAe;IAC1B,YAA4B,MAAiB;QAAjB,WAAM,GAAN,MAAM,CAAW;IAAG,CAAC;IAEjD;;;OAGG;IACH,IAAI,CACF,SAAkB,EAClB,UAAoC,EACpC,IAAiF;QAEjF,MAAM,CAAC,GAAG,eAAe,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,SAAS,IAAI,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,SAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3C,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YACvB,GAAG;YACH,IAAI;YACJ,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC,KAAK;YAC7B,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC,CAAC,QAAQ;YACtC,MAAM,EAAE,IAAI,EAAE,MAAM;YACpB,SAAS,EAAE,IAAI,EAAE,SAAS;YAC1B,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IACnC,MAAM,CAAC,IAAY,EAAE,WAAmB,EAAE,WAAoB;QAC5D,OAAO,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,IAAY,EAAE,QAAgB;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,IAAY,EAAE,QAAgB,EAAE,WAAmB;QACtD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC5D,CAAC;IAED,+EAA+E;IAC/E,SAAS,CAAC,OAAiD;QACzD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/lib/tracking/analytics/performance.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Performance shortcuts.
+ */
+import { PerformanceTracking } from "../../features/analytics/performance";
+type ResourceType = "script" | "stylesheet" | "image" | "font" | "xhr" | "fetch" | "other";
+export declare class PerformanceTracker {
+    readonly client: PerformanceTracking;
+    constructor(client: PerformanceTracking);
+    /** Report Core Web Vitals (LCP/FID/CLS/INP/TTFB). */
+    webVitals(pageUrl: string, vitals: Record<string, number>): Promise<import("../../features/analytics/performance").PerformanceResponse>;
+    /** Report page-load timing. */
+    pageLoad(pageUrl: string, timings: Record<string, number>): Promise<import("../../features/analytics/performance").PerformanceResponse>;
+    /** Report a single resource load. */
+    resource(pageUrl: string, resourceUrl: string, resourceType: ResourceType, duration: number): Promise<import("../../features/analytics/performance").PerformanceResponse>;
+    /** Auto-collect Core Web Vitals + navigation timing from the browser. */
+    autoTrack(options?: {
+        userId?: string;
+        resources?: boolean;
+        minDuration?: number;
+    }): import("../../utils/browser").Teardown;
+}
+export {};

package/dist/lib/tracking/analytics/performance.js

@@ -0,0 +1,22 @@
+export class PerformanceTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Report Core Web Vitals (LCP/FID/CLS/INP/TTFB). */
+    webVitals(pageUrl, vitals) {
+        return this.client.trackWebVitals({ pageUrl, ...vitals });
+    }
+    /** Report page-load timing. */
+    pageLoad(pageUrl, timings) {
+        return this.client.trackPageLoad({ pageUrl, ...timings });
+    }
+    /** Report a single resource load. */
+    resource(pageUrl, resourceUrl, resourceType, duration) {
+        return this.client.trackResource({ pageUrl, resourceUrl, resourceType, duration });
+    }
+    /** Auto-collect Core Web Vitals + navigation timing from the browser. */
+    autoTrack(options) {
+        return this.client.autoTrack(options);
+    }
+}
+//# sourceMappingURL=performance.js.map

package/dist/lib/tracking/analytics/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/performance.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,kBAAkB;IAC7B,YAA4B,MAA2B;QAA3B,WAAM,GAAN,MAAM,CAAqB;IAAG,CAAC;IAE3D,qDAAqD;IACrD,SAAS,CAAC,OAAe,EAAE,MAA8B;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,+BAA+B;IAC/B,QAAQ,CAAC,OAAe,EAAE,OAA+B;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,qCAAqC;IACrC,QAAQ,CAAC,OAAe,EAAE,WAAmB,EAAE,YAA0B,EAAE,QAAgB;QACzF,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,yEAAyE;IACzE,SAAS,CAAC,OAAwE;QAChF,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/lib/tracking/analytics/replay.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session Replay shortcut wrapper.
+ */
+import { SessionReplay, type SessionReplayFlushMetadata, type SessionReplayFlushReason, type SessionReplayOptions, type SessionReplayStatus } from "../../features/analytics/replay";
+import type { Teardown } from "../../utils/browser";
+export declare class ReplayTracker {
+    readonly client: SessionReplay;
+    constructor(client: SessionReplay);
+    /**
+     * Start recording the current page. Returns a teardown that stops capture
+     * and flushes the final buffer.
+     *
+     * @example
+     * ```ts
+     * const stop = await fg.replay.start({ sampleRate: 1.0, maskAllInputs: true });
+     * ```
+     */
+    start(options?: SessionReplayOptions): Promise<Teardown>;
+    /** Enable replay and start recording immediately. */
+    enable(options?: SessionReplayOptions): Promise<Teardown>;
+    /** Disable replay and stop any active recorder. */
+    disable(): void;
+    /** Stop the active recorder and flush a final chunk. */
+    stop(reason?: SessionReplayFlushReason): void;
+    /** Flush buffered events without stopping recording. */
+    flush(reason?: SessionReplayFlushReason): Promise<void>;
+    /** Bind a known user ID to subsequent replay chunks. */
+    identify(userId: string): void;
+    /** Read recorder lifecycle and health state. */
+    status(): SessionReplayStatus;
+    /** Send a pre-recorded rrweb chunk for custom recorder integrations. */
+    sendChunk(sessionId: string, events: unknown[], options?: Parameters<SessionReplay["sendChunk"]>[2]): Promise<void>;
+}
+export type { SessionReplayFlushMetadata, SessionReplayFlushReason, SessionReplayOptions, SessionReplayStatus };

package/dist/lib/tracking/analytics/replay.js

@@ -0,0 +1,46 @@
+export class ReplayTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Start recording the current page. Returns a teardown that stops capture
+     * and flushes the final buffer.
+     *
+     * @example
+     * ```ts
+     * const stop = await fg.replay.start({ sampleRate: 1.0, maskAllInputs: true });
+     * ```
+     */
+    start(options) {
+        return this.client.start(options ?? {});
+    }
+    /** Enable replay and start recording immediately. */
+    enable(options) {
+        return this.client.enable(options ?? {});
+    }
+    /** Disable replay and stop any active recorder. */
+    disable() {
+        this.client.disable();
+    }
+    /** Stop the active recorder and flush a final chunk. */
+    stop(reason) {
+        this.client.stop(reason);
+    }
+    /** Flush buffered events without stopping recording. */
+    flush(reason) {
+        return this.client.flush(reason ?? "manual");
+    }
+    /** Bind a known user ID to subsequent replay chunks. */
+    identify(userId) {
+        this.client.identify(userId);
+    }
+    /** Read recorder lifecycle and health state. */
+    status() {
+        return this.client.getStatus();
+    }
+    /** Send a pre-recorded rrweb chunk for custom recorder integrations. */
+    sendChunk(sessionId, events, options) {
+        return this.client.sendChunk(sessionId, events, options ?? {});
+    }
+}
+//# sourceMappingURL=replay.js.map

package/dist/lib/tracking/analytics/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/replay.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,aAAa;IACxB,YAA4B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAErD;;;;;;;;OAQG;IACH,KAAK,CAAC,OAA8B;QAClC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,qDAAqD;IACrD,MAAM,CAAC,OAA8B;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,mDAAmD;IACnD,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,MAAiC;QACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,MAAiC;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,wDAAwD;IACxD,QAAQ,CAAC,MAAc;QACrB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,gDAAgD;IAChD,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,SAAS,CACP,SAAiB,EACjB,MAAiB,EACjB,OAAmD;QAEnD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/lib/tracking/analytics/retention.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Retention shortcuts.
+ */
+import { Retention } from "../../features/analytics/retention";
+export declare class RetentionTracker {
+    readonly client: Retention;
+    constructor(client: Retention);
+    /** Record that a user was active. */
+    active(userId: string, properties?: Record<string, unknown>): Promise<import("../../features/analytics/retention").ActivityResponse>;
+}

package/dist/lib/tracking/analytics/retention.js

@@ -0,0 +1,10 @@
+export class RetentionTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Record that a user was active. */
+    active(userId, properties) {
+        return this.client.trackActivity({ userId, properties });
+    }
+}
+//# sourceMappingURL=retention.js.map

package/dist/lib/tracking/analytics/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/retention.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,gBAAgB;IAC3B,YAA4B,MAAiB;QAAjB,WAAM,GAAN,MAAM,CAAW;IAAG,CAAC;IAEjD,qCAAqC;IACrC,MAAM,CAAC,MAAc,EAAE,UAAoC;QACzD,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/lib/tracking/analytics/sessions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Session lifecycle shortcuts.
+ */
+import { Sessions } from "../../features/analytics/sessions";
+export declare class SessionTracker {
+    readonly client: Sessions;
+    constructor(client: Sessions);
+    /** Start a new session. */
+    start(opts?: Parameters<Sessions["start"]>[0]): Promise<import("../../features/analytics/sessions").SessionResponse>;
+    /** Update an active session with new properties. */
+    update(sessionId: string, properties: Record<string, unknown>): Promise<import("../../features/analytics/sessions").SessionResponse>;
+    /** End a session. */
+    end(sessionId: string): Promise<import("../../features/analytics/sessions").SessionEndResponse>;
+    /** Heartbeat to keep a session alive. */
+    heartbeat(sessionId: string): Promise<import("../../features/analytics/sessions").SessionResponse>;
+    /** Auto-manage browser session lifecycle (start, heartbeat, end on pagehide). */
+    autoTrack(config?: Parameters<Sessions["autoTrack"]>[0], options?: {
+        heartbeatMs?: number;
+    }): import("../../utils/browser").Teardown;
+}

package/dist/lib/tracking/analytics/sessions.js

@@ -0,0 +1,26 @@
+export class SessionTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Start a new session. */
+    start(opts) {
+        return this.client.start(opts);
+    }
+    /** Update an active session with new properties. */
+    update(sessionId, properties) {
+        return this.client.update(sessionId, properties);
+    }
+    /** End a session. */
+    end(sessionId) {
+        return this.client.end(sessionId);
+    }
+    /** Heartbeat to keep a session alive. */
+    heartbeat(sessionId) {
+        return this.client.heartbeat(sessionId);
+    }
+    /** Auto-manage browser session lifecycle (start, heartbeat, end on pagehide). */
+    autoTrack(config, options) {
+        return this.client.autoTrack(config, options);
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/lib/tracking/analytics/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../../src/lib/tracking/analytics/sessions.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,cAAc;IACzB,YAA4B,MAAgB;QAAhB,WAAM,GAAN,MAAM,CAAU;IAAG,CAAC;IAEhD,2BAA2B;IAC3B,KAAK,CAAC,IAAuC;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,SAAiB,EAAE,UAAmC;QAC3D,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC;IAED,qBAAqB;IACrB,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,yCAAyC;IACzC,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,iFAAiF;IACjF,SAAS,CAAC,MAA6C,EAAE,OAAkC;QACzF,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;CACF"}

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

@@ -0,0 +1,23 @@
+/**
+ * Activation shortcuts — one helper per event, positional args, sensible defaults.
+ * Underlying class accessible via `.client`.
+ */
+import { Activation } from "../../features/core/activation";
+export declare class ActivationTracker {
+    readonly client: Activation;
+    constructor(client: Activation);
+    /** New user signup. */
+    signup(userId: string, method: string, source?: string, props?: Record<string, unknown>): Promise<import("../../features/core/activation").ActivationResponse>;
+    /** Step in an onboarding flow (e.g. `step 2 of 5`). */
+    onboardingStep(userId: string, stepId: string, stepName: string, stepOrder: number, totalSteps: number, extra?: {
+        skipped?: boolean;
+        timeSpent?: number;
+        properties?: Record<string, unknown>;
+    }): Promise<import("../../features/core/activation").ActivationResponse>;
+    /** All onboarding steps finished. */
+    onboardingComplete(userId: string, totalTimeSpent: number, stepsCompleted: number, stepsSkipped?: number): Promise<import("../../features/core/activation").ActivationResponse>;
+    /** First meaningful action after signup ("aha" moment). */
+    firstAction(userId: string, actionName: string, timeSinceSignup: number, properties?: Record<string, unknown>): Promise<import("../../features/core/activation").ActivationResponse>;
+    /** Generic activation event. */
+    event(eventName: string, properties?: Record<string, unknown>): Promise<import("../../features/core/activation").ActivationResponse>;
+}

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

@@ -0,0 +1,33 @@
+export class ActivationTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /** New user signup. */
+    signup(userId, method, source, props) {
+        return this.client.trackSignup(userId, method, source, props);
+    }
+    /** Step in an onboarding flow (e.g. `step 2 of 5`). */
+    onboardingStep(userId, stepId, stepName, stepOrder, totalSteps, extra) {
+        return this.client.trackOnboardingStep({
+            userId,
+            stepId,
+            stepName,
+            stepOrder,
+            totalSteps,
+            ...extra,
+        });
+    }
+    /** All onboarding steps finished. */
+    onboardingComplete(userId, totalTimeSpent, stepsCompleted, stepsSkipped = 0) {
+        return this.client.completeOnboarding(userId, totalTimeSpent, stepsCompleted, stepsSkipped);
+    }
+    /** First meaningful action after signup ("aha" moment). */
+    firstAction(userId, actionName, timeSinceSignup, properties) {
+        return this.client.trackFirstAction({ userId, actionName, timeSinceSignup, properties });
+    }
+    /** Generic activation event. */
+    event(eventName, properties = {}) {
+        return this.client.create({ eventName, properties });
+    }
+}
+//# sourceMappingURL=activation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"activation.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/activation.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,iBAAiB;IAC5B,YAA4B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAElD,uBAAuB;IACvB,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,MAAe,EAAE,KAA+B;QACrF,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IAED,uDAAuD;IACvD,cAAc,CACZ,MAAc,EACd,MAAc,EACd,QAAgB,EAChB,SAAiB,EACjB,UAAkB,EAClB,KAAuF;QAEvF,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC;YACrC,MAAM;YACN,MAAM;YACN,QAAQ;YACR,SAAS;YACT,UAAU;YACV,GAAG,KAAK;SACT,CAAC,CAAC;IACL,CAAC;IAED,qCAAqC;IACrC,kBAAkB,CAAC,MAAc,EAAE,cAAsB,EAAE,cAAsB,EAAE,YAAY,GAAG,CAAC;QACjG,OAAO,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;IAC9F,CAAC;IAED,2DAA2D;IAC3D,WAAW,CAAC,MAAc,EAAE,UAAkB,EAAE,eAAuB,EAAE,UAAoC;QAC3G,OAAO,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,gCAAgC;IAChC,KAAK,CAAC,SAAiB,EAAE,aAAsC,EAAE;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;CAEF"}

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;
+}