@canarygate/sdk 0.1.0 → 0.1.1

package/README.md

@@ -2,8 +2,8 @@
 
 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
+- **Server (Node.js)** — snapshot on `init()` + live updates via SSE, auto-reconnect and heartbeat
+- **Browser** — snapshot + polling via `pollIntervalMs`
 
 ## Install
 
@@ -19,12 +19,11 @@ npm install @canarygate/sdk
 import { CanaryGate } from '@canarygate/sdk/server'
 
 const gate = new CanaryGate('your-api-key', {
-  environment: 'production',
-  stream: true
+  environment: 'production'
 })
 
 await gate.init()
-// flags keep updating in the background via SSE
+// the snapshot is fetched and SSE opens automatically
 
 gate.disconnect() // when shutting down
 ```
@@ -70,7 +69,7 @@ Rollout evaluation hashes `userId` deterministically — the same user always ge
 | -------------------- | --------- | ----------------------- | ------------------------------------------------ |
 | `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)         |
+| `pollIntervalMs`     | `number`  | `30000`                 | Browser polling interval in ms. Set `0` to disable |
 | `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 |
@@ -79,7 +78,7 @@ Rollout evaluation hashes `userId` deterministically — the same user always ge
 
 | Method                | Description                                        |
 | --------------------- | -------------------------------------------------- |
-| `init()`              | Fetches flags and starts the stream when enabled   |
+| `init()`              | Fetches the snapshot; the server entry opens SSE, the browser entry starts polling |
 | `getFlag(key, ctx?)`  | Evaluates one flag (`boolean` or `rollout`)        |
 | `getFlags(ctx?)`      | Evaluates all cached flags                         |
 | `isStale()`           | Whether the last sync attempt failed               |
@@ -89,9 +88,13 @@ Rollout evaluation hashes `userId` deterministically — the same user always ge
 ## How sync works
 
 1. `init()` fetches a full snapshot from `/sdk/flags`.
-2. With `stream: true`, an SSE connection receives granular updates per change.
+2. The server entry always opens an SSE connection that receives granular updates per change; the browser entry polls the snapshot every `pollIntervalMs`.
 3. On disconnect, the SDK reconnects with exponential backoff and does a full resync over the snapshot endpoint.
 
+## Entry-point guards
+
+Each entry point is bound to its environment: the server entry throws `Error('@canarygate/sdk/server is server-only. In browsers import from "@canarygate/sdk/client" instead.')` if used where `window` exists, and the client entry throws a browser-only error if used where there is no `window`.
+
 ## License
 
 [MIT](./LICENSE)

package/dist/{canary-gate-base-D069Q1Z_.d.mts → canary-gate-base-DzuUUPOC.d.mts}

@@ -16,7 +16,7 @@ type FlagEvaluationContext = {
 type CanaryGateOptions = {
     baseUrl?: string;
     environment?: string;
-    stream?: boolean;
+    pollIntervalMs?: number;
     reconnectDelay?: number;
     maxReconnectDelay?: number;
     heartbeatTimeoutMs?: number;
@@ -31,19 +31,20 @@ declare class CanaryGateBase {
     private readonly reconnectDelay;
     private readonly maxReconnectDelay;
     private readonly heartbeatTimeoutMs;
+    private readonly pollIntervalMs;
     private cache;
     private cacheVersions;
     private readonly anonId;
     private streamAbortController;
     private reconnectTimeout;
     private heartbeatTimeout;
+    private pollTimeout;
     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;
@@ -55,6 +56,8 @@ declare class CanaryGateBase {
     private scheduleReconnect;
     private consumeStream;
     private connectStream;
+    private startPolling;
+    private stopPolling;
     getFlag(key: string, context?: FlagEvaluationContext): FlagData | undefined;
     getFlags(context?: FlagEvaluationContext): FlagData[];
     isStale(): boolean;

package/dist/{canary-gate-base-D069Q1Z_.d.ts → canary-gate-base-DzuUUPOC.d.ts}

@@ -16,7 +16,7 @@ type FlagEvaluationContext = {
 type CanaryGateOptions = {
     baseUrl?: string;
     environment?: string;
-    stream?: boolean;
+    pollIntervalMs?: number;
     reconnectDelay?: number;
     maxReconnectDelay?: number;
     heartbeatTimeoutMs?: number;
@@ -31,19 +31,20 @@ declare class CanaryGateBase {
     private readonly reconnectDelay;
     private readonly maxReconnectDelay;
     private readonly heartbeatTimeoutMs;
+    private readonly pollIntervalMs;
     private cache;
     private cacheVersions;
     private readonly anonId;
     private streamAbortController;
     private reconnectTimeout;
     private heartbeatTimeout;
+    private pollTimeout;
     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;
@@ -55,6 +56,8 @@ declare class CanaryGateBase {
     private scheduleReconnect;
     private consumeStream;
     private connectStream;
+    private startPolling;
+    private stopPolling;
     getFlag(key: string, context?: FlagEvaluationContext): FlagData | undefined;
     getFlags(context?: FlagEvaluationContext): FlagData[];
     isStale(): boolean;

package/dist/{chunk-7KAJ7OJO.mjs → chunk-ECO47H4R.mjs}

@@ -42,6 +42,7 @@ function parseSseEventBlock(block) {
 // src/canary-gate-base.ts
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -59,6 +60,7 @@ var CanaryGateBase = class {
     this.streamAbortController = null;
     this.reconnectTimeout = null;
     this.heartbeatTimeout = null;
+    this.pollTimeout = null;
     this.reconnectAttempts = 0;
     this.stale = false;
     this.lastSyncAt = null;
@@ -74,17 +76,17 @@ var CanaryGateBase = class {
       this.reconnectDelay
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_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();
+    if (this.streamEnabled) {
+      this.connectStream();
+    } else {
+      this.startPolling();
+    }
   }
   replaceCacheFromSnapshot(flags, requestedAt) {
     const nextCache = /* @__PURE__ */ new Map();
@@ -270,6 +272,20 @@ var CanaryGateBase = class {
     this.streamAbortController = abortController;
     void this.consumeStream(abortController);
   }
+  startPolling() {
+    if (this.destroyed || this.streamEnabled || this.pollIntervalMs <= 0 || this.pollTimeout) {
+      return;
+    }
+    this.pollTimeout = setInterval(() => {
+      void this.fetchFlags();
+    }, this.pollIntervalMs);
+  }
+  stopPolling() {
+    if (this.pollTimeout) {
+      clearInterval(this.pollTimeout);
+      this.pollTimeout = null;
+    }
+  }
   getFlag(key, context) {
     const raw = this.cache.get(key);
     if (!raw) return void 0;
@@ -298,6 +314,7 @@ var CanaryGateBase = class {
   }
   disconnect() {
     this.destroyed = true;
+    this.stopPolling();
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;

package/dist/client.d.mts

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

package/dist/client.d.ts

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

package/dist/client.js

@@ -68,6 +68,7 @@ function parseSseEventBlock(block) {
 // src/canary-gate-base.ts
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -85,6 +86,7 @@ var CanaryGateBase = class {
     this.streamAbortController = null;
     this.reconnectTimeout = null;
     this.heartbeatTimeout = null;
+    this.pollTimeout = null;
     this.reconnectAttempts = 0;
     this.stale = false;
     this.lastSyncAt = null;
@@ -100,17 +102,17 @@ var CanaryGateBase = class {
       this.reconnectDelay
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_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();
+    if (this.streamEnabled) {
+      this.connectStream();
+    } else {
+      this.startPolling();
+    }
   }
   replaceCacheFromSnapshot(flags, requestedAt) {
     const nextCache = /* @__PURE__ */ new Map();
@@ -296,6 +298,20 @@ var CanaryGateBase = class {
     this.streamAbortController = abortController;
     void this.consumeStream(abortController);
   }
+  startPolling() {
+    if (this.destroyed || this.streamEnabled || this.pollIntervalMs <= 0 || this.pollTimeout) {
+      return;
+    }
+    this.pollTimeout = setInterval(() => {
+      void this.fetchFlags();
+    }, this.pollIntervalMs);
+  }
+  stopPolling() {
+    if (this.pollTimeout) {
+      clearInterval(this.pollTimeout);
+      this.pollTimeout = null;
+    }
+  }
   getFlag(key, context) {
     const raw = this.cache.get(key);
     if (!raw) return void 0;
@@ -324,6 +340,7 @@ var CanaryGateBase = class {
   }
   disconnect() {
     this.destroyed = true;
+    this.stopPolling();
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
@@ -348,10 +365,12 @@ function getOrCreateAnonId() {
 }
 var CanaryGate = class extends CanaryGateBase {
   constructor(apiKey, options = {}) {
-    super(apiKey, options, false, getOrCreateAnonId);
-    if (options.stream === true) {
-      this.warnStreamDisabled();
+    if (typeof window === "undefined") {
+      throw new Error(
+        '@canarygate/sdk/client is browser-only. On server runtimes (Node.js, Deno, Bun, Edge) import from "@canarygate/sdk/server" instead.'
+      );
     }
+    super(apiKey, options, false, getOrCreateAnonId);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/client.mjs

@@ -1,6 +1,6 @@
 import {
   CanaryGateBase
-} from "./chunk-7KAJ7OJO.mjs";
+} from "./chunk-ECO47H4R.mjs";
 
 // src/client.ts
 var ANON_ID_KEY = "__cg_anon_id__";
@@ -16,10 +16,12 @@ function getOrCreateAnonId() {
 }
 var CanaryGate = class extends CanaryGateBase {
   constructor(apiKey, options = {}) {
-    super(apiKey, options, false, getOrCreateAnonId);
-    if (options.stream === true) {
-      this.warnStreamDisabled();
+    if (typeof window === "undefined") {
+      throw new Error(
+        '@canarygate/sdk/client is browser-only. On server runtimes (Node.js, Deno, Bun, Edge) import from "@canarygate/sdk/server" instead.'
+      );
     }
+    super(apiKey, options, false, getOrCreateAnonId);
   }
 };
 export {

package/dist/server.d.mts

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

package/dist/server.d.ts

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

package/dist/server.js

@@ -68,6 +68,7 @@ function parseSseEventBlock(block) {
 // src/canary-gate-base.ts
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -85,6 +86,7 @@ var CanaryGateBase = class {
     this.streamAbortController = null;
     this.reconnectTimeout = null;
     this.heartbeatTimeout = null;
+    this.pollTimeout = null;
     this.reconnectAttempts = 0;
     this.stale = false;
     this.lastSyncAt = null;
@@ -100,17 +102,17 @@ var CanaryGateBase = class {
       this.reconnectDelay
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_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();
+    if (this.streamEnabled) {
+      this.connectStream();
+    } else {
+      this.startPolling();
+    }
   }
   replaceCacheFromSnapshot(flags, requestedAt) {
     const nextCache = /* @__PURE__ */ new Map();
@@ -296,6 +298,20 @@ var CanaryGateBase = class {
     this.streamAbortController = abortController;
     void this.consumeStream(abortController);
   }
+  startPolling() {
+    if (this.destroyed || this.streamEnabled || this.pollIntervalMs <= 0 || this.pollTimeout) {
+      return;
+    }
+    this.pollTimeout = setInterval(() => {
+      void this.fetchFlags();
+    }, this.pollIntervalMs);
+  }
+  stopPolling() {
+    if (this.pollTimeout) {
+      clearInterval(this.pollTimeout);
+      this.pollTimeout = null;
+    }
+  }
   getFlag(key, context) {
     const raw = this.cache.get(key);
     if (!raw) return void 0;
@@ -324,6 +340,7 @@ var CanaryGateBase = class {
   }
   disconnect() {
     this.destroyed = true;
+    this.stopPolling();
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
@@ -337,7 +354,12 @@ var CanaryGateBase = class {
 // src/server.ts
 var CanaryGate = class extends CanaryGateBase {
   constructor(apiKey, options = {}) {
-    super(apiKey, options, options.stream ?? false, () => crypto.randomUUID());
+    if (typeof window !== "undefined") {
+      throw new Error(
+        '@canarygate/sdk/server is server-only. In browsers import from "@canarygate/sdk/client" instead.'
+      );
+    }
+    super(apiKey, options, true, () => crypto.randomUUID());
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/server.mjs

@@ -1,11 +1,16 @@
 import {
   CanaryGateBase
-} from "./chunk-7KAJ7OJO.mjs";
+} from "./chunk-ECO47H4R.mjs";
 
 // src/server.ts
 var CanaryGate = class extends CanaryGateBase {
   constructor(apiKey, options = {}) {
-    super(apiKey, options, options.stream ?? false, () => crypto.randomUUID());
+    if (typeof window !== "undefined") {
+      throw new Error(
+        '@canarygate/sdk/server is server-only. In browsers import from "@canarygate/sdk/client" instead.'
+      );
+    }
+    super(apiKey, options, true, () => crypto.randomUUID());
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canarygate/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CanaryGate SDK — feature flags with real-time SSE streaming",
   "exports": {
     "./client": {
@@ -15,20 +15,18 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/client.ts src/server.ts --format esm,cjs --dts --out-dir dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "pnpm build"
+  },
   "sideEffects": false,
   "license": "MIT",
-  "keywords": [
-    "feature-flags",
-    "feature-toggles",
-    "sse",
-    "real-time",
-    "rollout"
-  ],
+  "keywords": ["feature-flags", "feature-toggles", "sse", "real-time", "rollout"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rborges98/canarygate.git",
@@ -47,12 +45,5 @@
     "tsup": "^8.5.1",
     "typescript": "^5",
     "vitest": "^3.0.0"
-  },
-  "scripts": {
-    "build": "tsup src/client.ts src/server.ts --format esm,cjs --dts --out-dir dist",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
   }
-}
+}