@savvagent/sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,601 @@
+// src/cache.ts
+var FlagCache = class {
+  constructor(ttl = 6e4) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.ttl = ttl;
+  }
+  /**
+   * Get a cached flag value
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a flag value in cache
+   */
+  set(key, value, flagId) {
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttl,
+      flagId
+    });
+  }
+  /**
+   * Invalidate a specific flag
+   */
+  invalidate(key) {
+    this.cache.delete(key);
+  }
+  /**
+   * Clear all cached flags
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Get all cached keys
+   */
+  keys() {
+    return Array.from(this.cache.keys());
+  }
+};
+
+// src/telemetry.ts
+var TelemetryService = class {
+  constructor(baseUrl, apiKey, enabled = true) {
+    this.queue = [];
+    this.flushInterval = 5e3;
+    // 5 seconds
+    this.maxBatchSize = 50;
+    this.timer = null;
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.enabled = enabled;
+    if (this.enabled) {
+      this.startBatchSender();
+    }
+  }
+  /**
+   * Track a flag evaluation
+   */
+  trackEvaluation(event) {
+    if (!this.enabled) return;
+    this.queue.push(event);
+    if (this.queue.length >= this.maxBatchSize) {
+      this.flush();
+    }
+  }
+  /**
+   * Track an error in flagged code
+   */
+  trackError(event) {
+    if (!this.enabled) return;
+    this.queue.push(event);
+    this.flush();
+  }
+  /**
+   * Start the batch sender interval
+   */
+  startBatchSender() {
+    this.timer = setInterval(() => {
+      if (this.queue.length > 0) {
+        this.flush();
+      }
+    }, this.flushInterval);
+    if (typeof window !== "undefined") {
+      window.addEventListener("beforeunload", () => {
+        this.flush();
+      });
+    }
+  }
+  /**
+   * Flush the telemetry queue
+   */
+  async flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.maxBatchSize);
+    try {
+      const evaluations = batch.filter((e) => "durationMs" in e);
+      const errors = batch.filter((e) => "errorType" in e);
+      if (evaluations.length > 0) {
+        await this.sendEvaluations(evaluations);
+      }
+      if (errors.length > 0) {
+        await this.sendErrors(errors);
+      }
+    } catch (error) {
+      if (this.queue.length < 1e3) {
+        this.queue.unshift(...batch);
+      }
+      console.error("[Savvagent] Failed to send telemetry:", error);
+    }
+  }
+  /**
+   * Send evaluation events to backend
+   */
+  async sendEvaluations(events) {
+    const response = await fetch(`${this.baseUrl}/api/telemetry/evaluations`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ events })
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to send evaluations: ${response.status}`);
+    }
+  }
+  /**
+   * Send error events to backend
+   */
+  async sendErrors(events) {
+    const response = await fetch(`${this.baseUrl}/api/telemetry/errors`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ events })
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to send errors: ${response.status}`);
+    }
+  }
+  /**
+   * Stop the telemetry service
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.flush();
+  }
+  /**
+   * Generate a trace ID for distributed tracing
+   */
+  static generateTraceId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+};
+
+// src/realtime.ts
+var RealtimeService = class {
+  constructor(baseUrl, apiKey, onConnectionChange) {
+    this.eventSource = 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.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.onConnectionChange = onConnectionChange;
+  }
+  /**
+   * Connect to SSE stream
+   */
+  connect() {
+    if (this.eventSource) {
+      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();
+    }
+  }
+  /**
+   * Handle incoming SSE messages
+   */
+  handleMessage(type, event) {
+    try {
+      const data = JSON.parse(event.data);
+      const updateEvent = {
+        type,
+        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));
+      }
+    } catch (error) {
+      console.error("[Savvagent] Failed to parse SSE message:", error);
+    }
+  }
+  /**
+   * Handle disconnection and attempt reconnect
+   */
+  handleDisconnect() {
+    this.onConnectionChange?.call(null, false);
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++;
+      const exponentialDelay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+      const delay = Math.min(exponentialDelay, this.maxReconnectDelay);
+      console.log(`[Savvagent] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+      setTimeout(() => {
+        this.connect();
+      }, delay);
+    } else {
+      console.warn("[Savvagent] Max reconnection attempts reached. Connection will not be retried automatically.");
+    }
+  }
+  /**
+   * Subscribe to flag updates
+   * @param flagKey - Specific flag key or '*' for all flags
+   * @param listener - Callback function
+   */
+  subscribe(flagKey, listener) {
+    if (!this.listeners.has(flagKey)) {
+      this.listeners.set(flagKey, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(flagKey).add(listener);
+    return () => {
+      const listeners = this.listeners.get(flagKey);
+      if (listeners) {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          this.listeners.delete(flagKey);
+        }
+      }
+    };
+  }
+  /**
+   * Disconnect from SSE stream
+   */
+  disconnect() {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.reconnectAttempts = this.maxReconnectAttempts;
+    this.onConnectionChange?.call(null, false);
+  }
+  /**
+   * Check if connected
+   */
+  isConnected() {
+    return this.eventSource !== null && this.eventSource.readyState === EventSource.OPEN;
+  }
+};
+
+// src/client.ts
+var FlagClient = class {
+  constructor(config) {
+    this.realtime = null;
+    this.anonymousId = null;
+    this.userId = null;
+    this.detectedLanguage = null;
+    this.config = {
+      apiKey: config.apiKey,
+      applicationId: config.applicationId || "",
+      baseUrl: config.baseUrl || "http://localhost:8080",
+      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
+    };
+    if (!this.config.disableLanguageDetection && typeof navigator !== "undefined") {
+      this.detectedLanguage = this.config.defaultLanguage || navigator.language || navigator.userLanguage || null;
+    }
+    if (!this.config.apiKey || !this.config.apiKey.startsWith("sdk_")) {
+      throw new Error('Invalid API key. SDK keys must start with "sdk_"');
+    }
+    this.cache = new FlagCache(this.config.cacheTtl);
+    this.telemetry = new TelemetryService(
+      this.config.baseUrl,
+      this.config.apiKey,
+      this.config.enableTelemetry
+    );
+    if (this.config.enableRealtime && typeof EventSource !== "undefined") {
+      this.realtime = new RealtimeService(
+        this.config.baseUrl,
+        this.config.apiKey,
+        (connected) => {
+          console.log(`[Savvagent] Real-time connection: ${connected ? "connected" : "disconnected"}`);
+        }
+      );
+      this.realtime.subscribe("*", (event) => {
+        console.log(`[Savvagent] Flag ${event.type}: ${event.flagKey}`);
+        this.cache.invalidate(event.flagKey);
+      });
+      this.realtime.connect();
+    }
+    this.anonymousId = this.getOrCreateAnonymousId();
+  }
+  /**
+   * Get or create an anonymous ID for consistent flag evaluation
+   * @returns Anonymous ID from localStorage or newly generated
+   */
+  getOrCreateAnonymousId() {
+    if (typeof window === "undefined" || typeof localStorage === "undefined") {
+      return `session_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    }
+    const storageKey = "savvagent_anonymous_id";
+    let anonId = localStorage.getItem(storageKey);
+    if (!anonId) {
+      anonId = `anon_${crypto.randomUUID()}`;
+      try {
+        localStorage.setItem(storageKey, anonId);
+      } catch (e) {
+        console.warn("[Savvagent] Could not save anonymous ID to localStorage:", e);
+      }
+    }
+    return anonId;
+  }
+  /**
+   * Set a custom anonymous ID
+   * Useful for cross-device tracking or custom identifier schemes
+   * @param id - The anonymous ID to use
+   */
+  setAnonymousId(id) {
+    this.anonymousId = id;
+    if (typeof localStorage !== "undefined") {
+      try {
+        localStorage.setItem("savvagent_anonymous_id", id);
+      } catch (e) {
+        console.warn("[Savvagent] Could not save anonymous ID to localStorage:", e);
+      }
+    }
+  }
+  /**
+   * 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) {
+    this.userId = userId;
+  }
+  /**
+   * Get the current user ID
+   */
+  getUserId() {
+    return this.userId;
+  }
+  /**
+   * Get the current anonymous ID
+   */
+  getAnonymousId() {
+    return this.anonymousId || this.getOrCreateAnonymousId();
+  }
+  /**
+   * Build the context for flag evaluation
+   * @param overrides - Context overrides
+   */
+  buildContext(overrides) {
+    const context = {
+      user_id: this.userId || void 0,
+      anonymous_id: this.anonymousId || void 0,
+      environment: "production",
+      // TODO: Make configurable
+      ...overrides
+    };
+    if (!context.application_id && this.config.applicationId) {
+      context.application_id = this.config.applicationId;
+    }
+    if (!context.language && this.detectedLanguage) {
+      context.language = this.detectedLanguage;
+    }
+    return context;
+  }
+  /**
+   * Check if a feature flag is enabled
+   * @param flagKey - The flag key to evaluate
+   * @param context - Optional context for targeting
+   * @returns Promise<boolean>
+   */
+  async isEnabled(flagKey, context) {
+    const result = await this.evaluate(flagKey, context);
+    return result.value;
+  }
+  /**
+   * Evaluate a feature flag and return detailed result
+   * @param flagKey - The flag key to evaluate
+   * @param context - Optional context for targeting
+   * @returns Promise<FlagEvaluationResult>
+   */
+  async evaluate(flagKey, context) {
+    const startTime = Date.now();
+    const traceId = TelemetryService.generateTraceId();
+    try {
+      const cachedValue = this.cache.get(flagKey);
+      if (cachedValue !== null) {
+        return {
+          key: flagKey,
+          value: cachedValue,
+          reason: "cached"
+        };
+      }
+      const evaluationContext = this.buildContext(context);
+      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}`
+        },
+        body: JSON.stringify(requestBody)
+      });
+      if (!response.ok) {
+        throw new Error(`Flag evaluation failed: ${response.status}`);
+      }
+      const data = await response.json();
+      const value = data.enabled || false;
+      this.cache.set(flagKey, value, data.key);
+      const durationMs = Date.now() - startTime;
+      this.telemetry.trackEvaluation({
+        flagKey,
+        result: value,
+        context: evaluationContext,
+        durationMs,
+        traceId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return {
+        key: flagKey,
+        value,
+        reason: "evaluated",
+        metadata: {
+          scope: data.scope,
+          configuration: data.configuration,
+          variation: data.variation,
+          timestamp: data.timestamp
+        }
+      };
+    } catch (error) {
+      const defaultValue = this.config.defaults[flagKey] ?? false;
+      this.config.onError(error);
+      return {
+        key: flagKey,
+        value: defaultValue,
+        reason: "error"
+      };
+    }
+  }
+  /**
+   * 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
+   */
+  async withFlag(flagKey, callback, context) {
+    const enabled = await this.isEnabled(flagKey, context);
+    if (!enabled) {
+      return null;
+    }
+    const evaluationContext = this.buildContext(context);
+    const traceId = TelemetryService.generateTraceId();
+    try {
+      return await callback();
+    } catch (error) {
+      this.telemetry.trackError({
+        flagKey,
+        flagEnabled: true,
+        errorType: error.name || "Error",
+        errorMessage: error.message || "Unknown error",
+        stackTrace: error.stack,
+        context: evaluationContext,
+        traceId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      throw error;
+    }
+  }
+  /**
+   * 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, error, context) {
+    const evaluationContext = this.buildContext(context);
+    this.telemetry.trackError({
+      flagKey,
+      flagEnabled: true,
+      // Assume enabled if tracking manually
+      errorType: error.name || "Error",
+      errorMessage: error.message || "Unknown error",
+      stackTrace: error.stack,
+      context: evaluationContext,
+      traceId: TelemetryService.generateTraceId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /**
+   * 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, callback) {
+    if (!this.realtime) {
+      console.warn("[Savvagent] Real-time updates are disabled");
+      return () => {
+      };
+    }
+    return this.realtime.subscribe(flagKey, () => {
+      callback();
+    });
+  }
+  /**
+   * Get all cached flag keys
+   */
+  getCachedFlags() {
+    return this.cache.keys();
+  }
+  /**
+   * Clear the flag cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Check if real-time connection is active
+   */
+  isRealtimeConnected() {
+    return this.realtime?.isConnected() || false;
+  }
+  /**
+   * Close the client and cleanup resources
+   */
+  close() {
+    this.telemetry.stop();
+    this.realtime?.disconnect();
+    this.cache.clear();
+  }
+};
+export {
+  FlagCache,
+  FlagClient,
+  RealtimeService,
+  TelemetryService
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@savvagent/sdk",
+  "version": "1.0.0",
+  "description": "Savvagent TypeScript/JavaScript SDK for feature flags with AI-powered error detection",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "savvagent",
+    "ai",
+    "error-detection",
+    "typescript"
+  ],
+  "author": "Rob Hicks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/savvagent/savvagent-sdks",
+    "directory": "packages/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/savvagent/savvagent-sdks/issues"
+  },
+  "homepage": "https://github.com/savvagent/savvagent-sdks/tree/main/packages/typescript#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {},
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=16"
+  }
+}