flowgrid-sdk 1.2.0 → 1.3.0

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

@@ -47,7 +47,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { ClickEvent, FormEvent, SearchEvent, ErrorEvent, TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
+import { ClickEvent, FormEvent, SearchEvent, ErrorEvent, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking a custom event.
  */
@@ -157,9 +157,6 @@ export interface EventAnalyticsData {
  *   label: 'export_pdf',
  *   properties: { format: 'A4', pages: 5 }
  * });
- *
- * // Get event analytics
- * const analytics = await events.getAnalytics({ range: 'last7days' });
  * ```
  */
 export declare class Events extends FlowGridTransport {
@@ -276,29 +273,5 @@ export declare class Events extends FlowGridTransport {
      * ```
      */
     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/events.js

@@ -0,0 +1,256 @@
+/**
+ * @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 { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// EVENTS CLASS
+// ============================================================================
+/**
+ * Events - Track and analyze custom events.
+ *
+ * @extends FlowGridTransport
+ *
+ * @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 }
+ * });
+ * ```
+ */
+export class Events extends FlowGridTransport {
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async track(config) {
+        return await this.init("custom_event", {
+            type: "custom_event",
+            eventName: config.eventName,
+            category: config.category || "general",
+            action: config.action,
+            label: config.label,
+            value: config.value,
+            nonInteraction: config.nonInteraction || false,
+            userId: config.userId,
+            sessionId: config.sessionId,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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' }
+     *   ]
+     * });
+     * ```
+     */
+    async trackBatch(config) {
+        const events = config.events.map(e => ({
+            ...e,
+            timestamp: new Date().toISOString()
+        }));
+        return await this.init("batch_events", {
+            type: "batch_events",
+            events,
+            count: events.length,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     *     });
+     *   }
+     * });
+     * ```
+     */
+    async trackClick(config) {
+        return await this.init("click_event", {
+            type: "click_event",
+            ...config,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     *   });
+     * });
+     * ```
+     */
+    async trackForm(config) {
+        return await this.init("form_event", {
+            type: "form_event",
+            ...config,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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' }
+     * });
+     * ```
+     */
+    async trackSearch(config) {
+        return await this.init("search_event", {
+            type: "search_event",
+            query: config.query,
+            category: config.category,
+            resultsCount: config.resultsCount,
+            resultClicked: config.resultClicked,
+            clickedPosition: config.clickedPosition,
+            filters: config.filters,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     *   });
+     * };
+     * ```
+     */
+    async trackError(config) {
+        return await this.init("error_event", {
+            type: "error_event",
+            message: config.message,
+            stack: config.stack,
+            errorType: config.type,
+            fatal: config.fatal || false,
+            context: config.context,
+            userAction: config.userAction,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Events;
+//# sourceMappingURL=events.js.map

package/dist/lib/features/analytics/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/events.ts"],"names":[],"mappings":"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"}

package/dist/lib/features/analytics/funnels.js

@@ -0,0 +1,260 @@
+/**
+ * @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 { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// FUNNELS CLASS
+// ============================================================================
+/**
+ * Funnels - Define and analyze conversion funnels.
+ *
+ * @extends FlowGridTransport
+ *
+ * @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 class Funnels extends FlowGridTransport {
+    /**
+     * 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'] }
+     *   ]
+     * });
+     * ```
+     */
+    async define(config) {
+        return await this.init("define_funnel", {
+            type: "define_funnel",
+            funnelId: config.funnelId,
+            name: config.name,
+            description: config.description,
+            steps: config.steps,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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' }
+     * });
+     * ```
+     */
+    async trackStep(config) {
+        return await this.init("funnel_step", {
+            type: "funnel_step",
+            funnelId: config.funnelId,
+            step: config.step,
+            stepNumber: config.stepNumber,
+            userId: config.userId,
+            sessionId: config.sessionId,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks funnel completion.
+     *
+     * @param funnelId - Funnel identifier
+     * @param userId - User who completed
+     * @param properties - Completion properties
+     * @returns Promise resolving to completion response
+     */
+    async trackComplete(funnelId, userId, properties) {
+        return await this.init("funnel_complete", {
+            type: "funnel_complete",
+            funnelId,
+            userId,
+            ...properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     */
+    async trackAbandon(funnelId, lastStep, userId, reason) {
+        return await this.init("funnel_abandon", {
+            type: "funnel_abandon",
+            funnelId,
+            lastStep,
+            userId,
+            reason,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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}%`);
+     * ```
+     */
+    async analyze(funnelId, filter) {
+        return await this.init("analyze_funnel", {
+            type: "query",
+            funnelId,
+            filter: filter || { range: "last30days" },
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     * }));
+     * ```
+     */
+    async compare(funnelId, baselineFilter, comparisonFilter) {
+        return await this.init("compare_funnel", {
+            type: "query",
+            funnelId,
+            baselineFilter,
+            comparisonFilter,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Lists all defined funnels.
+     *
+     * @returns Promise resolving to funnel list
+     */
+    async list() {
+        return await this.init("list_funnels", {
+            type: "query",
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Funnels;
+//# sourceMappingURL=funnels.js.map

package/dist/lib/features/analytics/funnels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnels.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/funnels.ts"],"names":[],"mappings":"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"}

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

@@ -41,7 +41,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DateRangeFilter } from "../../types";
+import { Teardown } from "../../utils/browser";
 /**
  * Click interaction data.
  */
@@ -229,25 +229,18 @@ export declare class Heatmaps extends FlowGridTransport {
      */
     trackRageClick(pageUrl: string, x: number, y: number, clickCount: number): Promise<HeatmapResponse>;
     /**
-     * Gets heatmap data for visualization.
+     * Auto-collect heatmap interactions: clicks (with element selector + text)
+     * and scroll depth on the current page. Mouse-move tracking is opt-in
+     * because the volume can be very high.
      *
-     * @param pageUrl - Page URL to get data for
-     * @param filter - Date range filter
-     * @returns Promise resolving to heatmap data
-     *
-     * @example
-     * ```typescript
-     * const data = await heatmaps.getData('/pricing', {
-     *   range: 'last7days'
-     * });
-     *
-     * // Render click heatmap
-     * renderHeatmap(data.clicks);
-     *
-     * // Render scroll map
-     * renderScrollMap(data.scrollDepth);
-     * ```
+     * @param options.movement Subscribe to throttled mousemove sampling.
+     * @param options.userId   Attached to every event.
+     * @returns Teardown function detaching all listeners.
      */
-    getData(pageUrl: string, filter?: DateRangeFilter): Promise<HeatmapData>;
+    autoTrack(options?: {
+        movement?: boolean;
+        userId?: string;
+        sessionId?: string;
+    }): Teardown;
 }
 export default Heatmaps;