@savvagent/sdk 1.0.0 → 1.1.0

package/README.md

@@ -159,6 +159,9 @@ interface FlagClientConfig {
   /** Base URL for the Savvagent API (default: production) */
   baseUrl?: string;
 
+  /** Environment for flag evaluation (default: 'production') */
+  environment?: string;
+
   /** Enable real-time flag updates via SSE (default: true) */
   enableRealtime?: boolean;
 
@@ -182,6 +185,7 @@ interface FlagClientConfig {
 const client = new FlagClient({
   apiKey: 'sdk_dev_abc123',
   baseUrl: 'https://api.savvagent.com',
+  environment: 'staging', // Use staging environment flags
   enableRealtime: true,
   cacheTtl: 30000, // 30 seconds
   enableTelemetry: true,
@@ -196,6 +200,47 @@ const client = new FlagClient({
 });
 ```
 
+### Environment Configuration
+
+The `environment` option controls which environment's flag values are used during evaluation. Common values include:
+
+- `'production'` (default) - Production environment
+- `'staging'` - Staging/pre-production environment
+- `'development'` - Local development environment
+- `'beta'` - Beta testing environment
+
+```typescript
+// Production app
+const client = new FlagClient({
+  apiKey: 'sdk_prod_...',
+  environment: 'production',
+});
+
+// Staging/QA app
+const client = new FlagClient({
+  apiKey: 'sdk_staging_...',
+  environment: 'staging',
+});
+
+// Development
+const client = new FlagClient({
+  apiKey: 'sdk_dev_...',
+  environment: 'development',
+});
+```
+
+You can also change the environment at runtime:
+
+```typescript
+// Switch to beta environment
+client.setEnvironment('beta');
+
+// Get current environment
+console.log(client.getEnvironment()); // 'beta'
+```
+
+Note: Changing the environment clears the cache since flag values may differ between environments.
+
 ## Framework Integration
 
 ### React
@@ -408,6 +453,10 @@ const client = new FlagClient({
 - `withFlag(flagKey, callback, context?)`: Execute code conditionally
 - `trackError(flagKey, error, context?)`: Manually track an error
 - `subscribe(flagKey, callback)`: Subscribe to flag updates
+- `setEnvironment(environment)`: Set the environment for flag evaluation
+- `getEnvironment()`: Get the current environment
+- `setUserId(userId)`: Set the user ID for targeted rollouts
+- `getUserId()`: Get the current user ID
 - `getCachedFlags()`: Get all cached flag keys
 - `clearCache()`: Clear the flag cache
 - `isRealtimeConnected()`: Check real-time connection status

package/dist/index.d.mts

@@ -11,6 +11,8 @@ interface FlagClientConfig {
     applicationId?: string;
     /** Base URL for the Savvagent API (default: production URL) */
     baseUrl?: string;
+    /** Environment for flag evaluation (e.g., "development", "staging", "production", "beta"). Default: "production" */
+    environment?: string;
     /** Enable real-time flag updates via SSE (default: true) */
     enableRealtime?: boolean;
     /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
@@ -25,25 +27,34 @@ interface FlagClientConfig {
     defaultLanguage?: string;
     /** Disable automatic browser language detection (default: false) */
     disableLanguageDetection?: boolean;
+    /** Number of retry attempts for transient failures (default: 3) */
+    retryAttempts?: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Retry backoff strategy: 'linear' or 'exponential' (default: 'exponential') */
+    retryBackoff?: 'linear' | 'exponential';
 }
 /**
  * Context passed to flag evaluation
+ * Per SDK Developer Guide: https://docs.savvagent.com/sdk-developer-guide
  */
 interface FlagContext {
-    /** User ID for targeted rollouts (logged-in users) */
+    /** User ID for targeted rollouts (logged-in users) - required for percentage rollouts */
     user_id?: string;
-    /** Anonymous ID for consistent rollouts (anonymous users) */
+    /** Anonymous ID for consistent rollouts (anonymous users) - alternative to user_id */
     anonymous_id?: string;
     /** Session ID as fallback identifier */
     session_id?: string;
-    /** Application ID for application-scoped flags (auto-injected from config) */
+    /** Target environment (e.g., "production", "staging") */
+    environment?: string;
+    /** Organization ID for multi-tenant apps */
+    organization_id?: string;
+    /** Application ID for hierarchical flag lookup (auto-injected from config) */
     application_id?: string;
-    /** User's language for language targeting (BCP 47 format, e.g., "en", "en-US") */
+    /** User's language code (e.g., "en", "es") */
     language?: string;
     /** Custom attributes for targeting rules */
     attributes?: Record<string, any>;
-    /** Environment (dev, staging, production) */
-    environment?: string;
 }
 /**
  * Result from flag evaluation
@@ -105,6 +116,43 @@ interface FlagUpdateEvent {
     flagKey: string;
     data?: any;
 }
+/**
+ * Flag definition returned from getAllFlags endpoint
+ * Per SDK Developer Guide: GET /api/sdk/flags
+ */
+interface FlagDefinition {
+    /** Flag key */
+    key: string;
+    /** Enabled state for the requested environment */
+    enabled: boolean;
+    /** Flag scope: "application" or "enterprise" */
+    scope: 'application' | 'enterprise';
+    /** Environment configuration with enabled state and rollout percentage */
+    environments: Record<string, {
+        enabled: boolean;
+        rollout_percentage?: number;
+    }>;
+    /** Variation definitions for A/B testing (if any) */
+    variations?: Record<string, any> | null;
+    /** Dynamic configuration attached to the flag */
+    configuration?: any;
+    /** Flag version for cache invalidation */
+    version: number;
+}
+/**
+ * Response from getAllFlags endpoint
+ * Per SDK Developer Guide: GET /api/sdk/flags
+ */
+interface FlagListResponse {
+    /** List of flag definitions */
+    flags: FlagDefinition[];
+    /** Total count of flags returned */
+    count: number;
+    /** Organization ID */
+    organization_id: string;
+    /** Application ID (present for SDK key auth) */
+    application_id?: string;
+}
 
 /**
  * Savvagent Client for feature flag evaluation with AI-powered error detection
@@ -117,6 +165,9 @@ declare class FlagClient {
     private anonymousId;
     private userId;
     private detectedLanguage;
+    private overrides;
+    private overrideListeners;
+    private authFailed;
     constructor(config: FlagClientConfig);
     /**
      * Get or create an anonymous ID for consistent flag evaluation
@@ -139,6 +190,16 @@ declare class FlagClient {
      * Get the current user ID
      */
     getUserId(): string | null;
+    /**
+     * Set the environment for flag evaluation
+     * Useful for dynamically switching environments (e.g., dev tools)
+     * @param environment - The environment name (e.g., "development", "staging", "production", "beta")
+     */
+    setEnvironment(environment: string): void;
+    /**
+     * Get the current environment
+     */
+    getEnvironment(): string;
     /**
      * Get the current anonymous ID
      */
@@ -148,6 +209,23 @@ declare class FlagClient {
      * @param overrides - Context overrides
      */
     private buildContext;
+    /**
+     * Check if an error is retryable (transient failure)
+     * @param error - The error to check
+     * @param status - HTTP status code (if available)
+     */
+    private isRetryableError;
+    /**
+     * Calculate delay for retry attempt
+     * @param attempt - Current attempt number (1-based)
+     */
+    private getRetryDelay;
+    /**
+     * Execute a fetch request with retry logic
+     * @param requestFn - Function that returns a fetch promise
+     * @param operationName - Name of the operation for logging
+     */
+    private fetchWithRetry;
     /**
      * Check if a feature flag is enabled
      * @param flagKey - The flag key to evaluate
@@ -199,6 +277,110 @@ declare class FlagClient {
      * Close the client and cleanup resources
      */
     close(): void;
+    /**
+     * Set a local override for a flag.
+     * Overrides take precedence over server values and cache.
+     *
+     * @param flagKey - The flag key to override
+     * @param value - The override value (true/false)
+     *
+     * @example
+     * ```typescript
+     * // Force a flag to be enabled locally
+     * client.setOverride('new-feature', true);
+     * ```
+     */
+    setOverride(flagKey: string, value: boolean): void;
+    /**
+     * Clear a local override for a flag.
+     * The flag will return to using server/cached values.
+     *
+     * @param flagKey - The flag key to clear override for
+     */
+    clearOverride(flagKey: string): void;
+    /**
+     * Clear all local overrides.
+     */
+    clearAllOverrides(): void;
+    /**
+     * Check if a flag has a local override.
+     *
+     * @param flagKey - The flag key to check
+     * @returns true if the flag has an override
+     */
+    hasOverride(flagKey: string): boolean;
+    /**
+     * Get the override value for a flag.
+     *
+     * @param flagKey - The flag key to get override for
+     * @returns The override value, or undefined if not set
+     */
+    getOverride(flagKey: string): boolean | undefined;
+    /**
+     * Get all current overrides.
+     *
+     * @returns Record of flag keys to override values
+     */
+    getOverrides(): Record<string, boolean>;
+    /**
+     * Set multiple overrides at once.
+     *
+     * @param overrides - Record of flag keys to override values
+     */
+    setOverrides(overrides: Record<string, boolean>): void;
+    /**
+     * Subscribe to override changes.
+     * Useful for React components to re-render when overrides change.
+     *
+     * @param callback - Function to call when overrides change
+     * @returns Unsubscribe function
+     */
+    onOverrideChange(callback: () => void): () => void;
+    /**
+     * Notify all override listeners of a change.
+     */
+    private notifyOverrideListeners;
+    /**
+     * Get all flags for the application (and enterprise-scoped flags).
+     * Per SDK Developer Guide: GET /api/sdk/flags
+     *
+     * Use cases:
+     * - Local override UI: Display all available flags for developers to toggle
+     * - Offline mode: Pre-fetch flags for mobile/desktop apps
+     * - SDK initialization: Bootstrap SDK with all flag values on startup
+     * - DevTools integration: Show available flags in browser dev panels
+     *
+     * @param environment - Environment to evaluate enabled state for (default: 'development')
+     * @returns Promise<FlagDefinition[]> - List of flag definitions
+     *
+     * @example
+     * ```typescript
+     * // Fetch all flags for development
+     * const flags = await client.getAllFlags('development');
+     *
+     * // Bootstrap local cache
+     * flags.forEach(flag => {
+     *   console.log(`${flag.key}: ${flag.enabled}`);
+     * });
+     * ```
+     */
+    getAllFlags(environment?: string): Promise<FlagDefinition[]>;
+    /**
+     * Get only enterprise-scoped flags for the organization.
+     * Per SDK Developer Guide: GET /api/sdk/enterprise-flags
+     *
+     * Enterprise flags are shared across all applications in the organization.
+     *
+     * @param environment - Environment to evaluate enabled state for (default: 'development')
+     * @returns Promise<FlagDefinition[]> - List of enterprise flag definitions
+     *
+     * @example
+     * ```typescript
+     * // Fetch enterprise-only flags
+     * const enterpriseFlags = await client.getEnterpriseFlags('production');
+     * ```
+     */
+    getEnterpriseFlags(environment?: string): Promise<FlagDefinition[]>;
 }
 
 /**
@@ -260,10 +442,12 @@ declare class TelemetryService {
     private flush;
     /**
      * Send evaluation events to backend
+     * Per SDK Developer Guide: POST /api/telemetry/evaluations with { "evaluations": [...] }
      */
     private sendEvaluations;
     /**
      * Send error events to backend
+     * Per SDK Developer Guide: POST /api/telemetry/errors with { "errors": [...] }
      */
     private sendErrors;
     /**
@@ -278,20 +462,25 @@ declare class TelemetryService {
 
 /**
  * Real-time updates service using Server-Sent Events (SSE)
+ * Uses @microsoft/fetch-event-source to support custom headers for authentication
+ * (native EventSource doesn't support custom headers)
  */
 declare class RealtimeService {
     private baseUrl;
     private apiKey;
-    private eventSource;
+    private abortController;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectDelay;
     private maxReconnectDelay;
     private listeners;
     private onConnectionChange?;
+    private connected;
+    private authFailed;
     constructor(baseUrl: string, apiKey: string, onConnectionChange?: (connected: boolean) => void);
     /**
-     * Connect to SSE stream
+     * Connect to SSE stream using header-based authentication
+     * Per SDK Developer Guide: "Never pass API keys as query parameters"
      */
     connect(): void;
     /**
@@ -299,7 +488,7 @@ declare class RealtimeService {
      */
     private handleMessage;
     /**
-     * Handle disconnection and attempt reconnect
+     * Handle disconnection and attempt reconnect with exponential backoff
      */
     private handleDisconnect;
     /**
@@ -596,4 +785,4 @@ interface components {
     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 };
+export { type components as ApiTypes, type CacheEntry, type ErrorEvent, type EvaluationEvent, FlagCache, FlagClient, type FlagClientConfig, type FlagContext, type FlagDefinition, type FlagEvaluationResult, type FlagListResponse, type FlagUpdateEvent, RealtimeService, TelemetryService, type components };

package/dist/index.d.ts

@@ -11,6 +11,8 @@ interface FlagClientConfig {
     applicationId?: string;
     /** Base URL for the Savvagent API (default: production URL) */
     baseUrl?: string;
+    /** Environment for flag evaluation (e.g., "development", "staging", "production", "beta"). Default: "production" */
+    environment?: string;
     /** Enable real-time flag updates via SSE (default: true) */
     enableRealtime?: boolean;
     /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
@@ -25,25 +27,34 @@ interface FlagClientConfig {
     defaultLanguage?: string;
     /** Disable automatic browser language detection (default: false) */
     disableLanguageDetection?: boolean;
+    /** Number of retry attempts for transient failures (default: 3) */
+    retryAttempts?: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Retry backoff strategy: 'linear' or 'exponential' (default: 'exponential') */
+    retryBackoff?: 'linear' | 'exponential';
 }
 /**
  * Context passed to flag evaluation
+ * Per SDK Developer Guide: https://docs.savvagent.com/sdk-developer-guide
  */
 interface FlagContext {
-    /** User ID for targeted rollouts (logged-in users) */
+    /** User ID for targeted rollouts (logged-in users) - required for percentage rollouts */
     user_id?: string;
-    /** Anonymous ID for consistent rollouts (anonymous users) */
+    /** Anonymous ID for consistent rollouts (anonymous users) - alternative to user_id */
     anonymous_id?: string;
     /** Session ID as fallback identifier */
     session_id?: string;
-    /** Application ID for application-scoped flags (auto-injected from config) */
+    /** Target environment (e.g., "production", "staging") */
+    environment?: string;
+    /** Organization ID for multi-tenant apps */
+    organization_id?: string;
+    /** Application ID for hierarchical flag lookup (auto-injected from config) */
     application_id?: string;
-    /** User's language for language targeting (BCP 47 format, e.g., "en", "en-US") */
+    /** User's language code (e.g., "en", "es") */
     language?: string;
     /** Custom attributes for targeting rules */
     attributes?: Record<string, any>;
-    /** Environment (dev, staging, production) */
-    environment?: string;
 }
 /**
  * Result from flag evaluation
@@ -105,6 +116,43 @@ interface FlagUpdateEvent {
     flagKey: string;
     data?: any;
 }
+/**
+ * Flag definition returned from getAllFlags endpoint
+ * Per SDK Developer Guide: GET /api/sdk/flags
+ */
+interface FlagDefinition {
+    /** Flag key */
+    key: string;
+    /** Enabled state for the requested environment */
+    enabled: boolean;
+    /** Flag scope: "application" or "enterprise" */
+    scope: 'application' | 'enterprise';
+    /** Environment configuration with enabled state and rollout percentage */
+    environments: Record<string, {
+        enabled: boolean;
+        rollout_percentage?: number;
+    }>;
+    /** Variation definitions for A/B testing (if any) */
+    variations?: Record<string, any> | null;
+    /** Dynamic configuration attached to the flag */
+    configuration?: any;
+    /** Flag version for cache invalidation */
+    version: number;
+}
+/**
+ * Response from getAllFlags endpoint
+ * Per SDK Developer Guide: GET /api/sdk/flags
+ */
+interface FlagListResponse {
+    /** List of flag definitions */
+    flags: FlagDefinition[];
+    /** Total count of flags returned */
+    count: number;
+    /** Organization ID */
+    organization_id: string;
+    /** Application ID (present for SDK key auth) */
+    application_id?: string;
+}
 
 /**
  * Savvagent Client for feature flag evaluation with AI-powered error detection
@@ -117,6 +165,9 @@ declare class FlagClient {
     private anonymousId;
     private userId;
     private detectedLanguage;
+    private overrides;
+    private overrideListeners;
+    private authFailed;
     constructor(config: FlagClientConfig);
     /**
      * Get or create an anonymous ID for consistent flag evaluation
@@ -139,6 +190,16 @@ declare class FlagClient {
      * Get the current user ID
      */
     getUserId(): string | null;
+    /**
+     * Set the environment for flag evaluation
+     * Useful for dynamically switching environments (e.g., dev tools)
+     * @param environment - The environment name (e.g., "development", "staging", "production", "beta")
+     */
+    setEnvironment(environment: string): void;
+    /**
+     * Get the current environment
+     */
+    getEnvironment(): string;
     /**
      * Get the current anonymous ID
      */
@@ -148,6 +209,23 @@ declare class FlagClient {
      * @param overrides - Context overrides
      */
     private buildContext;
+    /**
+     * Check if an error is retryable (transient failure)
+     * @param error - The error to check
+     * @param status - HTTP status code (if available)
+     */
+    private isRetryableError;
+    /**
+     * Calculate delay for retry attempt
+     * @param attempt - Current attempt number (1-based)
+     */
+    private getRetryDelay;
+    /**
+     * Execute a fetch request with retry logic
+     * @param requestFn - Function that returns a fetch promise
+     * @param operationName - Name of the operation for logging
+     */
+    private fetchWithRetry;
     /**
      * Check if a feature flag is enabled
      * @param flagKey - The flag key to evaluate
@@ -199,6 +277,110 @@ declare class FlagClient {
      * Close the client and cleanup resources
      */
     close(): void;
+    /**
+     * Set a local override for a flag.
+     * Overrides take precedence over server values and cache.
+     *
+     * @param flagKey - The flag key to override
+     * @param value - The override value (true/false)
+     *
+     * @example
+     * ```typescript
+     * // Force a flag to be enabled locally
+     * client.setOverride('new-feature', true);
+     * ```
+     */
+    setOverride(flagKey: string, value: boolean): void;
+    /**
+     * Clear a local override for a flag.
+     * The flag will return to using server/cached values.
+     *
+     * @param flagKey - The flag key to clear override for
+     */
+    clearOverride(flagKey: string): void;
+    /**
+     * Clear all local overrides.
+     */
+    clearAllOverrides(): void;
+    /**
+     * Check if a flag has a local override.
+     *
+     * @param flagKey - The flag key to check
+     * @returns true if the flag has an override
+     */
+    hasOverride(flagKey: string): boolean;
+    /**
+     * Get the override value for a flag.
+     *
+     * @param flagKey - The flag key to get override for
+     * @returns The override value, or undefined if not set
+     */
+    getOverride(flagKey: string): boolean | undefined;
+    /**
+     * Get all current overrides.
+     *
+     * @returns Record of flag keys to override values
+     */
+    getOverrides(): Record<string, boolean>;
+    /**
+     * Set multiple overrides at once.
+     *
+     * @param overrides - Record of flag keys to override values
+     */
+    setOverrides(overrides: Record<string, boolean>): void;
+    /**
+     * Subscribe to override changes.
+     * Useful for React components to re-render when overrides change.
+     *
+     * @param callback - Function to call when overrides change
+     * @returns Unsubscribe function
+     */
+    onOverrideChange(callback: () => void): () => void;
+    /**
+     * Notify all override listeners of a change.
+     */
+    private notifyOverrideListeners;
+    /**
+     * Get all flags for the application (and enterprise-scoped flags).
+     * Per SDK Developer Guide: GET /api/sdk/flags
+     *
+     * Use cases:
+     * - Local override UI: Display all available flags for developers to toggle
+     * - Offline mode: Pre-fetch flags for mobile/desktop apps
+     * - SDK initialization: Bootstrap SDK with all flag values on startup
+     * - DevTools integration: Show available flags in browser dev panels
+     *
+     * @param environment - Environment to evaluate enabled state for (default: 'development')
+     * @returns Promise<FlagDefinition[]> - List of flag definitions
+     *
+     * @example
+     * ```typescript
+     * // Fetch all flags for development
+     * const flags = await client.getAllFlags('development');
+     *
+     * // Bootstrap local cache
+     * flags.forEach(flag => {
+     *   console.log(`${flag.key}: ${flag.enabled}`);
+     * });
+     * ```
+     */
+    getAllFlags(environment?: string): Promise<FlagDefinition[]>;
+    /**
+     * Get only enterprise-scoped flags for the organization.
+     * Per SDK Developer Guide: GET /api/sdk/enterprise-flags
+     *
+     * Enterprise flags are shared across all applications in the organization.
+     *
+     * @param environment - Environment to evaluate enabled state for (default: 'development')
+     * @returns Promise<FlagDefinition[]> - List of enterprise flag definitions
+     *
+     * @example
+     * ```typescript
+     * // Fetch enterprise-only flags
+     * const enterpriseFlags = await client.getEnterpriseFlags('production');
+     * ```
+     */
+    getEnterpriseFlags(environment?: string): Promise<FlagDefinition[]>;
 }
 
 /**
@@ -260,10 +442,12 @@ declare class TelemetryService {
     private flush;
     /**
      * Send evaluation events to backend
+     * Per SDK Developer Guide: POST /api/telemetry/evaluations with { "evaluations": [...] }
      */
     private sendEvaluations;
     /**
      * Send error events to backend
+     * Per SDK Developer Guide: POST /api/telemetry/errors with { "errors": [...] }
      */
     private sendErrors;
     /**
@@ -278,20 +462,25 @@ declare class TelemetryService {
 
 /**
  * Real-time updates service using Server-Sent Events (SSE)
+ * Uses @microsoft/fetch-event-source to support custom headers for authentication
+ * (native EventSource doesn't support custom headers)
  */
 declare class RealtimeService {
     private baseUrl;
     private apiKey;
-    private eventSource;
+    private abortController;
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectDelay;
     private maxReconnectDelay;
     private listeners;
     private onConnectionChange?;
+    private connected;
+    private authFailed;
     constructor(baseUrl: string, apiKey: string, onConnectionChange?: (connected: boolean) => void);
     /**
-     * Connect to SSE stream
+     * Connect to SSE stream using header-based authentication
+     * Per SDK Developer Guide: "Never pass API keys as query parameters"
      */
     connect(): void;
     /**
@@ -299,7 +488,7 @@ declare class RealtimeService {
      */
     private handleMessage;
     /**
-     * Handle disconnection and attempt reconnect
+     * Handle disconnection and attempt reconnect with exponential backoff
      */
     private handleDisconnect;
     /**
@@ -596,4 +785,4 @@ interface components {
     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 };
+export { type components as ApiTypes, type CacheEntry, type ErrorEvent, type EvaluationEvent, FlagCache, FlagClient, type FlagClientConfig, type FlagContext, type FlagDefinition, type FlagEvaluationResult, type FlagListResponse, type FlagUpdateEvent, RealtimeService, TelemetryService, type components };