@savvagent/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,599 @@
+/**
+ * Savvagent SDK Types
+ */
+/**
+ * Configuration for initializing the FlagClient
+ */
+interface FlagClientConfig {
+    /** SDK API key (starts with sdk_) */
+    apiKey: string;
+    /** Application ID for application-scoped flags (omit for enterprise flags only) */
+    applicationId?: string;
+    /** Base URL for the Savvagent API (default: production URL) */
+    baseUrl?: string;
+    /** Enable real-time flag updates via SSE (default: true) */
+    enableRealtime?: boolean;
+    /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+    cacheTtl?: number;
+    /** Enable telemetry tracking (default: true) */
+    enableTelemetry?: boolean;
+    /** Default flag values when evaluation fails */
+    defaults?: Record<string, boolean>;
+    /** Custom error handler */
+    onError?: (error: Error) => void;
+    /** Default language for targeting (overrides browser detection) */
+    defaultLanguage?: string;
+    /** Disable automatic browser language detection (default: false) */
+    disableLanguageDetection?: boolean;
+}
+/**
+ * Context passed to flag evaluation
+ */
+interface FlagContext {
+    /** User ID for targeted rollouts (logged-in users) */
+    user_id?: string;
+    /** Anonymous ID for consistent rollouts (anonymous users) */
+    anonymous_id?: string;
+    /** Session ID as fallback identifier */
+    session_id?: string;
+    /** Application ID for application-scoped flags (auto-injected from config) */
+    application_id?: string;
+    /** User's language for language targeting (BCP 47 format, e.g., "en", "en-US") */
+    language?: string;
+    /** Custom attributes for targeting rules */
+    attributes?: Record<string, any>;
+    /** Environment (dev, staging, production) */
+    environment?: string;
+}
+/**
+ * Result from flag evaluation
+ */
+interface FlagEvaluationResult {
+    /** Flag key */
+    key: string;
+    /** Evaluated value */
+    value: boolean;
+    /** Reason for the value (cached, evaluated, default) */
+    reason: 'cached' | 'evaluated' | 'default' | 'error';
+    /** Metadata about the flag */
+    metadata?: {
+        flagId?: string;
+        description?: string;
+        scope?: string | null;
+        configuration?: any;
+        variation?: string | null;
+        timestamp?: number;
+    };
+}
+/**
+ * Telemetry event for flag evaluation
+ */
+interface EvaluationEvent {
+    flagKey: string;
+    result: boolean;
+    context?: FlagContext;
+    durationMs: number;
+    traceId?: string;
+    timestamp: string;
+}
+/**
+ * Telemetry event for errors in flagged code
+ */
+interface ErrorEvent {
+    flagKey: string;
+    flagEnabled: boolean;
+    errorType: string;
+    errorMessage: string;
+    stackTrace?: string;
+    context?: FlagContext;
+    traceId?: string;
+    timestamp: string;
+}
+/**
+ * Cache entry for flag values
+ */
+interface CacheEntry {
+    value: boolean;
+    expiresAt: number;
+    flagId?: string;
+}
+/**
+ * Real-time update event from SSE
+ */
+interface FlagUpdateEvent {
+    type: 'flag.updated' | 'flag.deleted' | 'flag.created';
+    flagKey: string;
+    data?: any;
+}
+
+/**
+ * Savvagent Client for feature flag evaluation with AI-powered error detection
+ */
+declare class FlagClient {
+    private config;
+    private cache;
+    private telemetry;
+    private realtime;
+    private anonymousId;
+    private userId;
+    private detectedLanguage;
+    constructor(config: FlagClientConfig);
+    /**
+     * Get or create an anonymous ID for consistent flag evaluation
+     * @returns Anonymous ID from localStorage or newly generated
+     */
+    private getOrCreateAnonymousId;
+    /**
+     * Set a custom anonymous ID
+     * Useful for cross-device tracking or custom identifier schemes
+     * @param id - The anonymous ID to use
+     */
+    setAnonymousId(id: string): void;
+    /**
+     * Set the user ID for logged-in users
+     * This takes precedence over anonymous ID
+     * @param userId - The user ID (or null to clear)
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Get the current user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Get the current anonymous ID
+     */
+    getAnonymousId(): string;
+    /**
+     * Build the context for flag evaluation
+     * @param overrides - Context overrides
+     */
+    private buildContext;
+    /**
+     * Check if a feature flag is enabled
+     * @param flagKey - The flag key to evaluate
+     * @param context - Optional context for targeting
+     * @returns Promise<boolean>
+     */
+    isEnabled(flagKey: string, context?: FlagContext): Promise<boolean>;
+    /**
+     * Evaluate a feature flag and return detailed result
+     * @param flagKey - The flag key to evaluate
+     * @param context - Optional context for targeting
+     * @returns Promise<FlagEvaluationResult>
+     */
+    evaluate(flagKey: string, context?: FlagContext): Promise<FlagEvaluationResult>;
+    /**
+     * Execute code conditionally based on flag value
+     * @param flagKey - The flag key to check
+     * @param callback - Function to execute if flag is enabled
+     * @param context - Optional context for targeting
+     */
+    withFlag<T>(flagKey: string, callback: () => T | Promise<T>, context?: FlagContext): Promise<T | null>;
+    /**
+     * Manually track an error with flag context
+     * @param flagKey - The flag key associated with the error
+     * @param error - The error that occurred
+     * @param context - Optional context
+     */
+    trackError(flagKey: string, error: Error, context?: FlagContext): void;
+    /**
+     * Subscribe to real-time updates for a specific flag
+     * @param flagKey - Flag key or '*' for all flags
+     * @param callback - Callback when flag is updated
+     * @returns Unsubscribe function
+     */
+    subscribe(flagKey: string, callback: () => void): () => void;
+    /**
+     * Get all cached flag keys
+     */
+    getCachedFlags(): string[];
+    /**
+     * Clear the flag cache
+     */
+    clearCache(): void;
+    /**
+     * Check if real-time connection is active
+     */
+    isRealtimeConnected(): boolean;
+    /**
+     * Close the client and cleanup resources
+     */
+    close(): void;
+}
+
+/**
+ * Simple in-memory cache for flag values with TTL
+ */
+declare class FlagCache {
+    private cache;
+    private ttl;
+    constructor(ttl?: number);
+    /**
+     * Get a cached flag value
+     */
+    get(key: string): boolean | null;
+    /**
+     * Set a flag value in cache
+     */
+    set(key: string, value: boolean, flagId?: string): void;
+    /**
+     * Invalidate a specific flag
+     */
+    invalidate(key: string): void;
+    /**
+     * Clear all cached flags
+     */
+    clear(): void;
+    /**
+     * Get all cached keys
+     */
+    keys(): string[];
+}
+
+/**
+ * Telemetry service for tracking flag evaluations and errors
+ */
+declare class TelemetryService {
+    private baseUrl;
+    private apiKey;
+    private enabled;
+    private queue;
+    private flushInterval;
+    private maxBatchSize;
+    private timer;
+    constructor(baseUrl: string, apiKey: string, enabled?: boolean);
+    /**
+     * Track a flag evaluation
+     */
+    trackEvaluation(event: EvaluationEvent): void;
+    /**
+     * Track an error in flagged code
+     */
+    trackError(event: ErrorEvent): void;
+    /**
+     * Start the batch sender interval
+     */
+    private startBatchSender;
+    /**
+     * Flush the telemetry queue
+     */
+    private flush;
+    /**
+     * Send evaluation events to backend
+     */
+    private sendEvaluations;
+    /**
+     * Send error events to backend
+     */
+    private sendErrors;
+    /**
+     * Stop the telemetry service
+     */
+    stop(): void;
+    /**
+     * Generate a trace ID for distributed tracing
+     */
+    static generateTraceId(): string;
+}
+
+/**
+ * Real-time updates service using Server-Sent Events (SSE)
+ */
+declare class RealtimeService {
+    private baseUrl;
+    private apiKey;
+    private eventSource;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private maxReconnectDelay;
+    private listeners;
+    private onConnectionChange?;
+    constructor(baseUrl: string, apiKey: string, onConnectionChange?: (connected: boolean) => void);
+    /**
+     * Connect to SSE stream
+     */
+    connect(): void;
+    /**
+     * Handle incoming SSE messages
+     */
+    private handleMessage;
+    /**
+     * Handle disconnection and attempt reconnect
+     */
+    private handleDisconnect;
+    /**
+     * Subscribe to flag updates
+     * @param flagKey - Specific flag key or '*' for all flags
+     * @param listener - Callback function
+     */
+    subscribe(flagKey: string, listener: (event: FlagUpdateEvent) => void): () => void;
+    /**
+     * Disconnect from SSE stream
+     */
+    disconnect(): void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+}
+
+interface components {
+    schemas: {
+        ArchiveRequest: {
+            reason?: string | null;
+        };
+        ArchivedFlag: {
+            /** Format: uuid */
+            application_id?: string | null;
+            archive_reason?: string | null;
+            /** Format: date-time */
+            archived_at: string;
+            /** Format: uuid */
+            archived_by: string;
+            auto_disable_after_end?: boolean | null;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: uuid */
+            created_by?: string | null;
+            description?: string | null;
+            environments: components["schemas"]["JsonValue"];
+            /** Format: uuid */
+            id: string;
+            key: string;
+            name: string;
+            /** Format: uuid */
+            organization_id: string;
+            /** Format: date-time */
+            scheduled_end_at?: string | null;
+            /** Format: date-time */
+            scheduled_start_at?: string | null;
+            scheduling_timezone?: string | null;
+            scope: string;
+            status: string;
+            /** Format: date-time */
+            updated_at: string;
+            variations?: components["schemas"]["JsonValue"] | null;
+            /** Format: int32 */
+            version: number;
+        };
+        AuditLogQuery: {
+            action?: string | null;
+            /** Format: date-time */
+            end_date?: string | null;
+            /** Format: uuid */
+            flag_id?: string | null;
+            /** Format: int64 */
+            limit?: number | null;
+            /** Format: int64 */
+            offset?: number | null;
+            /** Format: uuid */
+            organization_id?: string | null;
+            /** Format: date-time */
+            start_date?: string | null;
+            /** Format: uuid */
+            user_id?: string | null;
+        };
+        CheckKeyQuery: {
+            key: string;
+        };
+        /**
+         * @example {
+         *       "application_id": "123e4567-e89b-12d3-a456-426614174002",
+         *       "description": "Experimental new feature",
+         *       "environments": {
+         *         "development": {
+         *           "enabled": true,
+         *           "rolloutPercentage": 100
+         *         },
+         *         "production": {
+         *           "enabled": false,
+         *           "rolloutPercentage": 0
+         *         }
+         *       },
+         *       "key": "new-feature",
+         *       "name": "New Feature",
+         *       "scope": "application"
+         *     }
+         */
+        CreateFlag: {
+            /** Format: uuid */
+            application_id?: string | null;
+            auto_disable_after_end?: boolean | null;
+            description?: string | null;
+            environments: components["schemas"]["JsonValue"];
+            key: string;
+            name: string;
+            /** Format: date-time */
+            scheduled_end_at?: string | null;
+            /** Format: date-time */
+            scheduled_start_at?: string | null;
+            scheduling_timezone?: string | null;
+            scope?: string | null;
+            variations?: components["schemas"]["JsonValue"] | null;
+        };
+        /**
+         * @example {
+         *       "context": {
+         *         "attributes": {
+         *           "country": "US",
+         *           "plan": "premium"
+         *         },
+         *         "user_id": "user-123"
+         *       }
+         *     }
+         */
+        EvaluateFlag: {
+            context?: components["schemas"]["JsonValue"] | null;
+        };
+        /**
+         * @example {
+         *       "application_id": "123e4567-e89b-12d3-a456-426614174002",
+         *       "description": "Enable new streamlined checkout experience",
+         *       "environments": {
+         *         "production": {
+         *           "enabled": true,
+         *           "rolloutPercentage": 25
+         *         }
+         *       },
+         *       "id": "123e4567-e89b-12d3-a456-426614174000",
+         *       "key": "new-checkout-flow",
+         *       "name": "New Checkout Flow",
+         *       "organization_id": "123e4567-e89b-12d3-a456-426614174001",
+         *       "scope": "application",
+         *       "status": "active",
+         *       "version": 1
+         *     }
+         */
+        FeatureFlag: {
+            /** Format: uuid */
+            application_id?: string | null;
+            auto_disable_after_end?: boolean | null;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: uuid */
+            created_by?: string | null;
+            description?: string | null;
+            environments: components["schemas"]["JsonValue"];
+            /** Format: uuid */
+            id: string;
+            key: string;
+            name: string;
+            /** Format: uuid */
+            organization_id: string;
+            /** Format: date-time */
+            scheduled_end_at?: string | null;
+            /** Format: date-time */
+            scheduled_start_at?: string | null;
+            scheduling_timezone?: string | null;
+            scope: string;
+            status: string;
+            /** Format: date-time */
+            updated_at: string;
+            variations?: components["schemas"]["JsonValue"] | null;
+            /** Format: int32 */
+            version: number;
+        };
+        FlagAuditLog: {
+            action: string;
+            changes?: components["schemas"]["JsonValue"] | null;
+            /** Format: uuid */
+            flag_id?: string | null;
+            flag_key: string;
+            /** Format: uuid */
+            id: string;
+            ip_address?: string | null;
+            /** Format: uuid */
+            organization_id: string;
+            /** Format: date-time */
+            timestamp: string;
+            user_agent?: string | null;
+            user_email?: string | null;
+            /** Format: uuid */
+            user_id?: string | null;
+        };
+        FlagError: {
+            ai_analysis?: components["schemas"]["JsonValue"] | null;
+            context?: components["schemas"]["JsonValue"] | null;
+            error_message?: string | null;
+            error_type: string;
+            flag_enabled: boolean;
+            /** Format: uuid */
+            flag_id: string;
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            organization_id: string;
+            stack_trace?: string | null;
+            /** Format: date-time */
+            timestamp: string;
+            trace_id?: string | null;
+        };
+        FlagEvaluation: {
+            context?: components["schemas"]["JsonValue"] | null;
+            /** Format: float */
+            duration_ms?: number | null;
+            /** Format: uuid */
+            flag_id: string;
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            organization_id: string;
+            result: boolean;
+            /** Format: date-time */
+            timestamp: string;
+            trace_id?: string | null;
+        };
+        /**
+         * @example {
+         *       "enabled": true,
+         *       "key": "new-checkout-flow",
+         *       "scope": "application",
+         *       "timestamp": 1699564800
+         *     }
+         */
+        FlagEvaluationResponse: {
+            configuration?: components["schemas"]["JsonValue"] | null;
+            context?: components["schemas"]["JsonValue"] | null;
+            enabled: boolean;
+            key: string;
+            scope?: string | null;
+            /** Format: int64 */
+            timestamp: number;
+            variation?: string | null;
+        };
+        /** @description Generic JSON value - can be any valid JSON type */
+        JsonValue: Record<string, never>;
+        ListFlagsQuery: {
+            /**
+             * Format: uuid
+             * @description Filter by application_id (only for application-scoped flags)
+             */
+            application_id?: string | null;
+            /**
+             * Format: uuid
+             * @description Filter by organization_id
+             */
+            organization_id?: string | null;
+            /** @description Filter by scope: 'enterprise', 'application', or omit for all */
+            scope?: string | null;
+        };
+        UpdateFlag: {
+            auto_disable_after_end?: boolean | null;
+            description?: string | null;
+            environments?: components["schemas"]["JsonValue"] | null;
+            name?: string | null;
+            /** Format: date-time */
+            scheduled_end_at?: string | null;
+            /** Format: date-time */
+            scheduled_start_at?: string | null;
+            scheduling_timezone?: string | null;
+            status?: string | null;
+            variations?: components["schemas"]["JsonValue"] | null;
+        };
+        UserActivity: {
+            email: string;
+            /** Format: int64 */
+            flags_archived?: number | null;
+            /** Format: int64 */
+            flags_created?: number | null;
+            /** Format: int64 */
+            flags_deleted?: number | null;
+            /** Format: int64 */
+            flags_updated?: number | null;
+            /** Format: date-time */
+            last_action_at?: string | null;
+            /** Format: int64 */
+            total_actions?: number | null;
+            /** Format: uuid */
+            user_id: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+export { type components as ApiTypes, type CacheEntry, type ErrorEvent, type EvaluationEvent, FlagCache, FlagClient, type FlagClientConfig, type FlagContext, type FlagEvaluationResult, type FlagUpdateEvent, RealtimeService, TelemetryService, type components };