flowgrid-sdk 1.0.0

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

@@ -0,0 +1,239 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Base configuration for activation events.
+ */
+export interface ActivationConfig {
+    /** Event name */
+    eventName: string;
+    /** Event properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * Onboarding step configuration.
+ */
+export interface OnboardingStepConfig {
+    /** User ID */
+    userId: string;
+    /** Step identifier */
+    stepId: string;
+    /** Step name */
+    stepName: string;
+    /** Step order/number */
+    stepOrder: number;
+    /** Total steps in flow */
+    totalSteps: number;
+    /** Time spent on step (ms) */
+    timeSpent?: number;
+    /** Whether step was skipped */
+    skipped?: boolean;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * First action configuration.
+ */
+export interface FirstActionConfig {
+    /** User ID */
+    userId: string;
+    /** Action name */
+    actionName: string;
+    /** Time since signup (ms) */
+    timeSinceSignup: number;
+    /** Source/referrer */
+    source?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Activation response from API.
+ */
+export interface ActivationResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        activationId?: string;
+        isFirstActivation?: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Activation analytics data.
+ */
+export interface ActivationAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalSignups: number;
+        activatedUsers: number;
+        activationRate: number;
+        avgTimeToActivate: number;
+        onboardingCompletionRate: number;
+    };
+    /** Activation by step */
+    byStep: Array<{
+        stepId: string;
+        stepName: string;
+        started: number;
+        completed: number;
+        dropOff: number;
+        avgTimeSpent: number;
+    }>;
+    /** Activation by source */
+    bySource: Array<{
+        source: string;
+        signups: number;
+        activated: number;
+        activationRate: number;
+    }>;
+    /** Activation trends */
+    trends: TimeSeriesData;
+    /** Cohort activation */
+    byCohort: Array<{
+        cohort: string;
+        users: number;
+        activated: number;
+        activationRate: number;
+        avgTimeToActivate: number;
+    }>;
+}
+/**
+ * Activation - Track user activation events.
+ *
+ * @extends FTRPC
+ *
+ * @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 declare class Activation extends FTRPC {
+    /**
+     * Creates and tracks an activation event.
+     *
+     * @param config - Activation configuration
+     * @returns Promise resolving to activation response
+     */
+    create(config: ActivationConfig): Promise<ActivationResponse>;
+    /**
+     * Tracks an onboarding step completion.
+     *
+     * @param config - Onboarding step configuration
+     * @returns Promise resolving to activation response
+     */
+    trackOnboardingStep(config: OnboardingStepConfig): Promise<ActivationResponse>;
+    /**
+     * 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
+     */
+    completeOnboarding(userId: string, totalTimeSpent: number, stepsCompleted: number, stepsSkipped: number): Promise<ActivationResponse>;
+    /**
+     * Tracks user's first meaningful action (activation moment).
+     *
+     * @param config - First action configuration
+     * @returns Promise resolving to activation response
+     */
+    trackFirstAction(config: FirstActionConfig): Promise<ActivationResponse>;
+    /**
+     * 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
+     */
+    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/experiment.d.ts

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview Core - A/B Testing & Experiments
+ * @module features/core/experiment
+ *
+ * @description
+ * Track A/B tests, experiments, and variant assignments
+ * to measure impact and optimize product decisions.
+ *
+ * @useCases
+ * - Run A/B tests on features
+ * - Track variant assignments
+ * - Measure experiment impact
+ * - Statistical significance analysis
+ * - Multi-variant testing
+ *
+ * @metrics
+ * - Conversion by variant
+ * - Statistical significance
+ * - Sample size per variant
+ * - Experiment duration
+ * - Impact on key metrics
+ *
+ * @chartData
+ * - Bar chart: Conversion by variant
+ * - Line chart: Metric trends by variant
+ * - Table: Experiment results summary
+ * - Confidence interval visualization
+ *
+ * @example
+ * ```typescript
+ * const experiment = new Experiment(webId, endpoint, apiKey);
+ *
+ * await experiment.track({
+ *   eventName: 'checkout_flow_test',
+ *   variant: 'simplified_v2',
+ *   properties: { userId: 'user_123' }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Base experiment configuration.
+ */
+export interface ExperimentConfig {
+    /** Experiment/event name */
+    eventName: string;
+    /** Assigned variant */
+    variant: string;
+    /** Event properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * Experiment definition.
+ */
+export interface ExperimentDefinition {
+    /** Experiment ID */
+    experimentId: string;
+    /** Experiment name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Variants */
+    variants: Array<{
+        variantId: string;
+        name: string;
+        weight: number;
+    }>;
+    /** Target audience (optional) */
+    audience?: {
+        percentage: number;
+        filters?: Record<string, unknown>;
+    };
+    /** Primary metric */
+    primaryMetric: string;
+    /** Secondary metrics */
+    secondaryMetrics?: string[];
+    /** Start date */
+    startDate?: string;
+    /** End date */
+    endDate?: string;
+}
+/**
+ * Experiment assignment configuration.
+ */
+export interface ExperimentAssignmentConfig {
+    /** Experiment ID */
+    experimentId: string;
+    /** User ID */
+    userId: string;
+    /** Assigned variant ID */
+    variantId: string;
+    /** Assignment source */
+    source?: 'random' | 'targeted' | 'override';
+}
+/**
+ * Experiment conversion configuration.
+ */
+export interface ExperimentConversionConfig {
+    /** Experiment ID */
+    experimentId: string;
+    /** User ID */
+    userId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Metric name */
+    metricName: string;
+    /** Metric value */
+    value: number;
+}
+/**
+ * Experiment tracking response.
+ */
+export interface ExperimentResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        experimentId?: string;
+        variantId?: string;
+    };
+    timestamp: string;
+}
+/**
+ * Experiment results data.
+ */
+export interface ExperimentResultsData {
+    /** Experiment info */
+    experiment: {
+        experimentId: string;
+        name: string;
+        status: 'running' | 'paused' | 'completed';
+        startDate: string;
+        duration: number;
+    };
+    /** Results by variant */
+    variants: Array<{
+        variantId: string;
+        name: string;
+        participants: number;
+        conversions: number;
+        conversionRate: number;
+        improvement: number;
+        confidence: number;
+        isWinner: boolean;
+        isStatisticallySignificant: boolean;
+    }>;
+    /** Metric trends */
+    trends: Record<string, TimeSeriesData>;
+    /** Recommendation */
+    recommendation: {
+        action: 'ship_winner' | 'continue' | 'stop' | 'needs_more_data';
+        winningVariant?: string;
+        confidence: number;
+        reason: string;
+    };
+}
+/**
+ * All experiments analytics.
+ */
+export interface ExperimentAnalyticsData {
+    /** Summary */
+    summary: {
+        totalExperiments: number;
+        activeExperiments: number;
+        completedExperiments: number;
+        avgExperimentDuration: number;
+        winRate: number;
+    };
+    /** Active experiments */
+    active: Array<{
+        experimentId: string;
+        name: string;
+        participants: number;
+        daysSinceStart: number;
+        leadingVariant: string;
+        confidence: number;
+    }>;
+    /** Recent results */
+    recentResults: Array<{
+        experimentId: string;
+        name: string;
+        winner: string;
+        improvement: number;
+        completedDate: string;
+    }>;
+}
+/**
+ * Experiment - Track A/B tests and experiments.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides experiment tracking including:
+ * - Experiment definition
+ * - Variant assignment
+ * - Conversion tracking
+ * - Results analysis
+ * - Statistical significance
+ *
+ * @example
+ * ```typescript
+ * const experiment = new Experiment(webId, endpoint, apiKey);
+ *
+ * // Define experiment
+ * await experiment.define({
+ *   experimentId: 'checkout_v2',
+ *   name: 'Simplified Checkout',
+ *   variants: [
+ *     { variantId: 'control', name: 'Current', weight: 50 },
+ *     { variantId: 'treatment', name: 'Simplified', weight: 50 }
+ *   ],
+ *   primaryMetric: 'checkout_completed'
+ * });
+ *
+ * // Assign user to variant
+ * await experiment.assign({
+ *   experimentId: 'checkout_v2',
+ *   userId: 'user_123',
+ *   variantId: 'treatment'
+ * });
+ *
+ * // Track conversion
+ * await experiment.trackConversion({
+ *   experimentId: 'checkout_v2',
+ *   userId: 'user_123',
+ *   variantId: 'treatment',
+ *   metricName: 'checkout_completed',
+ *   value: 1
+ * });
+ * ```
+ */
+export declare class Experiment extends FTRPC {
+    /**
+     * Tracks an experiment event.
+     *
+     * @param config - Experiment configuration
+     * @returns Promise resolving to experiment response
+     */
+    track(config: ExperimentConfig): Promise<ExperimentResponse>;
+    /**
+     * Defines a new experiment.
+     *
+     * @param definition - Experiment definition
+     * @returns Promise resolving to experiment response
+     */
+    define(definition: ExperimentDefinition): Promise<ExperimentResponse>;
+    /**
+     * Assigns a user to an experiment variant.
+     *
+     * @param config - Assignment configuration
+     * @returns Promise resolving to experiment response
+     */
+    assign(config: ExperimentAssignmentConfig): Promise<ExperimentResponse>;
+    /**
+     * Tracks a conversion for an experiment.
+     *
+     * @param config - Conversion configuration
+     * @returns Promise resolving to experiment response
+     */
+    trackConversion(config: ExperimentConversionConfig): Promise<ExperimentResponse>;
+    /**
+     * Tracks user exposure to an experiment.
+     *
+     * @param experimentId - Experiment ID
+     * @param userId - User ID
+     * @param variantId - Variant ID
+     * @returns Promise resolving to experiment response
+     */
+    trackExposure(experimentId: string, userId: string, variantId: string): Promise<ExperimentResponse>;
+    /**
+     * Gets results for a specific experiment.
+     *
+     * @param experimentId - Experiment ID
+     * @returns Promise resolving to experiment results
+     */
+    getResults(experimentId: string): Promise<ExperimentResultsData>;
+    /**
+     * Gets experiment analytics overview.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to experiment analytics
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<ExperimentAnalyticsData>;
+}
+export default Experiment;