@savvagent/sdk 1.0.0 → 1.0.1

package/dist/index.js

@@ -149,15 +149,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}`);
@@ -165,15 +173,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}`);
@@ -198,88 +216,144 @@ var TelemetryService = class {
 };
 
 // src/realtime.ts
+var import_fetch_event_source = require("@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`;
+    (0, import_fetch_event_source.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++;
@@ -317,28 +391,33 @@ 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 || "",
@@ -363,7 +442,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,
@@ -474,6 +553,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 {
@@ -486,15 +588,27 @@ var FlagClient = class {
       const requestBody = {
         context: evaluationContext
       };
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, 1e4);
       const response = await fetch(`${this.config.baseUrl}/api/flags/${flagKey}/evaluate`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           Authorization: `Bearer ${this.config.apiKey}`
         },
-        body: JSON.stringify(requestBody)
+        body: JSON.stringify(requestBody),
+        signal: controller.signal
       });
+      clearTimeout(timeoutId);
       if (!response.ok) {
+        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}`);
+        }
         throw new Error(`Flag evaluation failed: ${response.status}`);
       }
       const data = await response.json();
@@ -621,6 +735,223 @@ 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 controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, 1e4);
+      const response = await fetch(
+        `${this.config.baseUrl}/api/sdk/flags?environment=${encodeURIComponent(environment)}`,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          },
+          signal: controller.signal
+        }
+      );
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        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}`);
+        }
+        throw new Error(`Failed to fetch flags: ${response.status}`);
+      }
+      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 controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, 1e4);
+      const response = await fetch(
+        `${this.config.baseUrl}/api/sdk/enterprise-flags?environment=${encodeURIComponent(environment)}`,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          },
+          signal: controller.signal
+        }
+      );
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        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}`);
+        }
+        throw new Error(`Failed to fetch enterprise flags: ${response.status}`);
+      }
+      const data = await response.json();
+      return data.flags;
+    } catch (error) {
+      this.config.onError(error);
+      return [];
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {