@canarygate/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CanaryGate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @canarygate/sdk
+
+Feature flag client for [CanaryGate](https://github.com/rborges98/canarygate).
+
+- **Server (Node.js)** — snapshot on `init()` + live updates via SSE, with auto-reconnect and heartbeat detection
+- **Browser** — flags fetched once and cached; SSE stays off to protect your infrastructure
+
+## Install
+
+```sh
+npm install @canarygate/sdk
+```
+
+## Quick start
+
+### Server — real-time
+
+```ts
+import { CanaryGate } from '@canarygate/sdk/server'
+
+const gate = new CanaryGate('your-api-key', {
+  environment: 'production',
+  stream: true
+})
+
+await gate.init()
+// flags keep updating in the background via SSE
+
+gate.disconnect() // when shutting down
+```
+
+### Browser — cached
+
+```ts
+import { CanaryGate } from '@canarygate/sdk/client'
+
+const gate = new CanaryGate('your-api-key', {
+  environment: 'production'
+})
+
+await gate.init()
+```
+
+## Evaluating flags
+
+```ts
+const flag = gate.getFlag('new-checkout', { userId: 'user-123' })
+
+if (flag?.enabled) {
+  // boolean flag is on,
+  // or user-123 falls inside the rollout percentage
+}
+
+const allFlags = gate.getFlags({ userId: 'user-123' })
+```
+
+Evaluations return a `FlagData`:
+
+```ts
+type FlagData =
+  | { key: string; type: 'boolean'; enabled: boolean }
+  | { key: string; type: 'rollout'; enabled: boolean; percent: number }
+```
+
+Rollout evaluation hashes `userId` deterministically — the same user always gets the same result for the same percentage.
+
+## Options
+
+| Option               | Type      | Default                 | Description                                      |
+| -------------------- | --------- | ----------------------- | ------------------------------------------------ |
+| `baseUrl`            | `string`  | `http://localhost:3001` | CanaryGate API base URL                          |
+| `environment`        | `string`  | —                       | Environment to evaluate flags against            |
+| `stream`             | `boolean` | `false`                 | Real-time SSE updates (server mode only)         |
+| `reconnectDelay`     | `number`  | `5000`                  | Initial SSE reconnect delay (ms)                 |
+| `maxReconnectDelay`  | `number`  | `30000`                 | Reconnect delay cap, exponential backoff (ms)    |
+| `heartbeatTimeoutMs` | `number`  | `65000`                 | Silence window before treating the stream as dead |
+
+## Methods
+
+| Method                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `init()`              | Fetches flags and starts the stream when enabled   |
+| `getFlag(key, ctx?)`  | Evaluates one flag (`boolean` or `rollout`)        |
+| `getFlags(ctx?)`      | Evaluates all cached flags                         |
+| `isStale()`           | Whether the last sync attempt failed               |
+| `getLastSyncAt()`     | Timestamp of the last successful sync              |
+| `disconnect()`        | Stops the stream and clears timers                 |
+
+## How sync works
+
+1. `init()` fetches a full snapshot from `/sdk/flags`.
+2. With `stream: true`, an SSE connection receives granular updates per change.
+3. On disconnect, the SDK reconnects with exponential backoff and does a full resync over the snapshot endpoint.
+
+## License
+
+[MIT](./LICENSE)

package/dist/canary-gate-base-D069Q1Z_.d.mts

@@ -0,0 +1,65 @@
+type BooleanFlagData = {
+    key: string;
+    type: 'boolean';
+    enabled: boolean;
+};
+type RolloutFlagData = {
+    key: string;
+    type: 'rollout';
+    enabled: boolean;
+    percent: number;
+};
+type FlagData = BooleanFlagData | RolloutFlagData;
+type FlagEvaluationContext = {
+    userId?: string;
+};
+type CanaryGateOptions = {
+    baseUrl?: string;
+    environment?: string;
+    stream?: boolean;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    heartbeatTimeoutMs?: number;
+};
+
+declare class CanaryGateBase {
+    protected readonly apiKey: string;
+    protected readonly streamEnabled: boolean;
+    protected readonly anonIdFactory: () => string;
+    private readonly baseUrl;
+    private readonly environment;
+    private readonly reconnectDelay;
+    private readonly maxReconnectDelay;
+    private readonly heartbeatTimeoutMs;
+    private cache;
+    private cacheVersions;
+    private readonly anonId;
+    private streamAbortController;
+    private reconnectTimeout;
+    private heartbeatTimeout;
+    private streamRetryDelay;
+    private reconnectAttempts;
+    private stale;
+    private lastSyncAt;
+    private destroyed;
+    constructor(apiKey: string, options: CanaryGateOptions | undefined, streamEnabled: boolean, anonIdFactory: () => string);
+    protected warnStreamDisabled(): void;
+    init(): Promise<void>;
+    private replaceCacheFromSnapshot;
+    private fetchFlags;
+    private applyFlagUpdate;
+    private applyFlagDeletion;
+    private handleStreamMessage;
+    private clearHeartbeatTimeout;
+    private bumpHeartbeatTimeout;
+    private scheduleReconnect;
+    private consumeStream;
+    private connectStream;
+    getFlag(key: string, context?: FlagEvaluationContext): FlagData | undefined;
+    getFlags(context?: FlagEvaluationContext): FlagData[];
+    isStale(): boolean;
+    getLastSyncAt(): string | null;
+    disconnect(): void;
+}
+
+export { CanaryGateBase as C, type CanaryGateOptions as a };

package/dist/canary-gate-base-D069Q1Z_.d.ts

@@ -0,0 +1,65 @@
+type BooleanFlagData = {
+    key: string;
+    type: 'boolean';
+    enabled: boolean;
+};
+type RolloutFlagData = {
+    key: string;
+    type: 'rollout';
+    enabled: boolean;
+    percent: number;
+};
+type FlagData = BooleanFlagData | RolloutFlagData;
+type FlagEvaluationContext = {
+    userId?: string;
+};
+type CanaryGateOptions = {
+    baseUrl?: string;
+    environment?: string;
+    stream?: boolean;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    heartbeatTimeoutMs?: number;
+};
+
+declare class CanaryGateBase {
+    protected readonly apiKey: string;
+    protected readonly streamEnabled: boolean;
+    protected readonly anonIdFactory: () => string;
+    private readonly baseUrl;
+    private readonly environment;
+    private readonly reconnectDelay;
+    private readonly maxReconnectDelay;
+    private readonly heartbeatTimeoutMs;
+    private cache;
+    private cacheVersions;
+    private readonly anonId;
+    private streamAbortController;
+    private reconnectTimeout;
+    private heartbeatTimeout;
+    private streamRetryDelay;
+    private reconnectAttempts;
+    private stale;
+    private lastSyncAt;
+    private destroyed;
+    constructor(apiKey: string, options: CanaryGateOptions | undefined, streamEnabled: boolean, anonIdFactory: () => string);
+    protected warnStreamDisabled(): void;
+    init(): Promise<void>;
+    private replaceCacheFromSnapshot;
+    private fetchFlags;
+    private applyFlagUpdate;
+    private applyFlagDeletion;
+    private handleStreamMessage;
+    private clearHeartbeatTimeout;
+    private bumpHeartbeatTimeout;
+    private scheduleReconnect;
+    private consumeStream;
+    private connectStream;
+    getFlag(key: string, context?: FlagEvaluationContext): FlagData | undefined;
+    getFlags(context?: FlagEvaluationContext): FlagData[];
+    isStale(): boolean;
+    getLastSyncAt(): string | null;
+    disconnect(): void;
+}
+
+export { CanaryGateBase as C, type CanaryGateOptions as a };

package/dist/chunk-7KAJ7OJO.mjs

@@ -0,0 +1,313 @@
+// 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;
+  }
+};
+
+export {
+  CanaryGateBase
+};

package/dist/client.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/client.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 };