@smplkit/sdk 1.3.26 → 1.3.27

package/dist/index.d.cts

@@ -1,6 +1,43 @@
+/**
+ * Internal SDK telemetry engine.
+ *
+ * Accumulates usage metrics in memory and periodically flushes them to the
+ * app service via `POST /api/v1/metrics/bulk`.  This module is entirely
+ * private — nothing here is exported or documented for customers.
+ *
+ * @internal
+ */
+/** @internal */
+declare class MetricsReporter {
+    private readonly _apiKey;
+    private readonly _environment;
+    private readonly _service;
+    private readonly _flushInterval;
+    private _counters;
+    private _gauges;
+    private _timer;
+    private _closed;
+    constructor(options: {
+        apiKey: string;
+        environment: string;
+        service: string;
+        flushInterval?: number;
+    });
+    record(name: string, value?: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    recordGauge(name: string, value: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    flush(): void;
+    close(): void;
+    private _mergeDimensions;
+    private _maybeStartTimer;
+    private _flush;
+    private _buildPayload;
+    private _entry;
+}
+
 /**
  * Shared WebSocket connection for real-time event delivery.
  */
+
 type EventCallback = (data: Record<string, any>) => void;
 /**
  * Manages a WebSocket connection for real-time event delivery.
@@ -8,13 +45,14 @@ type EventCallback = (data: Record<string, any>) => void;
 declare class SharedWebSocket {
     private readonly _appBaseUrl;
     private readonly _apiKey;
+    private readonly _metrics;
     private _listeners;
     private _connectionStatus;
     private _closed;
     private _ws;
     private _reconnectTimer;
     private _backoffIndex;
-    constructor(appBaseUrl: string, apiKey: string);
+    constructor(appBaseUrl: string, apiKey: string, metrics?: MetricsReporter | null);
     /** Register a listener for a specific event type. */
     on(eventName: string, callback: EventCallback): void;
     /** Unregister a listener for a specific event type. */
@@ -159,6 +197,7 @@ declare class ConfigClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private _configCache;
     private _initialized;
@@ -649,6 +688,7 @@ declare class FlagsClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
@@ -962,6 +1002,7 @@ declare class LoggingClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private readonly _ensureWs;
     private _wsManager;
@@ -1064,6 +1105,12 @@ interface SmplClientOptions {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Disable SDK telemetry reporting.
+     * When `true`, no usage metrics are collected or sent.
+     * @default false
+     */
+    disableTelemetry?: boolean;
 }
 /**
  * Entry point for the smplkit TypeScript SDK.
@@ -1100,6 +1147,8 @@ declare class SmplClient {
     readonly _environment: string;
     /** @internal */
     readonly _service: string;
+    /** @internal */
+    readonly _metrics: MetricsReporter | null;
     private readonly _timeout;
     private readonly _appHttp;
     constructor(options?: SmplClientOptions);

package/dist/index.d.ts

@@ -1,6 +1,43 @@
+/**
+ * Internal SDK telemetry engine.
+ *
+ * Accumulates usage metrics in memory and periodically flushes them to the
+ * app service via `POST /api/v1/metrics/bulk`.  This module is entirely
+ * private — nothing here is exported or documented for customers.
+ *
+ * @internal
+ */
+/** @internal */
+declare class MetricsReporter {
+    private readonly _apiKey;
+    private readonly _environment;
+    private readonly _service;
+    private readonly _flushInterval;
+    private _counters;
+    private _gauges;
+    private _timer;
+    private _closed;
+    constructor(options: {
+        apiKey: string;
+        environment: string;
+        service: string;
+        flushInterval?: number;
+    });
+    record(name: string, value?: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    recordGauge(name: string, value: number, unit?: string | null, dimensions?: Record<string, string>): void;
+    flush(): void;
+    close(): void;
+    private _mergeDimensions;
+    private _maybeStartTimer;
+    private _flush;
+    private _buildPayload;
+    private _entry;
+}
+
 /**
  * Shared WebSocket connection for real-time event delivery.
  */
+
 type EventCallback = (data: Record<string, any>) => void;
 /**
  * Manages a WebSocket connection for real-time event delivery.
@@ -8,13 +45,14 @@ type EventCallback = (data: Record<string, any>) => void;
 declare class SharedWebSocket {
     private readonly _appBaseUrl;
     private readonly _apiKey;
+    private readonly _metrics;
     private _listeners;
     private _connectionStatus;
     private _closed;
     private _ws;
     private _reconnectTimer;
     private _backoffIndex;
-    constructor(appBaseUrl: string, apiKey: string);
+    constructor(appBaseUrl: string, apiKey: string, metrics?: MetricsReporter | null);
     /** Register a listener for a specific event type. */
     on(eventName: string, callback: EventCallback): void;
     /** Unregister a listener for a specific event type. */
@@ -159,6 +197,7 @@ declare class ConfigClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private _configCache;
     private _initialized;
@@ -649,6 +688,7 @@ declare class FlagsClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     /** @internal */
     constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number);
@@ -962,6 +1002,7 @@ declare class LoggingClient {
     _parent: {
         readonly _environment: string;
         readonly _service: string | null;
+        readonly _metrics: MetricsReporter | null;
     } | null;
     private readonly _ensureWs;
     private _wsManager;
@@ -1064,6 +1105,12 @@ interface SmplClientOptions {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Disable SDK telemetry reporting.
+     * When `true`, no usage metrics are collected or sent.
+     * @default false
+     */
+    disableTelemetry?: boolean;
 }
 /**
  * Entry point for the smplkit TypeScript SDK.
@@ -1100,6 +1147,8 @@ declare class SmplClient {
     readonly _environment: string;
     /** @internal */
     readonly _service: string;
+    /** @internal */
+    readonly _metrics: MetricsReporter | null;
     private readonly _timeout;
     private readonly _appHttp;
     constructor(options?: SmplClientOptions);

package/dist/index.js

@@ -17182,6 +17182,10 @@ var ConfigClient = class {
     if (values === void 0) {
       throw new SmplNotFoundError(`Config with key '${key}' not found in cache`);
     }
+    const metrics = this._parent?._metrics;
+    if (metrics) {
+      metrics.record("config.resolutions", 1, "resolutions", { config_id: key });
+    }
     if (model) {
       return new model(values);
     }
@@ -17316,6 +17320,10 @@ var ConfigClient = class {
         const oldVal = iKey in oldItems ? oldItems[iKey] : null;
         const newVal = iKey in newItems ? newItems[iKey] : null;
         if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+          const metrics = this._parent?._metrics;
+          if (metrics) {
+            metrics.record("config.changes", 1, "changes", { config_id: cfgKey });
+          }
           const event = {
             configKey: cfgKey,
             itemKey: iKey,
@@ -18151,8 +18159,18 @@ var FlagsClient = class {
     const cacheKey = `${key}:${ctxHash}`;
     const [hit, cachedValue] = this._cache.get(cacheKey);
     if (hit) {
+      const metrics2 = this._parent?._metrics;
+      if (metrics2) {
+        metrics2.record("flags.cache_hits", 1, "hits");
+        metrics2.record("flags.evaluations", 1, "evaluations", { flag_id: key });
+      }
       return cachedValue;
     }
+    const metrics = this._parent?._metrics;
+    if (metrics) {
+      metrics.record("flags.cache_misses", 1, "misses");
+      metrics.record("flags.evaluations", 1, "evaluations", { flag_id: key });
+    }
     const flagDef = this._flagStore[key];
     if (flagDef === void 0) {
       this._cache.put(cacheKey, defaultValue);
@@ -18796,6 +18814,12 @@ var LoggingClient = class {
       } catch {
       }
     }
+    if (discovered.length > 0) {
+      const metrics = this._parent?._metrics;
+      if (metrics) {
+        metrics.record("logging.loggers_discovered", discovered.length, "loggers");
+      }
+    }
     for (const { name, level } of discovered) {
       try {
         const logger = this.new(name, { managed: true });
@@ -18890,6 +18914,10 @@ var LoggingClient = class {
           effectiveLevel = envOverride.level;
         }
       }
+      const metrics = this._parent?._metrics;
+      if (metrics) {
+        metrics.record("logging.level_changes", 1, "changes", { logger_id: logger.key });
+      }
       for (const adapter of this._adapters) {
         try {
           adapter.applyLevel(logger.key, effectiveLevel);
@@ -18973,15 +19001,17 @@ var BACKOFF_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 32e3, 6e4];
 var SharedWebSocket = class {
   _appBaseUrl;
   _apiKey;
+  _metrics;
   _listeners = /* @__PURE__ */ new Map();
   _connectionStatus = "disconnected";
   _closed = false;
   _ws = null;
   _reconnectTimer = null;
   _backoffIndex = 0;
-  constructor(appBaseUrl, apiKey) {
+  constructor(appBaseUrl, apiKey, metrics) {
     this._appBaseUrl = appBaseUrl;
     this._apiKey = apiKey;
+    this._metrics = metrics ?? null;
   }
   // ------------------------------------------------------------------
   // Listener registration
@@ -19080,6 +19110,9 @@ var SharedWebSocket = class {
           if (msg.type === "connected") {
             this._backoffIndex = 0;
             this._connectionStatus = "connected";
+            if (this._metrics) {
+              this._metrics.recordGauge("platform.websocket_connections", 1, "connections");
+            }
             return;
           }
           if (msg.type === "error") {
@@ -19093,6 +19126,9 @@ var SharedWebSocket = class {
         }
       });
       ws.on("close", () => {
+        if (this._metrics) {
+          this._metrics.recordGauge("platform.websocket_connections", 0, "connections");
+        }
         if (!this._closed) {
           this._connectionStatus = "disconnected";
           this._scheduleReconnect();
@@ -19173,8 +19209,145 @@ function resolveApiKey(explicit, environment) {
   throw new SmplError(noApiKeyMessage(environment));
 }
 
-// src/client.ts
+// src/_metrics.ts
 var APP_BASE_URL2 = "https://app.smplkit.com";
+function makeCounter(unit) {
+  return { value: 0, unit, windowStart: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function makeMapKey(name, dimensions) {
+  const sorted = Object.keys(dimensions).sort().map((k) => `${k}=${dimensions[k]}`).join("&");
+  return `${name}|${sorted}`;
+}
+var MetricsReporter = class {
+  _apiKey;
+  _environment;
+  _service;
+  _flushInterval;
+  _counters = /* @__PURE__ */ new Map();
+  _gauges = /* @__PURE__ */ new Map();
+  _timer = null;
+  _closed = false;
+  constructor(options) {
+    this._apiKey = options.apiKey;
+    this._environment = options.environment;
+    this._service = options.service;
+    this._flushInterval = options.flushInterval ?? 60;
+  }
+  // ------------------------------------------------------------------
+  // Public recording API
+  // ------------------------------------------------------------------
+  record(name, value = 1, unit = null, dimensions) {
+    const merged = this._mergeDimensions(dimensions);
+    const key = makeMapKey(name, merged);
+    let entry = this._counters.get(key);
+    if (!entry) {
+      entry = { name, dimensions: merged, counter: makeCounter(unit) };
+      this._counters.set(key, entry);
+    }
+    entry.counter.value += value;
+    if (entry.counter.unit === null && unit !== null) {
+      entry.counter.unit = unit;
+    }
+    this._maybeStartTimer();
+  }
+  recordGauge(name, value, unit = null, dimensions) {
+    const merged = this._mergeDimensions(dimensions);
+    const key = makeMapKey(name, merged);
+    let entry = this._gauges.get(key);
+    if (!entry) {
+      entry = { name, dimensions: merged, counter: makeCounter(unit) };
+      this._gauges.set(key, entry);
+    }
+    entry.counter.value = value;
+    if (entry.counter.unit === null && unit !== null) {
+      entry.counter.unit = unit;
+    }
+    this._maybeStartTimer();
+  }
+  // ------------------------------------------------------------------
+  // Flush / close
+  // ------------------------------------------------------------------
+  flush() {
+    this._flush();
+  }
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._timer !== null) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+    this._flush();
+  }
+  // ------------------------------------------------------------------
+  // Internal
+  // ------------------------------------------------------------------
+  _mergeDimensions(dimensions) {
+    const merged = {
+      environment: this._environment,
+      service: this._service
+    };
+    if (dimensions) {
+      Object.assign(merged, dimensions);
+    }
+    return merged;
+  }
+  _maybeStartTimer() {
+    if (this._timer === null && !this._closed) {
+      this._timer = setInterval(() => this._flush(), this._flushInterval * 1e3);
+      if (typeof this._timer === "object" && "unref" in this._timer) {
+        this._timer.unref();
+      }
+    }
+  }
+  _flush() {
+    const counters = this._counters;
+    const gauges = this._gauges;
+    this._counters = /* @__PURE__ */ new Map();
+    this._gauges = /* @__PURE__ */ new Map();
+    if (counters.size === 0 && gauges.size === 0) return;
+    const payload = this._buildPayload(counters, gauges);
+    try {
+      fetch(`${APP_BASE_URL2}/api/v1/metrics/bulk`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this._apiKey}`,
+          "Content-Type": "application/vnd.api+json",
+          Accept: "application/json"
+        },
+        body: JSON.stringify(payload)
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  _buildPayload(counters, gauges) {
+    const data = [];
+    for (const [, entry] of counters) {
+      data.push(this._entry(entry.name, entry.counter, entry.dimensions));
+    }
+    for (const [, entry] of gauges) {
+      data.push(this._entry(entry.name, entry.counter, entry.dimensions));
+    }
+    return { data };
+  }
+  _entry(name, counter, dimensions) {
+    return {
+      type: "metric",
+      attributes: {
+        name,
+        value: counter.value,
+        unit: counter.unit,
+        period_seconds: this._flushInterval,
+        dimensions,
+        recorded_at: counter.windowStart
+      }
+    };
+  }
+};
+
+// src/client.ts
+var APP_BASE_URL3 = "https://app.smplkit.com";
 var NO_ENVIRONMENT_MESSAGE = "No environment provided. Set one of:\n  1. Pass environment to the constructor\n  2. Set the SMPLKIT_ENVIRONMENT environment variable";
 var NO_SERVICE_MESSAGE = "No service provided. Set one of:\n  1. Pass service in options\n  2. Set the SMPLKIT_SERVICE environment variable";
 var SmplClient = class {
@@ -19190,6 +19363,8 @@ var SmplClient = class {
   _environment;
   /** @internal */
   _service;
+  /** @internal */
+  _metrics = null;
   _timeout;
   _appHttp;
   constructor(options = {}) {
@@ -19207,12 +19382,19 @@ var SmplClient = class {
     this._apiKey = apiKey;
     this._timeout = options.timeout ?? 3e4;
     this._appHttp = createClient4({
-      baseUrl: APP_BASE_URL2,
+      baseUrl: APP_BASE_URL3,
       headers: {
         Authorization: `Bearer ${apiKey}`,
         Accept: "application/json"
       }
     });
+    if (!options.disableTelemetry) {
+      this._metrics = new MetricsReporter({
+        apiKey,
+        environment: this._environment,
+        service: this._service
+      });
+    }
     this.config = new ConfigClient(apiKey, this._timeout);
     this.flags = new FlagsClient(apiKey, () => this._ensureWs(), this._timeout);
     this.logging = new LoggingClient(apiKey, () => this._ensureWs(), this._timeout);
@@ -19242,13 +19424,16 @@ var SmplClient = class {
   /** Lazily create and start the shared WebSocket. @internal */
   _ensureWs() {
     if (this._wsManager === null) {
-      this._wsManager = new SharedWebSocket(APP_BASE_URL2, this._apiKey);
+      this._wsManager = new SharedWebSocket(APP_BASE_URL3, this._apiKey, this._metrics);
       this._wsManager.start();
     }
     return this._wsManager;
   }
   /** Close the shared WebSocket and release resources. */
   close() {
+    if (this._metrics !== null) {
+      this._metrics.close();
+    }
     this.logging._close();
     if (this._wsManager !== null) {
       this._wsManager.stop();