@savvagent/sdk 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -28,22 +28,25 @@ interface FlagClientConfig {
 }
 /**
  * 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 +108,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 +157,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
@@ -199,6 +242,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 +407,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 +427,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 +453,7 @@ declare class RealtimeService {
      */
     private handleMessage;
     /**
-     * Handle disconnection and attempt reconnect
+     * Handle disconnection and attempt reconnect with exponential backoff
      */
     private handleDisconnect;
     /**
@@ -596,4 +750,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

@@ -28,22 +28,25 @@ interface FlagClientConfig {
 }
 /**
  * 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 +108,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 +157,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
@@ -199,6 +242,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 +407,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 +427,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 +453,7 @@ declare class RealtimeService {
      */
     private handleMessage;
     /**
-     * Handle disconnection and attempt reconnect
+     * Handle disconnection and attempt reconnect with exponential backoff
      */
     private handleDisconnect;
     /**
@@ -596,4 +750,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 };