flowgrid-sdk 1.4.1 → 1.5.0

package/dist/lib/flowgrid.d.ts

@@ -31,7 +31,713 @@
  */
 import { FlowGridTransport, FlowGridTransportConfig } from "./client/transport";
 import { IdentityManager } from "./utils/identity";
-import { ActivationTracker, ExperimentTracker, FeatureTracker, PromptTracker, EventTracker, PageViewTracker, SessionTracker, IdentifyTracker, FunnelTracker, RetentionTracker, AttributionTracker, HeatmapTracker, PerformanceTracker, ReplayTracker, ProductTracker, CartTracker, CheckoutTracker, PurchaseTracker, RefundTracker, PromotionTracker, WishlistTracker, SubscriptionTracker, LTVTracker, SearchTracker, EngagementTracker, CohortTracker, ChurnTracker, MonetizationTracker, MultiPathFunnelTracker, SupportTracker, AcquisitionTracker, PathTracker, AlertTracker, SecurityTracker, ForecastingTracker } from "./tracking";
+import type { EngagementTracker, CohortTracker, ChurnTracker, MonetizationTracker, MultiPathFunnelTracker, SupportTracker, AcquisitionTracker, PathTracker, AlertTracker, SecurityTracker, ForecastingTracker } from "./tracking/enterprise";
+import { ActivationTracker, ExperimentTracker, FeatureTracker, PromptTracker } from "./tracking/core";
+import { EventTracker, PageViewTracker, SessionTracker, IdentifyTracker, FunnelTracker, RetentionTracker, AttributionTracker, HeatmapTracker, PerformanceTracker, ReplayTracker } from "./tracking/analytics";
+import { ProductTracker, CartTracker, CheckoutTracker, PurchaseTracker, RefundTracker, PromotionTracker, WishlistTracker, SubscriptionTracker, LTVTracker, SearchTracker } from "./tracking/ecommerce";
+export type FlowGridTrackDomain = "event" | "activation" | "feature" | "prompt" | "experiment" | "ecommerce" | "analytics" | "retention" | "attribution" | "funnel" | "engagement" | "churn" | "monetization" | "support" | "acquisition" | "paths" | "security" | "multiPathFunnels";
+export interface FlowGridTrackOptions {
+    userId?: string;
+    sessionId?: string;
+    /** Force a specific module when an event name is intentionally generic. */
+    domain?: FlowGridTrackDomain;
+}
+/**
+ * Property shapes for every event name the `.track()` router understands.
+ * Required fields are enforced at the call site; extra fields are always
+ * permitted via the `Record<string, unknown>` intersection.
+ */
+export interface FlowGridEventMap {
+    signup_completed: {
+        userId: string;
+        method: string;
+        source?: string;
+    } & Record<string, unknown>;
+    onboarding_step: {
+        userId: string;
+        stepId: string;
+        stepName: string;
+        stepOrder: number;
+        totalSteps: number;
+    } & Record<string, unknown>;
+    onboarding_completed: {
+        userId: string;
+        totalTimeSpent: number;
+        stepsCompleted: number;
+        stepsSkipped?: number;
+    } & Record<string, unknown>;
+    first_action: {
+        userId: string;
+        actionName: string;
+        timeSinceSignup: number;
+    } & Record<string, unknown>;
+    feature_usage: {
+        featureId: string;
+        featureName: string;
+        action?: string;
+    } & Record<string, unknown>;
+    feature_viewed: {
+        featureId: string;
+        featureName: string;
+    } & Record<string, unknown>;
+    feature_used: {
+        featureId: string;
+        featureName: string;
+    } & Record<string, unknown>;
+    feature_completed: {
+        featureId: string;
+        featureName: string;
+    } & Record<string, unknown>;
+    feature_abandoned: {
+        featureId: string;
+        featureName: string;
+    } & Record<string, unknown>;
+    prompt_submitted: {
+        promptId: string;
+        promptType: string;
+    } & Record<string, unknown>;
+    prompt_response: {
+        promptId: string;
+        responseTime: number;
+        completed: boolean;
+    } & Record<string, unknown>;
+    prompt_feedback: {
+        promptId: string;
+        feedbackType: string;
+    } & Record<string, unknown>;
+    prompt_conversation: {
+        conversationId: string;
+        userId: string;
+        turnCount: number;
+        totalDuration: number;
+    } & Record<string, unknown>;
+    experiment_assignment: {
+        experimentId: string;
+        userId: string;
+        variantId: string;
+    } & Record<string, unknown>;
+    experiment_exposure: {
+        experimentId: string;
+        userId: string;
+        variantId: string;
+    } & Record<string, unknown>;
+    experiment_conversion: {
+        experimentId: string;
+        userId: string;
+        variantId: string;
+        metricName: string;
+    } & Record<string, unknown>;
+    click_event: {
+        elementId: string;
+        elementText: string;
+    } & Record<string, unknown>;
+    form_event: {
+        formId: string;
+        formName: string;
+    } & Record<string, unknown>;
+    search_event: {
+        query: string;
+        category: string;
+    } & Record<string, unknown>;
+    error_event: {
+        message: string;
+        type: string;
+    } & Record<string, unknown>;
+    funnel_step: {
+        funnelId: string;
+        step: string;
+        stepNumber: number;
+    } & Record<string, unknown>;
+    funnel_complete: {
+        funnelId: string;
+    } & Record<string, unknown>;
+    funnel_abandon: {
+        funnelId: string;
+        lastStep: string;
+    } & Record<string, unknown>;
+    user_activity: {
+        userId: string;
+    } & Record<string, unknown>;
+    attribution_touchpoint: {
+        userId: string;
+        channel: string;
+    } & Record<string, unknown>;
+    attribution_conversion: {
+        userId: string;
+        conversionType: string;
+    } & Record<string, unknown>;
+    product_view: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    product_impression: {
+        list: Record<string, unknown>;
+    } & Record<string, unknown>;
+    product_click: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+        listId: string;
+        position: number;
+    } & Record<string, unknown>;
+    add_to_cart: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+        quantity: number;
+    } & Record<string, unknown>;
+    remove_from_cart: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    update_cart_item: {
+        product: Record<string, unknown>;
+        previousQuantity: number;
+        newQuantity: number;
+    } & Record<string, unknown>;
+    view_cart: {
+        cart: Record<string, unknown>;
+    } & Record<string, unknown>;
+    begin_checkout: {
+        cart: Record<string, unknown>;
+    } & Record<string, unknown>;
+    checkout_step: {
+        step: string;
+        stepNumber: number;
+        cart: Record<string, unknown>;
+    } & Record<string, unknown>;
+    add_shipping_info: {
+        cart: Record<string, unknown>;
+        shipping: Record<string, unknown>;
+    } & Record<string, unknown>;
+    add_payment_info: {
+        cart: Record<string, unknown>;
+        payment: Record<string, unknown>;
+    } & Record<string, unknown>;
+    purchase: {
+        order: Record<string, unknown>;
+    } & Record<string, unknown>;
+    refund: {
+        orderId: string;
+        refundId: string;
+        amount: number;
+        currency: string;
+        isFullRefund: boolean;
+    } & Record<string, unknown>;
+    refund_requested: {
+        orderId: string;
+    } & Record<string, unknown>;
+    refund_approved: {
+        refundId: string;
+        approvedAmount: number;
+    } & Record<string, unknown>;
+    refund_denied: {
+        refundId: string;
+        reason: string;
+    } & Record<string, unknown>;
+    refund_completed: {
+        refundId: string;
+        processedAmount: number;
+    } & Record<string, unknown>;
+    promotion_view: {
+        promotionId: string;
+        name: string;
+        creative: string;
+        position: number;
+    } & Record<string, unknown>;
+    promotion_click: {
+        promotionId: string;
+        name: string;
+        creative: string;
+        position: number;
+    } & Record<string, unknown>;
+    coupon_used: {
+        code: string;
+        orderId: string;
+        discountValue: number;
+        discountType: string;
+        orderValueBefore: number;
+        orderValueAfter: number;
+    } & Record<string, unknown>;
+    add_to_wishlist: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    remove_from_wishlist: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    view_wishlist: {
+        wishlist: Record<string, unknown>;
+    } & Record<string, unknown>;
+    wishlist_to_cart: {
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    share_wishlist: {
+        wishlistId: string;
+        method: string;
+    } & Record<string, unknown>;
+    subscription_start: {
+        subscriptionId: string;
+        userId: string;
+        plan: string;
+        mrr: Record<string, unknown>;
+        billingCycle: string;
+    } & Record<string, unknown>;
+    subscription_change: {
+        subscriptionId: string;
+        userId: string;
+        previousPlan: string;
+        newPlan: string;
+        previousMrr: Record<string, unknown>;
+        newMrr: Record<string, unknown>;
+        changeType: string;
+    } & Record<string, unknown>;
+    subscription_cancel: {
+        subscriptionId: string;
+        userId: string;
+        plan: string;
+        lostMrr: Record<string, unknown>;
+        immediate: boolean;
+    } & Record<string, unknown>;
+    subscription_renew: {
+        subscriptionId: string;
+        userId: string;
+        mrr: Record<string, unknown>;
+    } & Record<string, unknown>;
+    trial_converted: {
+        subscriptionId: string;
+        userId: string;
+        plan: string;
+        mrr: Record<string, unknown>;
+    } & Record<string, unknown>;
+    trial_expired: {
+        subscriptionId: string;
+        userId: string;
+    } & Record<string, unknown>;
+    record_acquisition_cost: {
+        userId: string;
+        cost: Record<string, unknown>;
+        channel: string;
+    } & Record<string, unknown>;
+    update_customer_segment: {
+        userId: string;
+        newSegment: string;
+    } & Record<string, unknown>;
+    site_search: {
+        query: string;
+        resultsCount: number;
+    } & Record<string, unknown>;
+    search_result_click: {
+        query: string;
+        position: number;
+        productId: string;
+        name: string;
+        price: number;
+        currency: string;
+    } & Record<string, unknown>;
+    search_refinement: {
+        originalQuery: string;
+        refinedQuery: string;
+        refinementType: string;
+    } & Record<string, unknown>;
+    search_suggestion: {
+        partialQuery: string;
+        selectedSuggestion: string;
+        suggestionPosition: number;
+    } & Record<string, unknown>;
+    "engagement.dwell_time": {
+        featureId: string;
+        dwellTimeMs: number;
+    } & Record<string, unknown>;
+    "engagement_dwell_time": {
+        featureId: string;
+        dwellTimeMs: number;
+    } & Record<string, unknown>;
+    "engagement.session_depth": {
+        sessionId: string;
+        pagesVisited: number;
+        featuresUsed: number;
+        actionsTaken: number;
+        durationMs: number;
+    } & Record<string, unknown>;
+    "engagement_session_depth": {
+        sessionId: string;
+        pagesVisited: number;
+        featuresUsed: number;
+        actionsTaken: number;
+        durationMs: number;
+    } & Record<string, unknown>;
+    "engagement.content_consumption": {
+        contentId: string;
+        contentType: string;
+        percentageConsumed: number;
+        timeSpentMs: number;
+    } & Record<string, unknown>;
+    "engagement_content_consumption": {
+        contentId: string;
+        contentType: string;
+        percentageConsumed: number;
+        timeSpentMs: number;
+    } & Record<string, unknown>;
+    "engagement.user_activity": {
+        userId: string;
+        activityType: string;
+        durationMs: number;
+    } & Record<string, unknown>;
+    "engagement_user_activity": {
+        userId: string;
+        activityType: string;
+        durationMs: number;
+    } & Record<string, unknown>;
+    "churn.usage_decay": {
+        userId: string;
+        metric: string;
+        periods: unknown;
+    } & Record<string, unknown>;
+    "churn_usage_decay": {
+        userId: string;
+        metric: string;
+        periods: unknown;
+    } & Record<string, unknown>;
+    "churn.nps": {
+        userId: string;
+        score: number;
+    } & Record<string, unknown>;
+    "churn_nps": {
+        userId: string;
+        score: number;
+    } & Record<string, unknown>;
+    "churn.churn_event": {
+        userId: string;
+        churnType: string;
+    } & Record<string, unknown>;
+    "churn_churn_event": {
+        userId: string;
+        churnType: string;
+    } & Record<string, unknown>;
+    "churn.prevention_action": {
+        userId: string;
+        actionType: string;
+    } & Record<string, unknown>;
+    "churn_prevention_action": {
+        userId: string;
+        actionType: string;
+    } & Record<string, unknown>;
+    "monetization.revenue": {
+        userId: string;
+        amount: number;
+        currency: string;
+        type: string;
+    } & Record<string, unknown>;
+    "monetization_revenue": {
+        userId: string;
+        amount: number;
+        currency: string;
+        type: string;
+    } & Record<string, unknown>;
+    "support.ticket_created": {
+        ticketId: string;
+        userId: string;
+        subject: string;
+        category: string;
+        priority: string;
+        channel: string;
+    } & Record<string, unknown>;
+    "support_ticket_created": {
+        ticketId: string;
+        userId: string;
+        subject: string;
+        category: string;
+        priority: string;
+        channel: string;
+    } & Record<string, unknown>;
+    "support.ticket_updated": {
+        ticketId: string;
+        status: string;
+    } & Record<string, unknown>;
+    "support_ticket_updated": {
+        ticketId: string;
+        status: string;
+    } & Record<string, unknown>;
+    "support.csat": {
+        ticketId: string;
+        userId: string;
+        score: number;
+    } & Record<string, unknown>;
+    "support_csat": {
+        ticketId: string;
+        userId: string;
+        score: number;
+    } & Record<string, unknown>;
+    "support.feature_complaint": {
+        userId: string;
+        featureId: string;
+        complaintType: string;
+        severity: string;
+    } & Record<string, unknown>;
+    "support_feature_complaint": {
+        userId: string;
+        featureId: string;
+        complaintType: string;
+        severity: string;
+    } & Record<string, unknown>;
+    "acquisition.acquired": {
+        userId: string;
+        source: string;
+    } & Record<string, unknown>;
+    "acquisition_acquired": {
+        userId: string;
+        source: string;
+    } & Record<string, unknown>;
+    "acquisition.lifecycle_transition": {
+        userId: string;
+        fromStage: string;
+        toStage: string;
+    } & Record<string, unknown>;
+    "acquisition_lifecycle_transition": {
+        userId: string;
+        fromStage: string;
+        toStage: string;
+    } & Record<string, unknown>;
+    "acquisition.campaign_spend": {
+        campaignId: string;
+        amount: Record<string, unknown>;
+        date: string;
+    } & Record<string, unknown>;
+    "acquisition_campaign_spend": {
+        campaignId: string;
+        amount: Record<string, unknown>;
+        date: string;
+    } & Record<string, unknown>;
+    "paths.transition": {
+        userId: string;
+        fromScreen: string;
+        toScreen: string;
+    } & Record<string, unknown>;
+    "paths_transition": {
+        userId: string;
+        fromScreen: string;
+        toScreen: string;
+    } & Record<string, unknown>;
+    "paths.feature_sequence": {
+        userId: string;
+        feature: string;
+        order: number;
+    } & Record<string, unknown>;
+    "paths_feature_sequence": {
+        userId: string;
+        feature: string;
+        order: number;
+    } & Record<string, unknown>;
+    "security.login_attempt": {
+        userId: string;
+        success: boolean;
+    } & Record<string, unknown>;
+    "security_login_attempt": {
+        userId: string;
+        success: boolean;
+    } & Record<string, unknown>;
+    "security.role_change": {
+        userId: string;
+        changedBy: string;
+        previousRole: string;
+        newRole: string;
+    } & Record<string, unknown>;
+    "security_role_change": {
+        userId: string;
+        changedBy: string;
+        previousRole: string;
+        newRole: string;
+    } & Record<string, unknown>;
+    "security.permission_change": {
+        userId: string;
+        changedBy: string;
+        permission: string;
+        action: string;
+    } & Record<string, unknown>;
+    "security_permission_change": {
+        userId: string;
+        changedBy: string;
+        permission: string;
+        action: string;
+    } & Record<string, unknown>;
+    "security.data_access": {
+        userId: string;
+        resourceType: string;
+        accessType: string;
+    } & Record<string, unknown>;
+    "security_data_access": {
+        userId: string;
+        resourceType: string;
+        accessType: string;
+    } & Record<string, unknown>;
+    "security.compliance_event": {
+        userId: string;
+        eventType: string;
+    } & Record<string, unknown>;
+    "security_compliance_event": {
+        userId: string;
+        eventType: string;
+    } & Record<string, unknown>;
+    "multi_path_funnels.track_step": {
+        funnelId: string;
+        step: string;
+        userId: string;
+    } & Record<string, unknown>;
+    "multi_path_funnels_track_step": {
+        funnelId: string;
+        step: string;
+        userId: string;
+    } & Record<string, unknown>;
+    "multi_path_funnels.track_micro_conversion": {
+        conversionId: string;
+        userId: string;
+    } & Record<string, unknown>;
+    "multi_path_funnels_track_micro_conversion": {
+        conversionId: string;
+        userId: string;
+    } & Record<string, unknown>;
+}
+/** Union of every event name the `.track()` router recognises. */
+export type FlowGridEventName = keyof FlowGridEventMap;
+type FlowGridKnownTrackFields = Partial<{
+    userId: string;
+    sessionId: string;
+    method: string;
+    source: string;
+    featureId: string;
+    featureName: string;
+    action: string;
+    promptId: string;
+    promptType: string;
+    responseTime: number;
+    completed: boolean;
+    feedbackType: string;
+    conversationId: string;
+    turnCount: number;
+    totalDuration: number;
+    experimentId: string;
+    variantId: string;
+    variant: string;
+    metricName: string;
+    value: number;
+    elementId: string;
+    elementText: string;
+    formId: string;
+    formName: string;
+    query: string;
+    category: string;
+    message: string;
+    type: string;
+    funnelId: string;
+    step: string;
+    stepNumber: number;
+    lastStep: string;
+    channel: string;
+    conversionType: string;
+    list: Record<string, unknown>;
+    product: Record<string, unknown>;
+    productId: string;
+    name: string;
+    price: number;
+    currency: string;
+    position: number;
+    quantity: number;
+    previousQuantity: number;
+    newQuantity: number;
+    cart: Record<string, unknown>;
+    shipping: Record<string, unknown>;
+    payment: Record<string, unknown>;
+    order: Record<string, unknown>;
+    orderId: string;
+    refundId: string;
+    amount: unknown;
+    approvedAmount: number;
+    processedAmount: number;
+    reason: string;
+    promotionId: string;
+    creative: string;
+    code: string;
+    discountValue: number;
+    discountType: string;
+    orderValueBefore: number;
+    orderValueAfter: number;
+    wishlist: Record<string, unknown>;
+    wishlistId: string;
+    subscriptionId: string;
+    plan: string;
+    mrr: Record<string, unknown>;
+    billingCycle: string;
+    previousPlan: string;
+    newPlan: string;
+    previousMrr: Record<string, unknown>;
+    newMrr: Record<string, unknown>;
+    changeType: string;
+    lostMrr: Record<string, unknown>;
+    cost: Record<string, unknown>;
+    newSegment: string;
+    resultsCount: number;
+    originalQuery: string;
+    refinedQuery: string;
+    refinementType: string;
+    partialQuery: string;
+    selectedSuggestion: string;
+    suggestionPosition: number;
+    dwellTimeMs: number;
+    pagesVisited: number;
+    featuresUsed: number;
+    actionsTaken: number;
+    durationMs: number;
+    contentId: string;
+    contentType: string;
+    percentageConsumed: number;
+    timeSpentMs: number;
+    metric: string;
+    periods: unknown;
+    score: number;
+    churnType: string;
+    actionType: string;
+    activityType: string;
+    ticketId: string;
+    subject: string;
+    priority: string;
+    status: string;
+    complaintType: string;
+    severity: string;
+    fromStage: string;
+    toStage: string;
+    campaignId: string;
+    date: string;
+    fromScreen: string;
+    toScreen: string;
+    feature: string;
+    success: boolean;
+    isFullRefund: boolean;
+    immediate: boolean;
+    changedBy: string;
+    previousRole: string;
+    newRole: string;
+    permission: string;
+    resourceType: string;
+    accessType: string;
+    eventType: string;
+    conversionId: string;
+}>;
+export type FlowGridTrackProperties = Record<string, unknown> & FlowGridKnownTrackFields;
 /** Granular auto-instrumentation toggles. */
 export interface AutoTrackOptions {
     sessions?: boolean;
@@ -137,6 +843,13 @@ export declare class FlowGrid {
     static init(config: FlowGridInitConfig): FlowGrid;
     /** Returns the singleton created by {@link FlowGrid.init}, if any. */
     static instance(): FlowGrid | null;
+    /**
+     * Await the enterprise feature chunk. Call this before accessing any
+     * enterprise namespace (`fg.engagement`, `fg.churn`, etc.) if you need
+     * guaranteed availability rather than relying on the background pre-fetch
+     * started by `init()`.
+     */
+    static loadEnterprise(): Promise<void>;
     /**
      * Reset the singleton — primarily for tests / hot-reload. Tears down any
      * active auto-instrumentation.
@@ -173,6 +886,7 @@ export declare class FlowGrid {
     get ltv(): LTVTracker;
     get search(): SearchTracker;
     get subscriptions(): SubscriptionTracker;
+    private _requireEnterprise;
     get engagement(): EngagementTracker;
     get cohorts(): CohortTracker;
     get churn(): ChurnTracker;
@@ -187,17 +901,27 @@ export declare class FlowGrid {
     static setConsent: typeof FlowGridTransport.setConsent;
     static hasConsent: typeof FlowGridTransport.hasConsent;
     /**
-     * Track a custom event.
+     * Track a semantic event. The `eventName` must be one of the recognised
+     * {@link FlowGridEventName} literals — TypeScript will error on unknown
+     * names and narrow `properties` to the required shape for that event.
      *
      * @example
      * ```ts
-     * fg.track("signup_completed", { plan: "pro" });
+     * fg.track("signup_completed", { userId: "u_1", method: "google" });
+     * fg.track("add_to_cart", { productId: "sku_1", name: "Tee", price: 29, currency: "USD", quantity: 1 });
      * ```
      */
-    track(eventName: string, properties?: Record<string, unknown>, options?: {
-        userId?: string;
-        sessionId?: string;
-    }): Promise<import("./features/analytics").EventResponse>;
+    track<E extends FlowGridEventName>(eventName: E, properties: FlowGridEventMap[E], options?: FlowGridTrackOptions): unknown;
+    private withTrackContext;
+    private requireTrackProperties;
+    private dispatchTrack;
+    private dispatchActivationTrack;
+    private dispatchFeatureTrack;
+    private dispatchPromptTrack;
+    private dispatchExperimentTrack;
+    private dispatchAnalyticsTrack;
+    private dispatchEcommerceTrack;
+    private dispatchEnterpriseTrack;
     /**
      * Record an experiment exposure for a user.
      *
@@ -211,7 +935,7 @@ export declare class FlowGrid {
     experiment(experimentId: string, options: {
         variant: string;
         userId: string;
-    }): Promise<import("./features/core").ExperimentResponse>;
+    }): Promise<import("..").ExperimentResponse>;
     /**
      * Identify a user.
      *
@@ -220,7 +944,7 @@ export declare class FlowGrid {
      * fg.identifyUser("u_1", { plan: "pro", email: "alice@example.com" });
      * ```
      */
-    identifyUser(userId: string, traits?: Record<string, unknown>, anonymousId?: string): Promise<import("./features/analytics").IdentifyResponse>;
+    identifyUser(userId: string, traits?: Record<string, unknown>, anonymousId?: string): Promise<import("..").IdentifyResponse>;
     /**
      * Track a page view. Auto-detects URL/path/title/referrer in the browser.
      *
@@ -235,7 +959,7 @@ export declare class FlowGrid {
         referrer?: string;
         userId?: string;
         sessionId?: string;
-    }): Promise<import("./features/analytics").PageViewResponse>;
+    }): Promise<import("..").PageViewResponse>;
     /**
      * Enable browser-side auto-instrumentation in a single call. Subscribes to:
      *