flowgrid-sdk 1.0.0

package/dist/lib/features/enterprise/paths.d.ts

@@ -0,0 +1,332 @@
+/**
+ * @fileoverview Enterprise - Behavioral Analytics & Path Analysis
+ * @module features/enterprise/paths
+ *
+ * @description
+ * Track full user navigation and feature usage sequences.
+ * Identify common paths, dead-ends, and UX friction points.
+ *
+ * @useCases
+ * - Sequence analysis of feature usage
+ * - Dead-end screen detection
+ * - Most common path identification
+ * - User journey mapping
+ * - UX friction detection
+ *
+ * @metrics
+ * - Path frequency
+ * - Path completion rate
+ * - Dead-end rate
+ * - Average path length
+ * - Time per path
+ *
+ * @chartData
+ * - Sankey diagram: User flow
+ * - Tree map: Path distribution
+ * - Heatmap: Screen transitions
+ * - Timeline: User journeys
+ *
+ * @example
+ * ```typescript
+ * const paths = new PathAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track screen/page transition
+ * await paths.trackTransition({
+ *   userId: 'user_123',
+ *   fromScreen: 'dashboard',
+ *   toScreen: 'settings'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Screen/page transition configuration.
+ */
+export interface TransitionConfig {
+    /** User ID */
+    userId: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Source screen/page */
+    fromScreen: string;
+    /** Destination screen/page */
+    toScreen: string;
+    /** Time spent on source screen (ms) */
+    timeSpentMs?: number;
+    /** Trigger action */
+    trigger?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Feature sequence configuration.
+ */
+export interface FeatureSequenceConfig {
+    /** User ID */
+    userId: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Feature/action name */
+    feature: string;
+    /** Sequence order in session */
+    order: number;
+    /** Time spent (ms) */
+    timeSpentMs?: number;
+    /** Whether action was successful */
+    successful?: boolean;
+}
+/**
+ * Path definition.
+ */
+export interface PathDefinition {
+    /** Path identifier */
+    pathId?: string;
+    /** Path name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Ordered list of screens/steps */
+    screens: string[];
+    /** Goal screen (optional) */
+    goal?: string;
+    /** Tags */
+    tags?: string[];
+}
+/**
+ * Path analysis configuration.
+ */
+export interface PathAnalysisConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Starting screen */
+    startScreen?: string;
+    /** Ending screen */
+    endScreen?: string;
+    /** Minimum path occurrences */
+    minOccurrences?: number;
+    /** Maximum path length */
+    maxLength?: number;
+}
+/**
+ * Path analytics result.
+ */
+export interface PathResult {
+    /** Path screens */
+    path: string[];
+    /** Number of users who took this path */
+    userCount: number;
+    /** Percentage of total users */
+    percentage: number;
+    /** Average time to complete path (ms) */
+    avgTimeMs: number;
+    /** Completion rate (if goal defined) */
+    completionRate?: number;
+    /** Drop-off at each step */
+    dropOffByStep?: Array<{
+        step: string;
+        dropOffRate: number;
+    }>;
+}
+/**
+ * Dead-end screen.
+ */
+export interface DeadEndScreen {
+    /** Screen name */
+    screen: string;
+    /** Exit rate (users who leave from this screen) */
+    exitRate: number;
+    /** User count */
+    userCount: number;
+    /** Average time before exit (ms) */
+    avgTimeBeforeExitMs: number;
+    /** Previous screens (where users came from) */
+    previousScreens: Array<{
+        screen: string;
+        count: number;
+    }>;
+    /** Is this a dead-end (high exit, not intended end point) */
+    isDeadEnd: boolean;
+}
+/**
+ * Screen transition matrix.
+ */
+export interface TransitionMatrix {
+    /** All screens */
+    screens: string[];
+    /** Transition probabilities (screens.length x screens.length) */
+    matrix: number[][];
+    /** Total transitions */
+    totalTransitions: number;
+}
+/**
+ * User journey configuration.
+ */
+export interface UserJourneyConfig {
+    /** User ID */
+    userId: string;
+    /** Session ID (optional, get all sessions if not provided) */
+    sessionId?: string;
+    /** Date range */
+    filter?: DateRangeFilter;
+}
+/**
+ * User journey result.
+ */
+export interface UserJourney {
+    userId: string;
+    sessions: Array<{
+        sessionId: string;
+        startTime: string;
+        endTime: string;
+        path: Array<{
+            screen: string;
+            timestamp: string;
+            timeSpentMs: number;
+            actions?: string[];
+        }>;
+        totalDurationMs: number;
+        screenCount: number;
+    }>;
+}
+/**
+ * Friction point.
+ */
+export interface FrictionPoint {
+    /** Screen or step */
+    location: string;
+    /** Friction type */
+    type: 'high_exit' | 'long_dwell' | 'rage_clicks' | 'back_navigation' | 'error';
+    /** Severity score (0-100) */
+    severity: number;
+    /** Affected users */
+    affectedUsers: number;
+    /** Suggested improvement */
+    suggestion?: string;
+}
+/**
+ * Path comparison.
+ */
+export interface PathComparison {
+    /** Paths being compared */
+    paths: PathResult[];
+    /** Statistical significance */
+    significant: boolean;
+    /** Winner (if significant) */
+    winner?: string;
+    /** Metrics comparison */
+    comparison: {
+        metric: string;
+        values: Record<string, number>;
+        difference: number;
+    }[];
+}
+/**
+ * Convert path array to string identifier.
+ */
+export declare function pathToString(path: string[]): string;
+/**
+ * Convert string identifier to path array.
+ */
+export declare function stringToPath(pathString: string): string[];
+/**
+ * Calculate exit rate.
+ */
+export declare function calculateExitRate(exits: number, entries: number): number;
+/**
+ * Identify if a screen is a dead-end.
+ */
+export declare function isDeadEnd(exitRate: number, isIntendedEndPoint: boolean, threshold?: number): boolean;
+/**
+ * Calculate path similarity (Jaccard index).
+ */
+export declare function calculatePathSimilarity(path1: string[], path2: string[]): number;
+/**
+ * Find common sub-paths.
+ */
+export declare function findCommonSubPaths(paths: string[][], minLength?: number): Array<{
+    subPath: string[];
+    count: number;
+}>;
+/**
+ * Behavioral analytics and path analysis class.
+ */
+export declare class PathAnalytics extends EnterpriseFTRPC {
+    /**
+     * Track screen/page transition.
+     */
+    trackTransition(config: TransitionConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track feature sequence.
+     */
+    trackFeatureSequence(config: FeatureSequenceConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Define a path for tracking.
+     */
+    definePath(definition: PathDefinition): Promise<{
+        pathId: string;
+    }>;
+    /**
+     * Get top paths.
+     */
+    getTopPaths(config?: PathAnalysisConfig): Promise<PathResult[]>;
+    /**
+     * Get paths between screens.
+     */
+    getPathsBetween(startScreen: string, endScreen: string, filter?: DateRangeFilter, limit?: number): Promise<PathResult[]>;
+    /**
+     * Get dead-end screens.
+     */
+    getDeadEnds(filter?: DateRangeFilter, intendedEndPoints?: string[]): Promise<DeadEndScreen[]>;
+    /**
+     * Get transition matrix.
+     */
+    getTransitionMatrix(filter?: DateRangeFilter): Promise<TransitionMatrix>;
+    /**
+     * Get user journey.
+     */
+    getUserJourney(config: UserJourneyConfig): Promise<UserJourney>;
+    /**
+     * Get friction points.
+     */
+    getFrictionPoints(filter?: DateRangeFilter): Promise<FrictionPoint[]>;
+    /**
+     * Compare paths.
+     */
+    comparePaths(paths: string[][], filter?: DateRangeFilter): Promise<PathComparison>;
+    /**
+     * Get screen analytics.
+     */
+    getScreenAnalytics(screen: string, filter?: DateRangeFilter): Promise<{
+        screen: string;
+        visits: number;
+        uniqueUsers: number;
+        avgTimeSpentMs: number;
+        exitRate: number;
+        entryRate: number;
+        topNextScreens: Array<{
+            screen: string;
+            count: number;
+        }>;
+        topPreviousScreens: Array<{
+            screen: string;
+            count: number;
+        }>;
+    }>;
+    /**
+     * Get path trend.
+     */
+    getPathTrend(path: string[], filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get feature usage sequences.
+     */
+    getFeatureSequences(filter?: DateRangeFilter, limit?: number): Promise<Array<{
+        sequence: string[];
+        userCount: number;
+        avgTimeMs: number;
+    }>>;
+}

package/dist/lib/features/enterprise/security.d.ts

@@ -0,0 +1,387 @@
+/**
+ * @fileoverview Enterprise - Security & Compliance Analytics
+ * @module features/enterprise/security
+ *
+ * @description
+ * Track activity for security, privacy, and regulatory compliance.
+ * Monitor login attempts, role changes, and compliance events.
+ *
+ * @useCases
+ * - Track failed login attempts
+ * - Monitor role/permission changes
+ * - GDPR/CCPA compliance events
+ * - Audit logging
+ * - Security anomaly detection
+ *
+ * @metrics
+ * - Failed login rate
+ * - Suspicious activity count
+ * - Role change frequency
+ * - Data access patterns
+ * - Compliance event count
+ *
+ * @chartData
+ * - Line chart: Security events over time
+ * - Bar chart: Events by type
+ * - Table: Audit log
+ * - Heatmap: Access patterns
+ *
+ * @example
+ * ```typescript
+ * const security = new SecurityAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track login attempt
+ * await security.trackLoginAttempt({
+ *   userId: 'user_123',
+ *   success: false,
+ *   reason: 'invalid_password'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Security event types.
+ */
+export type SecurityEventType = 'login_attempt' | 'login_success' | 'login_failure' | 'logout' | 'password_change' | 'password_reset' | 'mfa_enabled' | 'mfa_disabled' | 'role_change' | 'permission_change' | 'data_access' | 'data_export' | 'data_deletion' | 'api_key_created' | 'api_key_revoked' | 'suspicious_activity';
+/**
+ * Compliance event types.
+ */
+export type ComplianceEventType = 'consent_given' | 'consent_withdrawn' | 'data_access_request' | 'data_deletion_request' | 'data_portability_request' | 'privacy_policy_update' | 'opt_out' | 'opt_in';
+/**
+ * Login attempt configuration.
+ */
+export interface LoginAttemptConfig {
+    /** User ID or email */
+    userId: string;
+    /** Whether login was successful */
+    success: boolean;
+    /** Failure reason (if failed) */
+    reason?: string;
+    /** IP address */
+    ipAddress?: string;
+    /** User agent */
+    userAgent?: string;
+    /** Device info */
+    device?: string;
+    /** Location */
+    location?: {
+        country?: string;
+        city?: string;
+    };
+    /** MFA used */
+    mfaUsed?: boolean;
+}
+/**
+ * Role change configuration.
+ */
+export interface RoleChangeConfig {
+    /** User ID being changed */
+    userId: string;
+    /** Who made the change */
+    changedBy: string;
+    /** Previous role */
+    previousRole: string;
+    /** New role */
+    newRole: string;
+    /** Reason for change */
+    reason?: string;
+}
+/**
+ * Permission change configuration.
+ */
+export interface PermissionChangeConfig {
+    /** User ID being changed */
+    userId: string;
+    /** Who made the change */
+    changedBy: string;
+    /** Permission being changed */
+    permission: string;
+    /** Action */
+    action: 'granted' | 'revoked';
+    /** Resource scope */
+    resourceScope?: string;
+}
+/**
+ * Data access configuration.
+ */
+export interface DataAccessConfig {
+    /** User ID accessing data */
+    userId: string;
+    /** Resource type */
+    resourceType: string;
+    /** Resource ID */
+    resourceId?: string;
+    /** Access type */
+    accessType: 'read' | 'write' | 'delete' | 'export';
+    /** IP address */
+    ipAddress?: string;
+    /** Query/filter used */
+    query?: Record<string, unknown>;
+}
+/**
+ * Compliance event configuration.
+ */
+export interface ComplianceEventConfig {
+    /** User ID */
+    userId: string;
+    /** Event type */
+    eventType: ComplianceEventType;
+    /** Regulation */
+    regulation?: 'GDPR' | 'CCPA' | 'HIPAA' | 'SOC2' | 'other';
+    /** Details */
+    details?: Record<string, unknown>;
+    /** Consent scope (for consent events) */
+    consentScope?: string[];
+    /** Request ID (for data requests) */
+    requestId?: string;
+}
+/**
+ * Audit log entry.
+ */
+export interface AuditLogEntry {
+    /** Entry ID */
+    entryId: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Event type */
+    eventType: SecurityEventType | ComplianceEventType;
+    /** Actor (who performed the action) */
+    actor: {
+        userId: string;
+        userEmail?: string;
+        ipAddress?: string;
+    };
+    /** Target (what was affected) */
+    target?: {
+        type: string;
+        id: string;
+        name?: string;
+    };
+    /** Action details */
+    details: Record<string, unknown>;
+    /** Severity */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /** Was action successful */
+    success: boolean;
+}
+/**
+ * Security analytics filter.
+ */
+export interface SecurityAnalyticsFilter extends DateRangeFilter {
+    /** Event type filter */
+    eventType?: SecurityEventType | SecurityEventType[];
+    /** User ID filter */
+    userId?: string;
+    /** Severity filter */
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    /** Success filter */
+    success?: boolean;
+}
+/**
+ * Security risk assessment.
+ */
+export interface SecurityRiskAssessment {
+    /** User ID */
+    userId: string;
+    /** Risk score (0-100) */
+    riskScore: number;
+    /** Risk level */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Risk factors */
+    factors: Array<{
+        factor: string;
+        contribution: number;
+        details: string;
+    }>;
+    /** Last assessment date */
+    assessedAt: string;
+    /** Recommended actions */
+    recommendations: string[];
+}
+/**
+ * Security analytics result.
+ */
+export interface SecurityAnalytics {
+    /** Total security events */
+    totalEvents: number;
+    /** Failed login count */
+    failedLogins: number;
+    /** Failed login rate */
+    failedLoginRate: number;
+    /** Suspicious activity count */
+    suspiciousActivityCount: number;
+    /** Role changes */
+    roleChanges: number;
+    /** Data access events */
+    dataAccessEvents: number;
+    /** By event type */
+    byEventType: Array<{
+        type: string;
+        count: number;
+    }>;
+    /** High risk users */
+    highRiskUsers: number;
+    /** Trend */
+    trend: TimeSeriesData;
+}
+/**
+ * Compliance report.
+ */
+export interface ComplianceReport {
+    /** Report period */
+    period: DateRangeFilter;
+    /** Regulation */
+    regulation: string;
+    /** Consent stats */
+    consentStats: {
+        totalConsents: number;
+        activeConsents: number;
+        withdrawals: number;
+    };
+    /** Data requests */
+    dataRequests: {
+        accessRequests: number;
+        deletionRequests: number;
+        portabilityRequests: number;
+        avgResponseTimeHours: number;
+    };
+    /** Compliance score */
+    complianceScore: number;
+    /** Issues */
+    issues: Array<{
+        type: string;
+        severity: string;
+        description: string;
+    }>;
+}
+/**
+ * Classify risk level from score.
+ */
+export declare function classifyRiskLevel(score: number): 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Calculate failed login rate.
+ */
+export declare function calculateFailedLoginRate(failed: number, total: number): number;
+/**
+ * Check if login pattern is suspicious.
+ */
+export declare function isSuspiciousLoginPattern(failedAttempts: number, timeWindowMinutes: number, threshold?: number): boolean;
+/**
+ * Determine event severity.
+ */
+export declare function determineEventSeverity(eventType: SecurityEventType, success: boolean): 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Security and compliance analytics class.
+ */
+export declare class SecurityAnalytics extends EnterpriseFTRPC {
+    /**
+     * Track login attempt.
+     */
+    trackLoginAttempt(config: LoginAttemptConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track logout.
+     */
+    trackLogout(userId: string, sessionId?: string): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track password change.
+     */
+    trackPasswordChange(userId: string, forced?: boolean): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track role change.
+     */
+    trackRoleChange(config: RoleChangeConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track permission change.
+     */
+    trackPermissionChange(config: PermissionChangeConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track data access.
+     */
+    trackDataAccess(config: DataAccessConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track data export.
+     */
+    trackDataExport(userId: string, resourceType: string, recordCount: number): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track suspicious activity.
+     */
+    trackSuspiciousActivity(userId: string, activityType: string, details: Record<string, unknown>): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track compliance event.
+     */
+    trackComplianceEvent(config: ComplianceEventConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Get audit log.
+     */
+    getAuditLog(filter?: SecurityAnalyticsFilter, limit?: number): Promise<{
+        entries: AuditLogEntry[];
+        total: number;
+    }>;
+    /**
+     * Get user risk assessment.
+     */
+    getUserRiskAssessment(userId: string): Promise<SecurityRiskAssessment>;
+    /**
+     * Get high risk users.
+     */
+    getHighRiskUsers(minScore?: number, limit?: number): Promise<SecurityRiskAssessment[]>;
+    /**
+     * Get security analytics.
+     */
+    getAnalytics(filter?: SecurityAnalyticsFilter): Promise<SecurityAnalytics>;
+    /**
+     * Get compliance report.
+     */
+    getComplianceReport(regulation: 'GDPR' | 'CCPA' | 'HIPAA' | 'SOC2', filter?: DateRangeFilter): Promise<ComplianceReport>;
+    /**
+     * Get login analytics.
+     */
+    getLoginAnalytics(filter?: DateRangeFilter): Promise<{
+        totalAttempts: number;
+        successful: number;
+        failed: number;
+        failedRate: number;
+        uniqueUsers: number;
+        byLocation: Array<{
+            location: string;
+            count: number;
+        }>;
+        byDevice: Array<{
+            device: string;
+            count: number;
+        }>;
+        trend: TimeSeriesData;
+    }>;
+    /**
+     * Get security trend.
+     */
+    getSecurityTrend(filter?: SecurityAnalyticsFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get data access patterns.
+     */
+    getDataAccessPatterns(userId?: string, filter?: DateRangeFilter): Promise<Array<{
+        resourceType: string;
+        accessCount: number;
+        uniqueUsers: number;
+        lastAccess: string;
+    }>>;
+}