flowgrid-sdk 1.2.0 → 1.3.0

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

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Product Analytics - Retention Analysis
+ * @module features/analytics/retention
+ *
+ * @description
+ * Track and analyze user retention using cohort analysis,
+ * identify churn patterns, and measure user stickiness.
+ *
+ * @useCases
+ * - Measure week-over-week retention rates
+ * - Compare retention across user cohorts
+ * - Identify churn risk factors
+ * - Track feature adoption impact on retention
+ * - Calculate DAU/MAU ratios (stickiness)
+ *
+ * @metrics
+ * - Day 1, 7, 30 retention rates
+ * - Cohort retention curves
+ * - Churn rate by segment
+ * - User resurrection rate
+ * - DAU/WAU/MAU ratios
+ *
+ * @chartData
+ * - Retention curve: Line chart over time
+ * - Cohort matrix: Heatmap by cohort/period
+ * - Bar chart: Retention by segment
+ * - Trend line: Stickiness over time
+ *
+ * @example
+ * ```typescript
+ * const retention = new Retention(webId, endpoint, apiKey);
+ *
+ * // Track user activity
+ * await retention.trackActivity({
+ *   userId: 'user_123',
+ *   action: 'feature_used'
+ * });
+ *
+ * // Get cohort analysis
+ * const cohorts = await retention.getCohortAnalysis({
+ *   range: 'last90days',
+ *   granularity: 'week'
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// RETENTION CLASS
+// ============================================================================
+/**
+ * Retention - Track and analyze user retention.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides retention analysis capabilities including:
+ * - User activity tracking
+ * - Cohort-based retention analysis
+ * - Stickiness metrics (DAU/MAU)
+ * - Churn prediction and analysis
+ * - Lifecycle stage tracking
+ *
+ * @example
+ * ```typescript
+ * const retention = new Retention(webId, endpoint, apiKey);
+ *
+ * // Track daily user activity
+ * await retention.trackActivity({
+ *   userId: 'user_123',
+ *   action: 'daily_login'
+ * });
+ *
+ * // Analyze cohort retention
+ * const analysis = await retention.getCohortAnalysis({
+ *   granularity: 'week',
+ *   periods: 12
+ * });
+ *
+ * // Cohort heatmap data
+ * const heatmapData = analysis.matrix;
+ * ```
+ */
+export class Retention extends FlowGridTransport {
+    /**
+     * Tracks user activity for retention calculation.
+     *
+     * @param config - Activity configuration
+     * @returns Promise resolving to activity response
+     *
+     * @example
+     * ```typescript
+     * // Track on app open
+     * await retention.trackActivity({
+     *   userId: 'user_123',
+     *   action: 'app_opened'
+     * });
+     *
+     * // Track specific feature usage
+     * await retention.trackActivity({
+     *   userId: 'user_123',
+     *   action: 'used_export',
+     *   properties: { format: 'pdf' }
+     * });
+     * ```
+     */
+    async trackActivity(config) {
+        return await this.init("user_activity", {
+            type: "user_activity",
+            userId: config.userId,
+            action: config.action || "active",
+            sessionId: config.sessionId,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks user lifecycle stage change.
+     *
+     * @param userId - User identifier
+     * @param stage - New lifecycle stage
+     * @param previousStage - Previous stage (optional)
+     * @returns Promise resolving to stage change response
+     */
+    async trackLifecycleChange(userId, stage, previousStage) {
+        return await this.init("lifecycle_change", {
+            type: "lifecycle_change",
+            userId,
+            stage,
+            previousStage,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Retention;
+//# sourceMappingURL=retention.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA4H3D,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,SAAU,SAAQ,iBAAiB;IAC9C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,aAAa,CAAC,MAAsB;QACxC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,QAAQ;YACjC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,GAAG,MAAM,CAAC,UAAU;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,oBAAoB,CACxB,MAAc,EACd,KAAyB,EACzB,aAAkC;QAElC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YACzC,IAAI,EAAE,kBAAkB;YACxB,MAAM;YACN,KAAK;YACL,aAAa;YACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,SAAS,CAAC"}

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

@@ -44,7 +44,8 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DeviceInfo, GeoLocation, UTMParams, TimeSeriesData, DateRangeFilter, PaginationParams, UserIdentity } from "../../types";
+import { Teardown } from "../../utils/browser";
+import { DeviceInfo, GeoLocation, UTMParams, TimeSeriesData, UserIdentity } from "../../types";
 /**
  * Configuration for starting a new session.
  */
@@ -235,43 +236,17 @@ export declare class Sessions extends FlowGridTransport {
      */
     heartbeat(sessionId: string): Promise<SessionResponse>;
     /**
-     * Retrieves session analytics data for dashboards and charts.
+     * Auto-manage a browser session: starts on call, sends a heartbeat on a
+     * fixed interval, and ends the session on `pagehide`. The resolved
+     * `sessionId` is stored on `sessionStorage` so reloads within the same tab
+     * resume the same session.
      *
-     * @param filter - Date range filter
-     * @param pagination - Pagination options
-     * @returns Promise resolving to session analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await sessions.getAnalytics({
-     *   range: 'last7days'
-     * });
-     *
-     * // For pie chart - traffic sources
-     * const sourceData = analytics.bySource.map(s => ({
-     *   name: s.source,
-     *   value: s.sessions
-     * }));
-     *
-     * // For line chart - sessions over time
-     * const trendData = analytics.timeSeries.data;
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<SessionAnalyticsData>;
-    /**
-     * Gets real-time session data for live dashboards.
-     *
-     * @returns Promise resolving to real-time session data
-     *
-     * @example
-     * ```typescript
-     * // Poll for real-time updates
-     * setInterval(async () => {
-     *   const realTime = await sessions.getRealTime();
-     *   updateDashboard(realTime.activeSessions);
-     * }, 10000);
-     * ```
+     * @param config Optional initial config forwarded to {@link Sessions.start}.
+     * @param options.heartbeatMs Interval between heartbeats. Default 30s.
+     * @returns A teardown function that ends the session and detaches listeners.
      */
-    getRealTime(): Promise<RealTimeSessionData>;
+    autoTrack(config?: SessionStartConfig, options?: {
+        heartbeatMs?: number;
+    }): Teardown;
 }
 export default Sessions;

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

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Product Analytics - Session Tracking
+ * @module features/analytics/sessions
+ *
+ * @description
+ * Track user sessions with comprehensive context including device info,
+ * geographic location, traffic source, and engagement metrics.
+ *
+ * @useCases
+ * - Monitor active user sessions in real-time
+ * - Analyze session duration and depth
+ * - Track user journey across pages
+ * - Identify traffic sources and campaigns
+ * - Segment users by device and location
+ *
+ * @metrics
+ * - Total sessions
+ * - Unique visitors
+ * - Average session duration
+ * - Pages per session
+ * - Bounce rate
+ * - New vs returning visitors
+ *
+ * @chartData
+ * - Line chart: Sessions over time
+ * - Pie chart: Traffic source breakdown
+ * - Bar chart: Sessions by device type
+ * - Geo map: Sessions by country
+ *
+ * @example
+ * ```typescript
+ * const sessions = new Sessions(webId, endpoint, apiKey);
+ *
+ * // Start a new session
+ * const session = await sessions.start({
+ *   userId: 'user_123',
+ *   device: { type: 'desktop', browser: 'Chrome' },
+ *   source: 'google',
+ *   medium: 'organic'
+ * });
+ *
+ * // End session
+ * await sessions.end(session.sessionId);
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getWindow, getDocument, isBrowser, combineTeardowns } from "../../utils/browser";
+// ============================================================================
+// SESSIONS CLASS
+// ============================================================================
+/**
+ * Sessions - Track and analyze user sessions.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides comprehensive session tracking including:
+ * - Session lifecycle (start, update, end)
+ * - Device and location tracking
+ * - Traffic source attribution
+ * - Real-time session monitoring
+ * - Session replay triggers
+ *
+ * @example
+ * ```typescript
+ * const sessions = new Sessions(webId, endpoint, apiKey);
+ *
+ * // Start session on page load
+ * const session = await sessions.start({
+ *   user: { userId: 'user_123' },
+ *   device: { type: 'mobile', os: 'iOS' },
+ *   source: 'email',
+ *   campaign: 'summer_sale'
+ * });
+ *
+ * // Get real-time data
+ * const realTime = await sessions.getRealTime();
+ * console.log(`${realTime.activeSessions} users online`);
+ * ```
+ */
+export class Sessions extends FlowGridTransport {
+    /**
+     * Starts a new user session.
+     *
+     * @param config - Session configuration
+     * @returns Promise resolving to session response with sessionId
+     *
+     * @example
+     * ```typescript
+     * const session = await sessions.start({
+     *   user: { userId: 'user_123' },
+     *   source: 'google',
+     *   medium: 'cpc',
+     *   campaign: 'brand_terms'
+     * });
+     * localStorage.setItem('sessionId', session.response.sessionId);
+     * ```
+     */
+    async start(config = {}) {
+        return await this.init("session_start", {
+            type: "session_start",
+            user: config.user,
+            device: config.device,
+            location: config.location,
+            source: config.source || config.utm?.utmSource,
+            medium: config.medium || config.utm?.utmMedium,
+            campaign: config.campaign || config.utm?.utmCampaign,
+            utm: config.utm,
+            landingPage: config.landingPage || (typeof window !== 'undefined' ? window.location.href : ''),
+            referrer: config.referrer || (typeof document !== 'undefined' ? document.referrer : ''),
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Updates an existing session with new data.
+     *
+     * @param sessionId - Session identifier
+     * @param properties - Properties to update
+     * @returns Promise resolving to update response
+     */
+    async update(sessionId, properties) {
+        return await this.init("session_update", {
+            type: "session_update",
+            sessionId,
+            ...properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Ends a user session.
+     *
+     * @param sessionId - Session identifier to end
+     * @returns Promise resolving to session end response with metrics
+     *
+     * @example
+     * ```typescript
+     * window.addEventListener('beforeunload', async () => {
+     *   const sessionId = localStorage.getItem('sessionId');
+     *   if (sessionId) {
+     *     await sessions.end(sessionId);
+     *   }
+     * });
+     * ```
+     */
+    async end(sessionId) {
+        return await this.init("session_end", {
+            type: "session_end",
+            sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks a heartbeat to keep session alive.
+     *
+     * @param sessionId - Session identifier
+     * @returns Promise resolving to heartbeat response
+     */
+    async heartbeat(sessionId) {
+        return await this.init("session_heartbeat", {
+            type: "session_heartbeat",
+            sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Auto-manage a browser session: starts on call, sends a heartbeat on a
+     * fixed interval, and ends the session on `pagehide`. The resolved
+     * `sessionId` is stored on `sessionStorage` so reloads within the same tab
+     * resume the same session.
+     *
+     * @param config Optional initial config forwarded to {@link Sessions.start}.
+     * @param options.heartbeatMs Interval between heartbeats. Default 30s.
+     * @returns A teardown function that ends the session and detaches listeners.
+     */
+    autoTrack(config = {}, options = {}) {
+        if (!isBrowser())
+            return () => { };
+        const win = getWindow();
+        const doc = getDocument();
+        const heartbeatMs = options.heartbeatMs ?? 30000;
+        const STORE_KEY = "flowgrid:sessionId";
+        let sessionId;
+        try {
+            sessionId = win.sessionStorage.getItem(STORE_KEY) || undefined;
+        }
+        catch { /* private mode */ }
+        const startPromise = sessionId
+            ? Promise.resolve(sessionId)
+            : this.start(config).then((r) => {
+                sessionId = r.response.sessionId;
+                try {
+                    win.sessionStorage.setItem(STORE_KEY, sessionId);
+                }
+                catch { /* ignore */ }
+                return sessionId;
+            }).catch(() => undefined);
+        const beat = win.setInterval(() => {
+            if (sessionId && doc.visibilityState === "visible")
+                void this.heartbeat(sessionId);
+        }, heartbeatMs);
+        const onHide = () => { if (sessionId)
+            void this.end(sessionId); };
+        win.addEventListener("pagehide", onHide);
+        return combineTeardowns(() => win.clearInterval(beat), () => win.removeEventListener("pagehide", onHide), () => { void startPromise.then(() => { if (sessionId)
+            void this.end(sessionId); }); }, () => { try {
+            win.sessionStorage.removeItem(STORE_KEY);
+        }
+        catch { /* ignore */ } });
+    }
+}
+export default Sessions;
+//# sourceMappingURL=sessions.js.map

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

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

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

@@ -38,7 +38,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DateRangeFilter, TimeSeriesData } from "../../types";
+import { TimeSeriesData } from "../../types";
 /**
  * Base configuration for activation events.
  */
@@ -212,28 +212,5 @@ export declare class Activation extends FlowGridTransport {
      * @returns Promise resolving to activation response
      */
     trackSignup(userId: string, method: 'email' | 'google' | 'github' | 'apple' | 'sso' | string, source?: string, properties?: Record<string, unknown>): Promise<ActivationResponse>;
-    /**
-     * Gets activation analytics for dashboards.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to activation analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await activation.getAnalytics({
-     *   range: 'last30days'
-     * });
-     *
-     * // Funnel chart - onboarding steps
-     * const funnel = analytics.byStep.map(s => ({
-     *   name: s.stepName,
-     *   value: s.completed
-     * }));
-     *
-     * // KPI - activation rate
-     * const activationRate = analytics.summary.activationRate;
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<ActivationAnalyticsData>;
 }
 export default Activation;

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

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Core - User Activation Tracking
+ * @module features/core/activation
+ *
+ * @description
+ * Track user activation events including onboarding steps,
+ * signup completions, and first-time actions.
+ *
+ * @useCases
+ * - Track onboarding step completions
+ * - Monitor signup funnel
+ * - Measure time to first value
+ * - Identify activation bottlenecks
+ * - A/B test onboarding flows
+ *
+ * @metrics
+ * - Activation rate
+ * - Onboarding completion rate
+ * - Time to activate
+ * - Drop-off by step
+ * - Activation by source
+ *
+ * @chartData
+ * - Funnel chart: Onboarding steps
+ * - Line chart: Activation rate over time
+ * - Bar chart: Activation by cohort/source
+ * - KPI: Time to first value
+ *
+ * @example
+ * ```typescript
+ * const activation = new Activation(webId, endpoint, apiKey);
+ *
+ * // Track activation event
+ * await activation.create({
+ *   eventName: 'onboarding_completed',
+ *   properties: { userId: 'user_123', step: 'profile_setup' }
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// ACTIVATION CLASS
+// ============================================================================
+/**
+ * Activation - Track user activation events.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides activation tracking including:
+ * - Generic activation events
+ * - Onboarding step tracking
+ * - First action tracking
+ * - Signup completion
+ * - Activation analytics
+ *
+ * @example
+ * ```typescript
+ * const activation = new Activation(webId, endpoint, apiKey);
+ *
+ * // Track onboarding step
+ * await activation.trackOnboardingStep({
+ *   userId: 'user_123',
+ *   stepId: 'profile_setup',
+ *   stepName: 'Set Up Profile',
+ *   stepOrder: 2,
+ *   totalSteps: 5
+ * });
+ *
+ * // Track first value action
+ * await activation.trackFirstAction({
+ *   userId: 'user_123',
+ *   actionName: 'created_first_project',
+ *   timeSinceSignup: 3600000 // 1 hour
+ * });
+ * ```
+ */
+export class Activation extends FlowGridTransport {
+    /**
+     * Creates and tracks an activation event.
+     *
+     * @param config - Activation configuration
+     * @returns Promise resolving to activation response
+     */
+    async create(config) {
+        return await this.init(config.eventName, {
+            ...config.properties,
+            type: "activation",
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks an onboarding step completion.
+     *
+     * @param config - Onboarding step configuration
+     * @returns Promise resolving to activation response
+     */
+    async trackOnboardingStep(config) {
+        return await this.init("onboarding_step", {
+            type: "activation",
+            subtype: "onboarding_step",
+            userId: config.userId,
+            stepId: config.stepId,
+            stepName: config.stepName,
+            stepOrder: config.stepOrder,
+            totalSteps: config.totalSteps,
+            progress: Math.round((config.stepOrder / config.totalSteps) * 100),
+            timeSpent: config.timeSpent,
+            skipped: config.skipped || false,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks onboarding completion.
+     *
+     * @param userId - User ID
+     * @param totalTimeSpent - Total time in onboarding (ms)
+     * @param stepsCompleted - Number of steps completed
+     * @param stepsSkipped - Number of steps skipped
+     * @returns Promise resolving to activation response
+     */
+    async completeOnboarding(userId, totalTimeSpent, stepsCompleted, stepsSkipped) {
+        return await this.init("onboarding_completed", {
+            type: "activation",
+            subtype: "onboarding_complete",
+            userId,
+            totalTimeSpent,
+            stepsCompleted,
+            stepsSkipped,
+            completionRate: Math.round((stepsCompleted / (stepsCompleted + stepsSkipped)) * 100),
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks user's first meaningful action (activation moment).
+     *
+     * @param config - First action configuration
+     * @returns Promise resolving to activation response
+     */
+    async trackFirstAction(config) {
+        return await this.init("first_action", {
+            type: "activation",
+            subtype: "first_action",
+            userId: config.userId,
+            actionName: config.actionName,
+            timeSinceSignup: config.timeSinceSignup,
+            source: config.source,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks signup completion.
+     *
+     * @param userId - User ID
+     * @param method - Signup method (email, google, etc.)
+     * @param source - Traffic source
+     * @param properties - Additional properties
+     * @returns Promise resolving to activation response
+     */
+    async trackSignup(userId, method, source, properties) {
+        return await this.init("signup_completed", {
+            type: "activation",
+            subtype: "signup",
+            userId,
+            method,
+            source,
+            ...properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Activation;
+//# sourceMappingURL=activation.js.map

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

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