flowgrid-sdk 1.0.0

package/dist/lib/features/analytics/events.d.ts

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview Product Analytics - Custom Event Tracking
+ * @module features/analytics/events
+ *
+ * @description
+ * Track custom events with flexible properties for any user action
+ * or system event. Supports categorization, value tracking, and batching.
+ *
+ * @useCases
+ * - Track button clicks and CTA interactions
+ * - Monitor feature usage and engagement
+ * - Capture form submissions and errors
+ * - Log search queries and results
+ * - Record video/audio playback events
+ *
+ * @metrics
+ * - Event counts by type
+ * - Event trends over time
+ * - Unique users per event
+ * - Event value aggregations
+ * - Event-to-conversion correlation
+ *
+ * @chartData
+ * - Bar chart: Top events by count
+ * - Line chart: Event trends over time
+ * - Heatmap: Events by hour/day
+ * - Sankey: Event flow paths
+ *
+ * @example
+ * ```typescript
+ * const events = new Events(webId, endpoint, apiKey);
+ *
+ * // Track a button click
+ * await events.track({
+ *   eventName: 'cta_clicked',
+ *   category: 'engagement',
+ *   action: 'click',
+ *   label: 'signup_hero'
+ * });
+ *
+ * // Track with value
+ * await events.track({
+ *   eventName: 'video_watched',
+ *   value: 120, // seconds
+ *   properties: { videoId: 'intro-video' }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { ClickEvent, FormEvent, SearchEvent, ErrorEvent, TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
+/**
+ * Configuration for tracking a custom event.
+ */
+export interface EventTrackConfig {
+    /** Event name (required) */
+    eventName: string;
+    /** Event category for grouping */
+    category?: string;
+    /** Event action */
+    action?: string;
+    /** Event label for sub-categorization */
+    label?: string;
+    /** Numeric value associated with event */
+    value?: number;
+    /** Non-interactive event (won't affect bounce rate) */
+    nonInteraction?: boolean;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Batch event tracking configuration.
+ */
+export interface BatchEventConfig {
+    /** Array of events to track */
+    events: EventTrackConfig[];
+}
+/**
+ * Event response from API.
+ */
+export interface EventResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        eventId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Batch event response.
+ */
+export interface BatchEventResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: number;
+        failed: number;
+        eventIds: string[];
+    };
+    timestamp: string;
+}
+/**
+ * Event analytics data for charts.
+ */
+export interface EventAnalyticsData {
+    /** Top events by count */
+    topEvents: Array<{
+        eventName: string;
+        category: string;
+        count: number;
+        uniqueUsers: number;
+        totalValue: number;
+    }>;
+    /** Events time series */
+    timeSeries: TimeSeriesData;
+    /** Events by category */
+    byCategory: Array<{
+        category: string;
+        count: number;
+        percentage: number;
+    }>;
+    /** Summary metrics */
+    summary: {
+        totalEvents: number;
+        uniqueEventTypes: number;
+        eventsPerUser: number;
+        totalValue: number;
+    };
+}
+/**
+ * Events - Track and analyze custom events.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides flexible custom event tracking including:
+ * - Standard event tracking with categories
+ * - Click and interaction tracking
+ * - Form submission tracking
+ * - Search event tracking
+ * - Error and exception logging
+ * - Batch event submission
+ *
+ * @example
+ * ```typescript
+ * const events = new Events(webId, endpoint, apiKey);
+ *
+ * // Track feature usage
+ * await events.track({
+ *   eventName: 'feature_used',
+ *   category: 'features',
+ *   action: 'use',
+ *   label: 'export_pdf',
+ *   properties: { format: 'A4', pages: 5 }
+ * });
+ *
+ * // Get event analytics
+ * const analytics = await events.getAnalytics({ range: 'last7days' });
+ * ```
+ */
+export declare class Events extends FTRPC {
+    /**
+     * Tracks a custom event.
+     *
+     * @param config - Event configuration
+     * @returns Promise resolving to event response
+     *
+     * @example
+     * ```typescript
+     * await events.track({
+     *   eventName: 'upgrade_clicked',
+     *   category: 'monetization',
+     *   action: 'click',
+     *   label: 'pricing_page',
+     *   value: 99.99
+     * });
+     * ```
+     */
+    track(config: EventTrackConfig): Promise<EventResponse>;
+    /**
+     * Tracks multiple events in a single request.
+     *
+     * @param config - Batch configuration with events array
+     * @returns Promise resolving to batch response
+     *
+     * @example
+     * ```typescript
+     * await events.trackBatch({
+     *   events: [
+     *     { eventName: 'step_1_complete', category: 'onboarding' },
+     *     { eventName: 'step_2_complete', category: 'onboarding' },
+     *     { eventName: 'step_3_complete', category: 'onboarding' }
+     *   ]
+     * });
+     * ```
+     */
+    trackBatch(config: BatchEventConfig): Promise<BatchEventResponse>;
+    /**
+     * Tracks a click/interaction event.
+     *
+     * @param config - Click event configuration
+     * @returns Promise resolving to event response
+     *
+     * @example
+     * ```typescript
+     * document.addEventListener('click', (e) => {
+     *   if (e.target.dataset.track) {
+     *     events.trackClick({
+     *       elementId: e.target.id,
+     *       elementText: e.target.textContent,
+     *       targetUrl: e.target.href
+     *     });
+     *   }
+     * });
+     * ```
+     */
+    trackClick(config: ClickEvent): Promise<EventResponse>;
+    /**
+     * Tracks a form submission event.
+     *
+     * @param config - Form event configuration
+     * @returns Promise resolving to event response
+     *
+     * @example
+     * ```typescript
+     * form.addEventListener('submit', async (e) => {
+     *   await events.trackForm({
+     *     formId: 'contact-form',
+     *     formName: 'Contact Us',
+     *     success: true,
+     *     fields: ['name', 'email', 'message'],
+     *     completionTime: 45
+     *   });
+     * });
+     * ```
+     */
+    trackForm(config: FormEvent): Promise<EventResponse>;
+    /**
+     * Tracks a search event.
+     *
+     * @param config - Search event configuration
+     * @returns Promise resolving to event response
+     *
+     * @example
+     * ```typescript
+     * await events.trackSearch({
+     *   query: 'wireless headphones',
+     *   category: 'products',
+     *   resultsCount: 42,
+     *   filters: { brand: 'Sony', priceRange: '100-200' }
+     * });
+     * ```
+     */
+    trackSearch(config: SearchEvent): Promise<EventResponse>;
+    /**
+     * Tracks an error or exception.
+     *
+     * @param config - Error event configuration
+     * @returns Promise resolving to event response
+     *
+     * @example
+     * ```typescript
+     * window.onerror = (message, source, line, col, error) => {
+     *   events.trackError({
+     *     message: message.toString(),
+     *     stack: error?.stack,
+     *     type: error?.name,
+     *     fatal: false,
+     *     context: source
+     *   });
+     * };
+     * ```
+     */
+    trackError(config: ErrorEvent): Promise<EventResponse>;
+    /**
+     * Retrieves event analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @param pagination - Pagination options
+     * @returns Promise resolving to event analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await events.getAnalytics({
+     *   range: 'last7days'
+     * });
+     *
+     * // Bar chart data - top events
+     * const barData = analytics.topEvents.map(e => ({
+     *   x: e.eventName,
+     *   y: e.count
+     * }));
+     *
+     * // Line chart - events over time
+     * const lineData = analytics.timeSeries.data;
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<EventAnalyticsData>;
+}
+export default Events;

package/dist/lib/features/analytics/funnels.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview Product Analytics - Funnel Analysis
+ * @module features/analytics/funnels
+ *
+ * @description
+ * Define and analyze conversion funnels to understand user journeys,
+ * identify drop-off points, and optimize conversion rates.
+ *
+ * @useCases
+ * - Track signup/onboarding completion rates
+ * - Analyze checkout funnel performance
+ * - Identify where users drop off in key flows
+ * - Compare funnel performance across segments
+ * - A/B test different funnel variations
+ *
+ * @metrics
+ * - Step-by-step conversion rates
+ * - Drop-off rates at each step
+ * - Time to complete each step
+ * - Overall funnel conversion rate
+ * - Funnel completion time
+ *
+ * @chartData
+ * - Funnel chart: Step-by-step visualization
+ * - Bar chart: Conversion by step
+ * - Line chart: Funnel performance over time
+ * - Comparison: Funnel variants side-by-side
+ *
+ * @example
+ * ```typescript
+ * const funnels = new Funnels(webId, endpoint, apiKey);
+ *
+ * // Track funnel step
+ * await funnels.trackStep({
+ *   funnelId: 'checkout_funnel',
+ *   step: 'add_payment',
+ *   stepNumber: 3,
+ *   userId: 'user_123'
+ * });
+ *
+ * // Get funnel analysis
+ * const analysis = await funnels.analyze('checkout_funnel');
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { FunnelAnalysis, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Funnel definition configuration.
+ */
+export interface FunnelDefinition {
+    /** Unique funnel identifier */
+    funnelId: string;
+    /** Funnel name for display */
+    name: string;
+    /** Funnel description */
+    description?: string;
+    /** Ordered list of step definitions */
+    steps: Array<{
+        /** Step name */
+        name: string;
+        /** Event(s) that trigger this step */
+        events: string[];
+        /** Step description */
+        description?: string;
+        /** Whether step is optional */
+        optional?: boolean;
+    }>;
+}
+/**
+ * Configuration for tracking a funnel step.
+ */
+export interface FunnelStepConfig {
+    /** Funnel identifier */
+    funnelId: string;
+    /** Step name or event */
+    step: string;
+    /** Step number (1-indexed) */
+    stepNumber: number;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Funnel step response from API.
+ */
+export interface FunnelStepResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        funnelId: string;
+        step: string;
+        tracked: boolean;
+        previousStep?: string;
+        timeFromPrevious?: number;
+    };
+    timestamp: string;
+}
+/**
+ * Funnel analytics data for charts.
+ */
+export interface FunnelAnalyticsData {
+    /** Funnel definition */
+    funnel: FunnelDefinition;
+    /** Analysis results */
+    analysis: FunnelAnalysis;
+    /** Step-by-step data for visualization */
+    visualization: Array<{
+        step: string;
+        entered: number;
+        completed: number;
+        conversionRate: number;
+        dropOffRate: number;
+        avgTime: number;
+    }>;
+    /** Performance over time */
+    trendData: TimeSeriesData;
+}
+/**
+ * Funnel comparison data.
+ */
+export interface FunnelComparisonData {
+    /** Base funnel data */
+    baseline: FunnelAnalyticsData;
+    /** Comparison funnel data */
+    comparison: FunnelAnalyticsData;
+    /** Step-by-step comparison */
+    stepComparison: Array<{
+        step: string;
+        baselineRate: number;
+        comparisonRate: number;
+        difference: number;
+        significant: boolean;
+    }>;
+}
+/**
+ * Funnels - Define and analyze conversion funnels.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides funnel analysis capabilities including:
+ * - Funnel definition and management
+ * - Step-by-step event tracking
+ * - Conversion and drop-off analysis
+ * - Time-to-completion tracking
+ * - Segment-based funnel comparison
+ *
+ * @example
+ * ```typescript
+ * const funnels = new Funnels(webId, endpoint, apiKey);
+ *
+ * // Define a signup funnel
+ * await funnels.define({
+ *   funnelId: 'signup_funnel',
+ *   name: 'User Signup',
+ *   steps: [
+ *     { name: 'Visit Landing', events: ['page_view_landing'] },
+ *     { name: 'Click Signup', events: ['signup_clicked'] },
+ *     { name: 'Submit Form', events: ['signup_submitted'] },
+ *     { name: 'Verify Email', events: ['email_verified'] }
+ *   ]
+ * });
+ *
+ * // Analyze funnel performance
+ * const analysis = await funnels.analyze('signup_funnel', {
+ *   range: 'last30days'
+ * });
+ * ```
+ */
+export declare class Funnels extends FTRPC {
+    /**
+     * Defines a new funnel or updates existing.
+     *
+     * @param config - Funnel definition
+     * @returns Promise resolving to definition response
+     *
+     * @example
+     * ```typescript
+     * await funnels.define({
+     *   funnelId: 'checkout_funnel',
+     *   name: 'Checkout Flow',
+     *   steps: [
+     *     { name: 'View Cart', events: ['view_cart'] },
+     *     { name: 'Begin Checkout', events: ['begin_checkout'] },
+     *     { name: 'Add Shipping', events: ['add_shipping_info'] },
+     *     { name: 'Add Payment', events: ['add_payment_info'] },
+     *     { name: 'Purchase', events: ['purchase'] }
+     *   ]
+     * });
+     * ```
+     */
+    define(config: FunnelDefinition): Promise<FunnelStepResponse>;
+    /**
+     * Tracks a funnel step completion.
+     *
+     * @param config - Funnel step configuration
+     * @returns Promise resolving to step response
+     *
+     * @example
+     * ```typescript
+     * // Track user progressing through checkout
+     * await funnels.trackStep({
+     *   funnelId: 'checkout_funnel',
+     *   step: 'add_shipping_info',
+     *   stepNumber: 3,
+     *   userId: 'user_123',
+     *   properties: { shippingMethod: 'express' }
+     * });
+     * ```
+     */
+    trackStep(config: FunnelStepConfig): Promise<FunnelStepResponse>;
+    /**
+     * Tracks funnel completion.
+     *
+     * @param funnelId - Funnel identifier
+     * @param userId - User who completed
+     * @param properties - Completion properties
+     * @returns Promise resolving to completion response
+     */
+    trackComplete(funnelId: string, userId?: string, properties?: Record<string, unknown>): Promise<FunnelStepResponse>;
+    /**
+     * Tracks funnel abandonment.
+     *
+     * @param funnelId - Funnel identifier
+     * @param lastStep - Last completed step
+     * @param userId - User who abandoned
+     * @param reason - Optional abandonment reason
+     * @returns Promise resolving to abandonment response
+     */
+    trackAbandon(funnelId: string, lastStep: string, userId?: string, reason?: string): Promise<FunnelStepResponse>;
+    /**
+     * Analyzes funnel performance.
+     *
+     * @param funnelId - Funnel identifier
+     * @param filter - Date range filter
+     * @returns Promise resolving to funnel analytics
+     *
+     * @example
+     * ```typescript
+     * const analysis = await funnels.analyze('checkout_funnel', {
+     *   range: 'last7days'
+     * });
+     *
+     * // Funnel visualization data
+     * const funnelData = analysis.visualization.map(step => ({
+     *   name: step.step,
+     *   value: step.entered,
+     *   conversion: step.conversionRate
+     * }));
+     *
+     * // Overall conversion rate
+     * console.log(`Conversion: ${analysis.analysis.overallConversionRate}%`);
+     * ```
+     */
+    analyze(funnelId: string, filter?: DateRangeFilter): Promise<FunnelAnalyticsData>;
+    /**
+     * Compares two funnel periods or segments.
+     *
+     * @param funnelId - Funnel identifier
+     * @param baselineFilter - Baseline period filter
+     * @param comparisonFilter - Comparison period filter
+     * @returns Promise resolving to comparison data
+     *
+     * @example
+     * ```typescript
+     * const comparison = await funnels.compare(
+     *   'checkout_funnel',
+     *   { range: 'last30days' },
+     *   { range: 'last60days' }
+     * );
+     *
+     * // Side-by-side comparison chart
+     * const comparisonData = comparison.stepComparison.map(s => ({
+     *   step: s.step,
+     *   baseline: s.baselineRate,
+     *   comparison: s.comparisonRate
+     * }));
+     * ```
+     */
+    compare(funnelId: string, baselineFilter: DateRangeFilter, comparisonFilter: DateRangeFilter): Promise<FunnelComparisonData>;
+    /**
+     * Lists all defined funnels.
+     *
+     * @returns Promise resolving to funnel list
+     */
+    list(): Promise<FunnelDefinition[]>;
+}
+export default Funnels;