@canarygate/sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,360 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  CanaryGate: () => CanaryGate
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/hash.ts
+function hashString(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) + hash ^ input.charCodeAt(i);
+    hash = hash >>> 0;
+  }
+  return hash % 100;
+}
+
+// src/sse.ts
+function parseSseEventBlock(block) {
+  let event = "message";
+  const dataLines = [];
+  let retryMs;
+  for (const line of block.split(/\r?\n/)) {
+    if (!line || line.startsWith(":")) continue;
+    const separatorIndex = line.indexOf(":");
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    const value = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1).trimStart();
+    if (field === "event") {
+      event = value || "message";
+      continue;
+    }
+    if (field === "data") {
+      dataLines.push(value);
+      continue;
+    }
+    if (field === "retry") {
+      const parsedRetryMs = Number.parseInt(value, 10);
+      if (Number.isFinite(parsedRetryMs) && parsedRetryMs > 0) {
+        retryMs = parsedRetryMs;
+      }
+    }
+  }
+  if (dataLines.length === 0 && retryMs === void 0) {
+    return null;
+  }
+  return { event, data: dataLines.join("\n"), retryMs };
+}
+
+// src/canary-gate-base.ts
+var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
+var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+}
+function parseTimestamp(value) {
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+var CanaryGateBase = class {
+  constructor(apiKey, options = {}, streamEnabled, anonIdFactory) {
+    this.apiKey = apiKey;
+    this.streamEnabled = streamEnabled;
+    this.anonIdFactory = anonIdFactory;
+    this.cache = /* @__PURE__ */ new Map();
+    this.cacheVersions = /* @__PURE__ */ new Map();
+    this.streamAbortController = null;
+    this.reconnectTimeout = null;
+    this.heartbeatTimeout = null;
+    this.reconnectAttempts = 0;
+    this.stale = false;
+    this.lastSyncAt = null;
+    this.destroyed = false;
+    this.baseUrl = (options.baseUrl ?? "http://localhost:3001").replace(
+      /\/$/,
+      ""
+    );
+    this.environment = options.environment;
+    this.reconnectDelay = options.reconnectDelay ?? 5e3;
+    this.maxReconnectDelay = Math.max(
+      options.maxReconnectDelay ?? DEFAULT_MAX_RECONNECT_DELAY_MS,
+      this.reconnectDelay
+    );
+    this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    this.streamRetryDelay = this.reconnectDelay;
+    this.anonId = anonIdFactory();
+  }
+  warnStreamDisabled() {
+    console.warn(
+      "[canarygate] Real-time streams (SSE) are disabled in browser environments to protect network architecture."
+    );
+  }
+  async init() {
+    await this.fetchFlags();
+    if (this.streamEnabled) this.connectStream();
+  }
+  replaceCacheFromSnapshot(flags, requestedAt) {
+    const nextCache = /* @__PURE__ */ new Map();
+    const nextVersions = /* @__PURE__ */ new Map();
+    for (const flag of flags) {
+      const nextVersion = parseTimestamp(flag.updatedAt);
+      const currentVersion = this.cacheVersions.get(flag.key) ?? -1;
+      if (currentVersion > nextVersion && currentVersion > requestedAt) {
+        const currentFlag = this.cache.get(flag.key);
+        if (currentFlag) nextCache.set(flag.key, currentFlag);
+        nextVersions.set(flag.key, currentVersion);
+        continue;
+      }
+      nextCache.set(flag.key, flag);
+      nextVersions.set(flag.key, nextVersion);
+    }
+    for (const [key, currentVersion] of this.cacheVersions) {
+      if (nextVersions.has(key) || currentVersion <= requestedAt) {
+        continue;
+      }
+      const currentFlag = this.cache.get(key);
+      if (currentFlag) nextCache.set(key, currentFlag);
+      nextVersions.set(key, currentVersion);
+    }
+    this.cache = nextCache;
+    this.cacheVersions = nextVersions;
+    this.stale = false;
+    this.lastSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  async fetchFlags() {
+    const requestedAt = Date.now();
+    try {
+      const headers = { "X-Api-Key": this.apiKey };
+      if (this.environment) headers["X-Environment"] = this.environment;
+      const res = await fetch(`${this.baseUrl}/sdk/flags`, { headers });
+      if (!res.ok) {
+        console.error(
+          `[canarygate] Failed to fetch flags: ${res.status} ${res.statusText}`
+        );
+        this.stale = true;
+        return false;
+      }
+      const body = await res.json();
+      this.replaceCacheFromSnapshot(body.flags, requestedAt);
+      return true;
+    } catch (err) {
+      console.error("[canarygate] Error fetching flags:", err);
+      this.stale = true;
+      return false;
+    }
+  }
+  applyFlagUpdate(raw) {
+    const nextVersion = parseTimestamp(raw.updatedAt);
+    const currentVersion = this.cacheVersions.get(raw.key) ?? -1;
+    if (nextVersion < currentVersion) return;
+    this.cacheVersions.set(raw.key, nextVersion);
+    this.cache.set(raw.key, raw);
+  }
+  applyFlagDeletion(payload) {
+    const nextVersion = parseTimestamp(payload.deletedAt);
+    const currentVersion = this.cacheVersions.get(payload.key) ?? -1;
+    if (nextVersion < currentVersion) return;
+    this.cacheVersions.set(payload.key, nextVersion);
+    this.cache.delete(payload.key);
+  }
+  handleStreamMessage(event, data) {
+    if (event === "connected" || event === "connection-closing") return;
+    if (!data) return;
+    try {
+      if (event === "flag-deleted") {
+        const payload = JSON.parse(data);
+        this.applyFlagDeletion(payload);
+        return;
+      }
+      if (event === "flag-updated" || event === "flag-created") {
+        this.applyFlagUpdate(JSON.parse(data));
+      }
+    } catch (err) {
+      console.error(`[canarygate] Failed to parse ${event} event:`, err);
+    }
+  }
+  clearHeartbeatTimeout() {
+    if (this.heartbeatTimeout) {
+      clearTimeout(this.heartbeatTimeout);
+      this.heartbeatTimeout = null;
+    }
+  }
+  bumpHeartbeatTimeout(abortController) {
+    this.clearHeartbeatTimeout();
+    this.heartbeatTimeout = setTimeout(() => {
+      if (this.streamAbortController === abortController && !this.destroyed) {
+        abortController.abort();
+      }
+    }, this.heartbeatTimeoutMs);
+  }
+  scheduleReconnect() {
+    if (this.destroyed || this.reconnectTimeout) return;
+    const nextDelay = Math.min(
+      this.streamRetryDelay * 2 ** this.reconnectAttempts,
+      this.maxReconnectDelay
+    );
+    this.reconnectAttempts += 1;
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connectStream();
+    }, nextDelay);
+  }
+  async consumeStream(abortController) {
+    try {
+      const headers = { "X-Api-Key": this.apiKey };
+      if (this.environment) headers["X-Environment"] = this.environment;
+      const response = await fetch(`${this.baseUrl}/sdk/stream`, {
+        headers,
+        signal: abortController.signal,
+        cache: "no-store"
+      });
+      if (!response.ok) {
+        console.error(
+          `[canarygate] Failed to connect stream: ${response.status} ${response.statusText}`
+        );
+        this.stale = true;
+        return;
+      }
+      if (!response.body) {
+        console.error(
+          "[canarygate] Stream body is not available in this runtime"
+        );
+        this.stale = true;
+        return;
+      }
+      this.reconnectAttempts = 0;
+      this.bumpHeartbeatTimeout(abortController);
+      if (this.stale) {
+        await this.fetchFlags();
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (!abortController.signal.aborted) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        this.bumpHeartbeatTimeout(abortController);
+        buffer += decoder.decode(value, { stream: true });
+        const blocks = buffer.split(/\r?\n\r?\n/);
+        buffer = blocks.pop() ?? "";
+        for (const block of blocks) {
+          const parsedEvent = parseSseEventBlock(block);
+          if (!parsedEvent) continue;
+          if (parsedEvent.retryMs !== void 0) {
+            this.streamRetryDelay = parsedEvent.retryMs;
+          }
+          this.handleStreamMessage(parsedEvent.event, parsedEvent.data);
+        }
+      }
+      buffer += decoder.decode();
+      if (buffer.trim()) {
+        const parsedEvent = parseSseEventBlock(buffer);
+        if (parsedEvent) {
+          if (parsedEvent.retryMs !== void 0) {
+            this.streamRetryDelay = parsedEvent.retryMs;
+          }
+          this.handleStreamMessage(parsedEvent.event, parsedEvent.data);
+        }
+      }
+    } catch (err) {
+      if (!isAbortError(err)) {
+        console.error("[canarygate] Stream connection failed:", err);
+      }
+    } finally {
+      this.clearHeartbeatTimeout();
+      if (this.streamAbortController === abortController) {
+        this.streamAbortController = null;
+      }
+      if (!this.destroyed) {
+        this.stale = true;
+        this.scheduleReconnect();
+      }
+    }
+  }
+  connectStream() {
+    if (this.destroyed || this.streamAbortController) return;
+    const abortController = new AbortController();
+    this.streamAbortController = abortController;
+    void this.consumeStream(abortController);
+  }
+  getFlag(key, context) {
+    const raw = this.cache.get(key);
+    if (!raw) return void 0;
+    const evaluationId = context?.userId || this.anonId;
+    if (raw.type === "rollout") {
+      const inRollout = raw.enabled && hashString(`${raw.key}:${evaluationId}`) < raw.rolloutPercent;
+      return {
+        key: raw.key,
+        type: "rollout",
+        enabled: inRollout,
+        percent: raw.rolloutPercent
+      };
+    }
+    return { key: raw.key, type: "boolean", enabled: raw.enabled };
+  }
+  getFlags(context) {
+    return Array.from(this.cache.keys()).map(
+      (key) => this.getFlag(key, context)
+    );
+  }
+  isStale() {
+    return this.stale;
+  }
+  getLastSyncAt() {
+    return this.lastSyncAt;
+  }
+  disconnect() {
+    this.destroyed = true;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.clearHeartbeatTimeout();
+    this.streamAbortController?.abort();
+    this.streamAbortController = null;
+  }
+};
+
+// src/client.ts
+var ANON_ID_KEY = "__cg_anon_id__";
+function getOrCreateAnonId() {
+  if (typeof localStorage !== "undefined") {
+    const stored = localStorage.getItem(ANON_ID_KEY);
+    if (stored) return stored;
+    const id = crypto.randomUUID();
+    localStorage.setItem(ANON_ID_KEY, id);
+    return id;
+  }
+  return crypto.randomUUID();
+}
+var CanaryGate = class extends CanaryGateBase {
+  constructor(apiKey, options = {}) {
+    super(apiKey, options, false, getOrCreateAnonId);
+    if (options.stream === true) {
+      this.warnStreamDisabled();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CanaryGate
+});

package/dist/client.mjs

@@ -0,0 +1,27 @@
+import {
+  CanaryGateBase
+} from "./chunk-7KAJ7OJO.mjs";
+
+// src/client.ts
+var ANON_ID_KEY = "__cg_anon_id__";
+function getOrCreateAnonId() {
+  if (typeof localStorage !== "undefined") {
+    const stored = localStorage.getItem(ANON_ID_KEY);
+    if (stored) return stored;
+    const id = crypto.randomUUID();
+    localStorage.setItem(ANON_ID_KEY, id);
+    return id;
+  }
+  return crypto.randomUUID();
+}
+var CanaryGate = class extends CanaryGateBase {
+  constructor(apiKey, options = {}) {
+    super(apiKey, options, false, getOrCreateAnonId);
+    if (options.stream === true) {
+      this.warnStreamDisabled();
+    }
+  }
+};
+export {
+  CanaryGate
+};

package/dist/server.d.mts

@@ -0,0 +1,7 @@
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-D069Q1Z_.mjs';
+
+declare class CanaryGate extends CanaryGateBase {
+    constructor(apiKey: string, options?: CanaryGateOptions);
+}
+
+export { CanaryGate };

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-D069Q1Z_.js';
+
+declare class CanaryGate extends CanaryGateBase {
+    constructor(apiKey: string, options?: CanaryGateOptions);
+}
+
+export { CanaryGate };