flowgrid-sdk 1.0.0

package/dist/lib/features/core/feature-flag.d.ts

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Core - Feature Flags
+ * @module features/core/feature-flag
+ *
+ * @description
+ * Track feature flag evaluations and usage to understand
+ * rollout progress and flag performance.
+ *
+ * @useCases
+ * - Track flag evaluations
+ * - Monitor rollout progress
+ * - Analyze flag impact
+ * - Debug flag configurations
+ * - Measure gradual rollouts
+ *
+ * @metrics
+ * - Evaluations per flag
+ * - Unique users per variant
+ * - Rollout percentage
+ * - Error rate
+ * - Flag age
+ *
+ * @chartData
+ * - Pie chart: Users by variant
+ * - Line chart: Evaluations over time
+ * - Table: Active flags summary
+ * - Bar chart: Top evaluated flags
+ *
+ * @example
+ * ```typescript
+ * const featureFlag = new FeatureFlag(webId, endpoint, apiKey);
+ *
+ * await featureFlag.evaluate({
+ *   eventName: 'new_dashboard',
+ *   properties: { userId: 'user_123', result: true }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Base feature flag configuration.
+ */
+export interface FlagConfig {
+    /** Flag name/event */
+    eventName: string;
+    /** Evaluation properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * Feature flag definition.
+ */
+export interface FlagDefinition {
+    /** Flag key */
+    flagKey: string;
+    /** Flag name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Flag type */
+    type: 'boolean' | 'string' | 'number' | 'json';
+    /** Default value */
+    defaultValue: boolean | string | number | Record<string, unknown>;
+    /** Variants (for multivariate flags) */
+    variants?: Array<{
+        key: string;
+        value: boolean | string | number | Record<string, unknown>;
+        weight?: number;
+    }>;
+    /** Targeting rules */
+    targeting?: {
+        rules: Array<{
+            attribute: string;
+            operator: 'equals' | 'contains' | 'in' | 'gt' | 'lt';
+            value: unknown;
+            variant: string;
+        }>;
+    };
+    /** Rollout percentage (0-100) */
+    rolloutPercentage?: number;
+}
+/**
+ * Flag evaluation configuration.
+ */
+export interface FlagEvaluationConfig {
+    /** Flag key */
+    flagKey: string;
+    /** User ID */
+    userId?: string;
+    /** Evaluation context */
+    context?: Record<string, unknown>;
+    /** Evaluated variant/value */
+    result: boolean | string | number | Record<string, unknown>;
+    /** Reason for evaluation result */
+    reason?: 'default' | 'targeting' | 'rollout' | 'override' | 'error';
+    /** Evaluation duration (ms) */
+    duration?: number;
+}
+/**
+ * Feature flag response.
+ */
+export interface FlagResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        flagKey?: string;
+    };
+    timestamp: string;
+}
+/**
+ * Single flag analytics.
+ */
+export interface FlagAnalyticsData {
+    /** Flag info */
+    flag: {
+        flagKey: string;
+        name: string;
+        type: string;
+        status: 'active' | 'inactive' | 'archived';
+        createdAt: string;
+        lastModified: string;
+    };
+    /** Evaluation stats */
+    evaluations: {
+        total: number;
+        uniqueUsers: number;
+        avgDuration: number;
+        errorRate: number;
+    };
+    /** Results by variant */
+    byVariant: Array<{
+        variant: string;
+        evaluations: number;
+        uniqueUsers: number;
+        percentage: number;
+    }>;
+    /** Results by reason */
+    byReason: Record<string, number>;
+    /** Trends */
+    trends: TimeSeriesData;
+}
+/**
+ * All flags analytics.
+ */
+export interface AllFlagsAnalyticsData {
+    /** Summary */
+    summary: {
+        totalFlags: number;
+        activeFlags: number;
+        totalEvaluations: number;
+        uniqueUsers: number;
+        avgEvaluationsPerUser: number;
+    };
+    /** Top flags by evaluations */
+    topFlags: Array<{
+        flagKey: string;
+        name: string;
+        evaluations: number;
+        uniqueUsers: number;
+        rolloutPercentage: number;
+    }>;
+    /** Stale flags (not evaluated recently) */
+    staleFlags: Array<{
+        flagKey: string;
+        name: string;
+        lastEvaluated: string;
+        daysSinceEvaluation: number;
+    }>;
+    /** Flags by status */
+    byStatus: {
+        active: number;
+        inactive: number;
+        archived: number;
+    };
+}
+/**
+ * FeatureFlag - Track feature flag evaluations.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides feature flag tracking including:
+ * - Flag evaluations
+ * - Rollout monitoring
+ * - Flag definitions
+ * - Usage analytics
+ * - Stale flag detection
+ *
+ * @example
+ * ```typescript
+ * const featureFlag = new FeatureFlag(webId, endpoint, apiKey);
+ *
+ * // Track evaluation
+ * await featureFlag.trackEvaluation({
+ *   flagKey: 'new_checkout',
+ *   userId: 'user_123',
+ *   result: true,
+ *   reason: 'rollout'
+ * });
+ *
+ * // Get flag analytics
+ * const analytics = await featureFlag.getFlagAnalytics('new_checkout');
+ * console.log(`${analytics.evaluations.total} evaluations`);
+ * ```
+ */
+export declare class FeatureFlag extends FTRPC {
+    /**
+     * Evaluates and tracks a feature flag.
+     *
+     * @param config - Flag configuration
+     * @returns Promise resolving to flag response
+     */
+    evaluate(config: FlagConfig): Promise<FlagResponse>;
+    /**
+     * Tracks a flag evaluation with details.
+     *
+     * @param config - Flag evaluation configuration
+     * @returns Promise resolving to flag response
+     */
+    trackEvaluation(config: FlagEvaluationConfig): Promise<FlagResponse>;
+    /**
+     * Defines/updates a feature flag.
+     *
+     * @param definition - Flag definition
+     * @returns Promise resolving to flag response
+     */
+    define(definition: FlagDefinition): Promise<FlagResponse>;
+    /**
+     * Tracks flag status change (enable/disable).
+     *
+     * @param flagKey - Flag key
+     * @param enabled - Whether flag is enabled
+     * @param changedBy - User who made the change
+     * @returns Promise resolving to flag response
+     */
+    trackStatusChange(flagKey: string, enabled: boolean, changedBy?: string): Promise<FlagResponse>;
+    /**
+     * Tracks rollout percentage change.
+     *
+     * @param flagKey - Flag key
+     * @param previousPercentage - Previous rollout %
+     * @param newPercentage - New rollout %
+     * @param changedBy - User who made the change
+     * @returns Promise resolving to flag response
+     */
+    trackRolloutChange(flagKey: string, previousPercentage: number, newPercentage: number, changedBy?: string): Promise<FlagResponse>;
+    /**
+     * Gets analytics for a specific flag.
+     *
+     * @param flagKey - Flag key
+     * @param filter - Date range filter
+     * @returns Promise resolving to flag analytics
+     */
+    getFlagAnalytics(flagKey: string, filter?: DateRangeFilter): Promise<FlagAnalyticsData>;
+    /**
+     * Gets analytics for all flags.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to all flags analytics
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<AllFlagsAnalyticsData>;
+}
+export default FeatureFlag;

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

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Core features barrel export
+ * @module features/core
+ */
+export { Activation } from './activation';
+export { TrackFeature } from './track-feature';
+export { TrackPrompt } from './track-prompt';
+export { Experiment } from './experiment';
+export { FeatureFlag } from './feature-flag';
+export type { ActivationConfig, OnboardingStepConfig, FirstActionConfig, ActivationResponse, ActivationAnalyticsData } from './activation';
+export type { FeatureConfig, FeatureUsageConfig, FeatureDiscoveryConfig, FeatureResponse, FeatureAnalyticsData } from './track-feature';
+export type { PromptConfig, PromptSubmissionConfig, PromptResponseConfig, PromptFeedbackConfig, PromptResponse, PromptAnalyticsData } from './track-prompt';
+export type { ExperimentConfig, ExperimentDefinition, ExperimentAssignmentConfig, ExperimentConversionConfig, ExperimentResponse, ExperimentResultsData, ExperimentAnalyticsData } from './experiment';
+export type { FlagConfig, FlagDefinition, FlagEvaluationConfig, FlagResponse, FlagAnalyticsData, AllFlagsAnalyticsData } from './feature-flag';

package/dist/lib/features/core/track-feature.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Core - Feature Usage Tracking
+ * @module features/core/track-feature
+ *
+ * @description
+ * Track feature usage events to understand how users
+ * interact with different parts of your product.
+ *
+ * @useCases
+ * - Track feature adoption rates
+ * - Measure feature engagement
+ * - Identify power users
+ * - Prioritize feature development
+ * - Detect underused features
+ *
+ * @metrics
+ * - Feature adoption rate
+ * - Feature usage frequency
+ * - Users per feature
+ * - Feature stickiness
+ * - Time spent per feature
+ *
+ * @chartData
+ * - Bar chart: Most used features
+ * - Heatmap: Feature usage by user segment
+ * - Line chart: Feature adoption over time
+ * - Table: Feature engagement metrics
+ *
+ * @example
+ * ```typescript
+ * const trackFeature = new TrackFeature(webId, endpoint, apiKey);
+ *
+ * await trackFeature.create({
+ *   eventName: 'export_report',
+ *   properties: { format: 'csv', rowCount: 1000 }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Base configuration for feature tracking.
+ */
+export interface FeatureConfig {
+    /** Event/feature name */
+    eventName: string;
+    /** Event properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * Detailed feature usage configuration.
+ */
+export interface FeatureUsageConfig {
+    /** Feature identifier */
+    featureId: string;
+    /** Feature name */
+    featureName: string;
+    /** User ID */
+    userId?: string;
+    /** Usage action */
+    action: 'viewed' | 'used' | 'completed' | 'abandoned';
+    /** Time spent (ms) */
+    duration?: number;
+    /** Success/failure */
+    success?: boolean;
+    /** Feature category */
+    category?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Feature discovery configuration.
+ */
+export interface FeatureDiscoveryConfig {
+    /** Feature identifier */
+    featureId: string;
+    /** User ID */
+    userId: string;
+    /** How feature was discovered */
+    discoveryMethod: 'organic' | 'tooltip' | 'announcement' | 'search' | 'onboarding' | 'recommendation';
+    /** Whether user engaged with feature */
+    engaged: boolean;
+}
+/**
+ * Feature tracking response.
+ */
+export interface FeatureResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        featureId?: string;
+        isFirstUse?: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Feature analytics data.
+ */
+export interface FeatureAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalFeatures: number;
+        totalUsage: number;
+        uniqueUsers: number;
+        avgUsagePerUser: number;
+        mostUsedFeature: string;
+        leastUsedFeature: string;
+    };
+    /** Usage by feature */
+    byFeature: Array<{
+        featureId: string;
+        featureName: string;
+        category: string;
+        usageCount: number;
+        uniqueUsers: number;
+        adoptionRate: number;
+        avgDuration: number;
+        successRate: number;
+    }>;
+    /** Usage by user segment */
+    bySegment: Array<{
+        segment: string;
+        topFeatures: string[];
+        avgFeaturesUsed: number;
+    }>;
+    /** Feature trends */
+    trends: TimeSeriesData;
+    /** Feature correlations */
+    correlations: Array<{
+        featureA: string;
+        featureB: string;
+        correlation: number;
+    }>;
+}
+/**
+ * TrackFeature - Track feature usage events.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides feature tracking including:
+ * - Generic feature events
+ * - Detailed usage tracking
+ * - Feature discovery tracking
+ * - Adoption analytics
+ * - Engagement metrics
+ *
+ * @example
+ * ```typescript
+ * const trackFeature = new TrackFeature(webId, endpoint, apiKey);
+ *
+ * // Simple feature tracking
+ * await trackFeature.create({
+ *   eventName: 'dark_mode_enabled',
+ *   properties: { userId: 'user_123' }
+ * });
+ *
+ * // Detailed feature usage
+ * await trackFeature.trackUsage({
+ *   featureId: 'export',
+ *   featureName: 'Data Export',
+ *   userId: 'user_123',
+ *   action: 'completed',
+ *   duration: 5000,
+ *   success: true,
+ *   properties: { format: 'csv' }
+ * });
+ * ```
+ */
+export declare class TrackFeature extends FTRPC {
+    /**
+     * Records a feature usage event.
+     *
+     * @param config - Feature configuration
+     * @returns Promise resolving to feature response
+     */
+    create(config: FeatureConfig): Promise<FeatureResponse>;
+    /**
+     * Tracks detailed feature usage.
+     *
+     * @param config - Feature usage configuration
+     * @returns Promise resolving to feature response
+     */
+    trackUsage(config: FeatureUsageConfig): Promise<FeatureResponse>;
+    /**
+     * Tracks feature discovery.
+     *
+     * @param config - Feature discovery configuration
+     * @returns Promise resolving to feature response
+     */
+    trackDiscovery(config: FeatureDiscoveryConfig): Promise<FeatureResponse>;
+    /**
+     * Tracks feature adoption (first-time use).
+     *
+     * @param featureId - Feature identifier
+     * @param userId - User ID
+     * @param source - How user found feature
+     * @returns Promise resolving to feature response
+     */
+    trackAdoption(featureId: string, userId: string, source?: string): Promise<FeatureResponse>;
+    /**
+     * Tracks feature abandonment.
+     *
+     * @param featureId - Feature identifier
+     * @param userId - User ID
+     * @param reason - Abandonment reason
+     * @param timeSpent - Time spent before abandoning (ms)
+     * @returns Promise resolving to feature response
+     */
+    trackAbandonment(featureId: string, userId: string, reason?: string, timeSpent?: number): Promise<FeatureResponse>;
+    /**
+     * Gets feature analytics for dashboards.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to feature analytics
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<FeatureAnalyticsData>;
+}
+export default TrackFeature;