@savvagent/sdk 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -120,15 +120,23 @@ var TelemetryService = class {
   }
   /**
    * Send evaluation events to backend
+   * Per SDK Developer Guide: POST /api/telemetry/evaluations with { "evaluations": [...] }
    */
   async sendEvaluations(events) {
+    const evaluations = events.map((e) => ({
+      flag_key: e.flagKey,
+      result: e.result,
+      user_id: e.context?.user_id,
+      context: e.context,
+      timestamp: Math.floor(new Date(e.timestamp).getTime() / 1e3)
+    }));
     const response = await fetch(`${this.baseUrl}/api/telemetry/evaluations`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
       },
-      body: JSON.stringify({ events })
+      body: JSON.stringify({ evaluations })
     });
     if (!response.ok) {
       throw new Error(`Failed to send evaluations: ${response.status}`);
@@ -136,15 +144,25 @@ var TelemetryService = class {
   }
   /**
    * Send error events to backend
+   * Per SDK Developer Guide: POST /api/telemetry/errors with { "errors": [...] }
    */
   async sendErrors(events) {
+    const errors = events.map((e) => ({
+      flag_key: e.flagKey,
+      flag_enabled: e.flagEnabled,
+      error_type: e.errorType,
+      error_message: e.errorMessage,
+      stack_trace: e.stackTrace,
+      context: e.context,
+      timestamp: Math.floor(new Date(e.timestamp).getTime() / 1e3)
+    }));
     const response = await fetch(`${this.baseUrl}/api/telemetry/errors`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
       },
-      body: JSON.stringify({ events })
+      body: JSON.stringify({ errors })
     });
     if (!response.ok) {
       throw new Error(`Failed to send errors: ${response.status}`);
@@ -169,88 +187,144 @@ var TelemetryService = class {
 };
 
 // src/realtime.ts
+import { fetchEventSource } from "@microsoft/fetch-event-source";
+var FatalError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FatalError";
+  }
+};
+var RetriableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RetriableError";
+  }
+};
 var RealtimeService = class {
+  // Track auth failures to prevent reconnection attempts
   constructor(baseUrl, apiKey, onConnectionChange) {
-    this.eventSource = null;
+    this.abortController = null;
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = 10;
-    // Increased from 5 to 10
     this.reconnectDelay = 1e3;
     // Start with 1 second
     this.maxReconnectDelay = 3e4;
     // Cap at 30 seconds
     this.listeners = /* @__PURE__ */ new Map();
+    this.connected = false;
+    this.authFailed = false;
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.onConnectionChange = onConnectionChange;
   }
   /**
-   * Connect to SSE stream
+   * Connect to SSE stream using header-based authentication
+   * Per SDK Developer Guide: "Never pass API keys as query parameters"
    */
   connect() {
-    if (this.eventSource) {
+    if (this.abortController) {
       return;
     }
-    const url = `${this.baseUrl}/api/flags/stream?apiKey=${encodeURIComponent(this.apiKey)}`;
-    try {
-      this.eventSource = new EventSource(url);
-      this.eventSource.onopen = () => {
-        console.log("[Savvagent] Real-time connection established");
-        this.reconnectAttempts = 0;
-        this.reconnectDelay = 1e3;
-        this.onConnectionChange?.call(null, true);
-      };
-      this.eventSource.onerror = (error) => {
-        console.error("[Savvagent] SSE connection error:", error);
-        this.handleDisconnect();
-      };
-      this.eventSource.addEventListener("heartbeat", () => {
-      });
-      this.eventSource.addEventListener("flag.updated", (e) => {
-        this.handleMessage("flag.updated", e);
-      });
-      this.eventSource.addEventListener("flag.deleted", (e) => {
-        this.handleMessage("flag.deleted", e);
-      });
-      this.eventSource.addEventListener("flag.created", (e) => {
-        this.handleMessage("flag.created", e);
-      });
-    } catch (error) {
-      console.error("[Savvagent] Failed to create EventSource:", error);
-      this.handleDisconnect();
+    if (this.authFailed) {
+      return;
     }
+    this.abortController = new AbortController();
+    const url = `${this.baseUrl}/api/flags/stream`;
+    fetchEventSource(url, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      signal: this.abortController.signal,
+      // Disable built-in retry behavior - we handle it ourselves
+      openWhenHidden: false,
+      onopen: async (response) => {
+        if (response.ok) {
+          console.log("[Savvagent] Real-time connection established");
+          this.reconnectAttempts = 0;
+          this.reconnectDelay = 1e3;
+          this.connected = true;
+          this.onConnectionChange?.(true);
+        } else if (response.status === 401 || response.status === 403) {
+          this.authFailed = true;
+          console.error(`[Savvagent] SSE authentication failed (${response.status}). Check your API key. Reconnection disabled.`);
+          throw new FatalError(`SSE authentication failed: ${response.status}`);
+        } else {
+          console.error(`[Savvagent] SSE connection failed: ${response.status}`);
+          throw new RetriableError(`SSE connection failed: ${response.status}`);
+        }
+      },
+      onmessage: (event) => {
+        this.handleMessage(event);
+      },
+      onerror: (err) => {
+        if (this.authFailed) {
+          throw err;
+        }
+        console.error("[Savvagent] SSE connection error:", err);
+        this.handleDisconnect();
+      },
+      onclose: () => {
+        console.log("[Savvagent] SSE connection closed");
+        if (!this.authFailed) {
+          this.handleDisconnect();
+        }
+      }
+    }).catch((error) => {
+      if (error.name !== "AbortError" && !(error instanceof FatalError)) {
+        console.error("[Savvagent] SSE connection error:", error);
+        if (!this.authFailed) {
+          this.handleDisconnect();
+        }
+      }
+    });
   }
   /**
    * Handle incoming SSE messages
    */
-  handleMessage(type, event) {
+  handleMessage(event) {
+    if (event.event === "heartbeat") {
+      return;
+    }
+    if (event.event === "connected") {
+      return;
+    }
+    const eventType = event.event;
+    if (!["flag.updated", "flag.deleted", "flag.created"].includes(eventType)) {
+      return;
+    }
     try {
       const data = JSON.parse(event.data);
       const updateEvent = {
-        type,
+        type: eventType,
         flagKey: data.key,
         data
       };
-      const flagListeners = this.listeners.get(updateEvent.flagKey);
-      if (flagListeners) {
-        flagListeners.forEach((listener) => listener(updateEvent));
-      }
       const wildcardListeners = this.listeners.get("*");
       if (wildcardListeners) {
         wildcardListeners.forEach((listener) => listener(updateEvent));
       }
+      const flagListeners = this.listeners.get(updateEvent.flagKey);
+      if (flagListeners) {
+        flagListeners.forEach((listener) => listener(updateEvent));
+      }
     } catch (error) {
       console.error("[Savvagent] Failed to parse SSE message:", error);
     }
   }
   /**
-   * Handle disconnection and attempt reconnect
+   * Handle disconnection and attempt reconnect with exponential backoff
    */
   handleDisconnect() {
-    this.onConnectionChange?.call(null, false);
-    if (this.eventSource) {
-      this.eventSource.close();
-      this.eventSource = null;
+    this.connected = false;
+    this.onConnectionChange?.(false);
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    if (this.authFailed) {
+      console.warn("[Savvagent] Authentication failed. Reconnection disabled.");
+      return;
     }
     if (this.reconnectAttempts < this.maxReconnectAttempts) {
       this.reconnectAttempts++;
@@ -288,39 +362,48 @@ var RealtimeService = class {
    * Disconnect from SSE stream
    */
   disconnect() {
-    if (this.eventSource) {
-      this.eventSource.close();
-      this.eventSource = null;
-    }
     this.reconnectAttempts = this.maxReconnectAttempts;
-    this.onConnectionChange?.call(null, false);
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.connected = false;
+    this.onConnectionChange?.(false);
   }
   /**
    * Check if connected
    */
   isConnected() {
-    return this.eventSource !== null && this.eventSource.readyState === EventSource.OPEN;
+    return this.connected;
   }
 };
 
 // src/client.ts
 var FlagClient = class {
+  // Track auth failures to prevent request spam
   constructor(config) {
     this.realtime = null;
     this.anonymousId = null;
     this.userId = null;
     this.detectedLanguage = null;
+    this.overrides = /* @__PURE__ */ new Map();
+    this.overrideListeners = /* @__PURE__ */ new Set();
+    this.authFailed = false;
     this.config = {
       apiKey: config.apiKey,
       applicationId: config.applicationId || "",
       baseUrl: config.baseUrl || "http://localhost:8080",
+      environment: config.environment || "production",
       enableRealtime: config.enableRealtime ?? true,
       cacheTtl: config.cacheTtl || 6e4,
       enableTelemetry: config.enableTelemetry ?? true,
       defaults: config.defaults || {},
       onError: config.onError || ((error) => console.error("[Savvagent]", error)),
       defaultLanguage: config.defaultLanguage || "",
-      disableLanguageDetection: config.disableLanguageDetection ?? false
+      disableLanguageDetection: config.disableLanguageDetection ?? false,
+      retryAttempts: config.retryAttempts ?? 3,
+      retryDelay: config.retryDelay ?? 1e3,
+      retryBackoff: config.retryBackoff ?? "exponential"
     };
     if (!this.config.disableLanguageDetection && typeof navigator !== "undefined") {
       this.detectedLanguage = this.config.defaultLanguage || navigator.language || navigator.userLanguage || null;
@@ -334,7 +417,7 @@ var FlagClient = class {
       this.config.apiKey,
       this.config.enableTelemetry
     );
-    if (this.config.enableRealtime && typeof EventSource !== "undefined") {
+    if (this.config.enableRealtime && typeof fetch !== "undefined") {
       this.realtime = new RealtimeService(
         this.config.baseUrl,
         this.config.apiKey,
@@ -399,6 +482,21 @@ var FlagClient = class {
   getUserId() {
     return this.userId;
   }
+  /**
+   * 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) {
+    this.config.environment = environment;
+    this.cache.clear();
+  }
+  /**
+   * Get the current environment
+   */
+  getEnvironment() {
+    return this.config.environment;
+  }
   /**
    * Get the current anonymous ID
    */
@@ -413,8 +511,7 @@ var FlagClient = class {
     const context = {
       user_id: this.userId || void 0,
       anonymous_id: this.anonymousId || void 0,
-      environment: "production",
-      // TODO: Make configurable
+      environment: this.config.environment,
       ...overrides
     };
     if (!context.application_id && this.config.applicationId) {
@@ -425,6 +522,86 @@ var FlagClient = class {
     }
     return context;
   }
+  /**
+   * Check if an error is retryable (transient failure)
+   * @param error - The error to check
+   * @param status - HTTP status code (if available)
+   */
+  isRetryableError(error, status) {
+    if (status === 401 || status === 403) {
+      return false;
+    }
+    if (status && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+      return false;
+    }
+    if (status && status >= 500) {
+      return true;
+    }
+    if (error.name === "AbortError" || error.name === "TypeError" || error.message.includes("network")) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Calculate delay for retry attempt
+   * @param attempt - Current attempt number (1-based)
+   */
+  getRetryDelay(attempt) {
+    const baseDelay = this.config.retryDelay;
+    if (this.config.retryBackoff === "linear") {
+      return baseDelay * attempt;
+    }
+    const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+    const jitter = Math.random() * 0.3 * exponentialDelay;
+    return exponentialDelay + jitter;
+  }
+  /**
+   * Execute a fetch request with retry logic
+   * @param requestFn - Function that returns a fetch promise
+   * @param operationName - Name of the operation for logging
+   */
+  async fetchWithRetry(requestFn, operationName) {
+    let lastError = null;
+    let lastStatus;
+    for (let attempt = 1; attempt <= this.config.retryAttempts; attempt++) {
+      try {
+        const response = await requestFn();
+        if (response.status === 401 || response.status === 403) {
+          this.authFailed = true;
+          this.realtime?.disconnect();
+          console.error(`[Savvagent] Authentication failed (${response.status}). Check your API key. Further requests disabled.`);
+          throw new Error(`Authentication failed: ${response.status}`);
+        }
+        if (response.ok) {
+          return response;
+        }
+        lastStatus = response.status;
+        lastError = new Error(`${operationName} failed: ${response.status}`);
+        if (!this.isRetryableError(lastError, response.status)) {
+          throw lastError;
+        }
+        if (attempt < this.config.retryAttempts) {
+          const delay = this.getRetryDelay(attempt);
+          console.warn(`[Savvagent] ${operationName} failed (${response.status}), retrying in ${Math.round(delay)}ms (attempt ${attempt}/${this.config.retryAttempts})`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      } catch (error) {
+        lastError = error;
+        if (lastError.message.includes("Authentication failed")) {
+          throw lastError;
+        }
+        if (!this.isRetryableError(lastError, lastStatus)) {
+          throw lastError;
+        }
+        if (attempt < this.config.retryAttempts) {
+          const delay = this.getRetryDelay(attempt);
+          console.warn(`[Savvagent] ${operationName} error: ${lastError.message}, retrying in ${Math.round(delay)}ms (attempt ${attempt}/${this.config.retryAttempts})`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastError || new Error(`${operationName} failed after ${this.config.retryAttempts} attempts`);
+  }
   /**
    * Check if a feature flag is enabled
    * @param flagKey - The flag key to evaluate
@@ -445,6 +622,29 @@ var FlagClient = class {
     const startTime = Date.now();
     const traceId = TelemetryService.generateTraceId();
     try {
+      if (this.overrides.has(flagKey)) {
+        const overrideValue = this.overrides.get(flagKey);
+        return {
+          key: flagKey,
+          value: overrideValue,
+          reason: "default",
+          // Using 'default' to indicate override
+          metadata: {
+            description: "Local override active"
+          }
+        };
+      }
+      if (this.authFailed) {
+        const defaultValue = this.config.defaults[flagKey] ?? false;
+        return {
+          key: flagKey,
+          value: defaultValue,
+          reason: "error",
+          metadata: {
+            description: "Authentication failed - using default value"
+          }
+        };
+      }
       const cachedValue = this.cache.get(flagKey);
       if (cachedValue !== null) {
         return {
@@ -457,17 +657,26 @@ var FlagClient = class {
       const requestBody = {
         context: evaluationContext
       };
-      const response = await fetch(`${this.config.baseUrl}/api/flags/${flagKey}/evaluate`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.apiKey}`
+      const response = await this.fetchWithRetry(
+        () => {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => {
+            controller.abort();
+          }, 1e4);
+          return fetch(`${this.config.baseUrl}/api/flags/${flagKey}/evaluate`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.config.apiKey}`
+            },
+            body: JSON.stringify(requestBody),
+            signal: controller.signal
+          }).finally(() => {
+            clearTimeout(timeoutId);
+          });
         },
-        body: JSON.stringify(requestBody)
-      });
-      if (!response.ok) {
-        throw new Error(`Flag evaluation failed: ${response.status}`);
-      }
+        `Flag evaluation (${flagKey})`
+      );
       const data = await response.json();
       const value = data.enabled || false;
       this.cache.set(flagKey, value, data.key);
@@ -592,6 +801,217 @@ var FlagClient = class {
     this.realtime?.disconnect();
     this.cache.clear();
   }
+  // =====================
+  // Local Override Methods
+  // =====================
+  /**
+   * 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, value) {
+    this.overrides.set(flagKey, value);
+    this.notifyOverrideListeners();
+  }
+  /**
+   * 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) {
+    this.overrides.delete(flagKey);
+    this.notifyOverrideListeners();
+  }
+  /**
+   * Clear all local overrides.
+   */
+  clearAllOverrides() {
+    this.overrides.clear();
+    this.notifyOverrideListeners();
+  }
+  /**
+   * 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) {
+    return this.overrides.has(flagKey);
+  }
+  /**
+   * 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) {
+    return this.overrides.get(flagKey);
+  }
+  /**
+   * Get all current overrides.
+   *
+   * @returns Record of flag keys to override values
+   */
+  getOverrides() {
+    const result = {};
+    this.overrides.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+  /**
+   * Set multiple overrides at once.
+   *
+   * @param overrides - Record of flag keys to override values
+   */
+  setOverrides(overrides) {
+    Object.entries(overrides).forEach(([key, value]) => {
+      this.overrides.set(key, value);
+    });
+    this.notifyOverrideListeners();
+  }
+  /**
+   * 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) {
+    this.overrideListeners.add(callback);
+    return () => {
+      this.overrideListeners.delete(callback);
+    };
+  }
+  /**
+   * Notify all override listeners of a change.
+   */
+  notifyOverrideListeners() {
+    this.overrideListeners.forEach((callback) => {
+      try {
+        callback();
+      } catch (e) {
+        console.error("[Savvagent] Override listener error:", e);
+      }
+    });
+  }
+  /**
+   * 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}`);
+   * });
+   * ```
+   */
+  async getAllFlags(environment = "development") {
+    if (this.authFailed) {
+      return [];
+    }
+    try {
+      const response = await this.fetchWithRetry(
+        () => {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => {
+            controller.abort();
+          }, 1e4);
+          return fetch(
+            `${this.config.baseUrl}/api/sdk/flags?environment=${encodeURIComponent(environment)}`,
+            {
+              method: "GET",
+              headers: {
+                Authorization: `Bearer ${this.config.apiKey}`
+              },
+              signal: controller.signal
+            }
+          ).finally(() => {
+            clearTimeout(timeoutId);
+          });
+        },
+        "Get all flags"
+      );
+      const data = await response.json();
+      data.flags.forEach((flag) => {
+        this.cache.set(flag.key, flag.enabled, flag.key);
+      });
+      return data.flags;
+    } catch (error) {
+      this.config.onError(error);
+      return [];
+    }
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async getEnterpriseFlags(environment = "development") {
+    if (this.authFailed) {
+      return [];
+    }
+    try {
+      const response = await this.fetchWithRetry(
+        () => {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => {
+            controller.abort();
+          }, 1e4);
+          return fetch(
+            `${this.config.baseUrl}/api/sdk/enterprise-flags?environment=${encodeURIComponent(environment)}`,
+            {
+              method: "GET",
+              headers: {
+                Authorization: `Bearer ${this.config.apiKey}`
+              },
+              signal: controller.signal
+            }
+          ).finally(() => {
+            clearTimeout(timeoutId);
+          });
+        },
+        "Get enterprise flags"
+      );
+      const data = await response.json();
+      return data.flags;
+    } catch (error) {
+      this.config.onError(error);
+      return [];
+    }
+  }
 };
 export {
   FlagCache,