@canarygate/sdk 0.1.1 → 0.1.3

package/README.md

@@ -65,14 +65,15 @@ Rollout evaluation hashes `userId` deterministically — the same user always ge
 
 ## Options
 
+The API base URL is resolved automatically from the `CANARYGATE_BASE_URL` environment variable (in browsers, `NEXT_PUBLIC_CANARYGATE_BASE_URL`), falling back to `http://localhost:3001`.
+
 | Option               | Type      | Default                 | Description                                      |
 | -------------------- | --------- | ----------------------- | ------------------------------------------------ |
-| `baseUrl`            | `string`  | `http://localhost:3001` | CanaryGate API base URL                          |
 | `environment`        | `string`  | —                       | Environment to evaluate flags against            |
-| `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 |
+| `pollIntervalMs`     | `number`  | `30000`                 | Browser polling interval in ms (clamped to a 3000ms minimum). Set `0` to disable. Throws if passed to the server entry |
+| `reconnectDelay`     | `number`  | `5000`                  | Initial SSE reconnect delay (ms). Server-only; throws on the browser entry |
+| `maxReconnectDelay`  | `number`  | `30000`                 | Reconnect delay cap, exponential backoff (ms). Server-only |
+| `heartbeatTimeoutMs` | `number`  | `65000`                 | Silence window before treating the stream as dead. Server-only |
 
 ## Methods
 

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

@@ -16,6 +16,7 @@ type FlagEvaluationContext = {
 type CanaryGateOptions = {
     baseUrl?: string;
     environment?: string;
+    /** Browser polling interval in ms. Default: 30000; minimum enforced: 3000. Set 0 to disable. Server always uses SSE instead. */
     pollIntervalMs?: number;
     reconnectDelay?: number;
     maxReconnectDelay?: number;

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

@@ -16,6 +16,7 @@ type FlagEvaluationContext = {
 type CanaryGateOptions = {
     baseUrl?: string;
     environment?: string;
+    /** Browser polling interval in ms. Default: 30000; minimum enforced: 3000. Set 0 to disable. Server always uses SSE instead. */
     pollIntervalMs?: number;
     reconnectDelay?: number;
     maxReconnectDelay?: number;

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

@@ -0,0 +1,71 @@
+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 = {
+    environment?: string;
+    /** Browser polling interval in ms. Default: 30000; minimum enforced: 3000. Set 0 to disable. Throws if set on the server entry. */
+    pollIntervalMs?: number;
+    /** Initial stream reconnect delay in ms. Default: 5000. Server-only. */
+    reconnectDelay?: number;
+    /** Maximum stream reconnect delay in ms. Default: 30000. Server-only. */
+    maxReconnectDelay?: number;
+    /** Time in ms without a server heartbeat before reconnecting the stream. Default: 65000. Server-only. */
+    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 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);
+    init(): Promise<void>;
+    private replaceCacheFromSnapshot;
+    private fetchFlags;
+    private applyFlagUpdate;
+    private applyFlagDeletion;
+    private handleStreamMessage;
+    private clearHeartbeatTimeout;
+    private bumpHeartbeatTimeout;
+    private scheduleReconnect;
+    private consumeStream;
+    private connectStream;
+    private startPolling;
+    private stopPolling;
+    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-jk1htbug.d.ts

@@ -0,0 +1,71 @@
+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 = {
+    environment?: string;
+    /** Browser polling interval in ms. Default: 30000; minimum enforced: 3000. Set 0 to disable. Throws if set on the server entry. */
+    pollIntervalMs?: number;
+    /** Initial stream reconnect delay in ms. Default: 5000. Server-only. */
+    reconnectDelay?: number;
+    /** Maximum stream reconnect delay in ms. Default: 30000. Server-only. */
+    maxReconnectDelay?: number;
+    /** Time in ms without a server heartbeat before reconnecting the stream. Default: 65000. Server-only. */
+    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 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);
+    init(): Promise<void>;
+    private replaceCacheFromSnapshot;
+    private fetchFlags;
+    private applyFlagUpdate;
+    private applyFlagDeletion;
+    private handleStreamMessage;
+    private clearHeartbeatTimeout;
+    private bumpHeartbeatTimeout;
+    private scheduleReconnect;
+    private consumeStream;
+    private connectStream;
+    private startPolling;
+    private stopPolling;
+    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-ECO47H4R.mjs → chunk-LMPIWD3Z.mjs}

@@ -43,6 +43,7 @@ function parseSseEventBlock(block) {
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MIN_POLL_INTERVAL_MS = 3e3;
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -77,6 +78,12 @@ var CanaryGateBase = class {
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (options.pollIntervalMs !== void 0 && options.pollIntervalMs > 0 && options.pollIntervalMs < MIN_POLL_INTERVAL_MS) {
+      console.warn(
+        `[canarygate] pollIntervalMs must be at least ${MIN_POLL_INTERVAL_MS}ms; clamped to ${MIN_POLL_INTERVAL_MS}.`
+      );
+      this.pollIntervalMs = MIN_POLL_INTERVAL_MS;
+    }
     this.streamRetryDelay = this.reconnectDelay;
     this.anonId = anonIdFactory();
   }

package/dist/chunk-X2JAB5XL.mjs

@@ -0,0 +1,341 @@
+// 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;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MIN_POLL_INTERVAL_MS = 3e3;
+var DEFAULT_BASE_URL = "http://localhost:3001";
+function resolveBaseUrl() {
+  if (typeof process !== "undefined" && typeof process.env === "object" && process.env !== null) {
+    return (process.env.CANARYGATE_BASE_URL ?? process.env.NEXT_PUBLIC_CANARYGATE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  return DEFAULT_BASE_URL;
+}
+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.pollTimeout = null;
+    this.reconnectAttempts = 0;
+    this.stale = false;
+    this.lastSyncAt = null;
+    this.destroyed = false;
+    this.baseUrl = resolveBaseUrl();
+    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.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (options.pollIntervalMs !== void 0 && options.pollIntervalMs > 0 && options.pollIntervalMs < MIN_POLL_INTERVAL_MS) {
+      console.warn(
+        `[canarygate] pollIntervalMs must be at least ${MIN_POLL_INTERVAL_MS}ms; clamped to ${MIN_POLL_INTERVAL_MS}.`
+      );
+      this.pollIntervalMs = MIN_POLL_INTERVAL_MS;
+    }
+    this.streamRetryDelay = this.reconnectDelay;
+    this.anonId = anonIdFactory();
+  }
+  async init() {
+    await this.fetchFlags();
+    if (this.streamEnabled) {
+      this.connectStream();
+    } else {
+      this.startPolling();
+    }
+  }
+  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);
+  }
+  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;
+    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;
+    this.stopPolling();
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.clearHeartbeatTimeout();
+    this.streamAbortController?.abort();
+    this.streamAbortController = null;
+  }
+};
+
+export {
+  CanaryGateBase
+};

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-DzuUUPOC.mjs';
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-jk1htbug.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-DzuUUPOC.js';
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-jk1htbug.js';
 
 declare class CanaryGate extends CanaryGateBase {
     constructor(apiKey: string, options?: CanaryGateOptions);

package/dist/client.js

@@ -69,6 +69,14 @@ function parseSseEventBlock(block) {
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MIN_POLL_INTERVAL_MS = 3e3;
+var DEFAULT_BASE_URL = "http://localhost:3001";
+function resolveBaseUrl() {
+  if (typeof process !== "undefined" && typeof process.env === "object" && process.env !== null) {
+    return (process.env.CANARYGATE_BASE_URL ?? process.env.NEXT_PUBLIC_CANARYGATE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  return DEFAULT_BASE_URL;
+}
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -91,10 +99,7 @@ var CanaryGateBase = class {
     this.stale = false;
     this.lastSyncAt = null;
     this.destroyed = false;
-    this.baseUrl = (options.baseUrl ?? "http://localhost:3001").replace(
-      /\/$/,
-      ""
-    );
+    this.baseUrl = resolveBaseUrl();
     this.environment = options.environment;
     this.reconnectDelay = options.reconnectDelay ?? 5e3;
     this.maxReconnectDelay = Math.max(
@@ -103,6 +108,12 @@ var CanaryGateBase = class {
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (options.pollIntervalMs !== void 0 && options.pollIntervalMs > 0 && options.pollIntervalMs < MIN_POLL_INTERVAL_MS) {
+      console.warn(
+        `[canarygate] pollIntervalMs must be at least ${MIN_POLL_INTERVAL_MS}ms; clamped to ${MIN_POLL_INTERVAL_MS}.`
+      );
+      this.pollIntervalMs = MIN_POLL_INTERVAL_MS;
+    }
     this.streamRetryDelay = this.reconnectDelay;
     this.anonId = anonIdFactory();
   }
@@ -353,6 +364,11 @@ var CanaryGateBase = class {
 
 // src/client.ts
 var ANON_ID_KEY = "__cg_anon_id__";
+var SERVER_ONLY_OPTIONS = [
+  "reconnectDelay",
+  "maxReconnectDelay",
+  "heartbeatTimeoutMs"
+];
 function getOrCreateAnonId() {
   if (typeof localStorage !== "undefined") {
     const stored = localStorage.getItem(ANON_ID_KEY);
@@ -370,6 +386,13 @@ var CanaryGate = class extends CanaryGateBase {
         '@canarygate/sdk/client is browser-only. On server runtimes (Node.js, Deno, Bun, Edge) import from "@canarygate/sdk/server" instead.'
       );
     }
+    for (const key of SERVER_ONLY_OPTIONS) {
+      if (options[key] !== void 0) {
+        throw new Error(
+          `"${key}" is a server-only option and has no effect on @canarygate/sdk/client. Remove it, or use @canarygate/sdk/server.`
+        );
+      }
+    }
     super(apiKey, options, false, getOrCreateAnonId);
   }
 };

package/dist/client.mjs

@@ -1,9 +1,14 @@
 import {
   CanaryGateBase
-} from "./chunk-ECO47H4R.mjs";
+} from "./chunk-X2JAB5XL.mjs";
 
 // src/client.ts
 var ANON_ID_KEY = "__cg_anon_id__";
+var SERVER_ONLY_OPTIONS = [
+  "reconnectDelay",
+  "maxReconnectDelay",
+  "heartbeatTimeoutMs"
+];
 function getOrCreateAnonId() {
   if (typeof localStorage !== "undefined") {
     const stored = localStorage.getItem(ANON_ID_KEY);
@@ -21,6 +26,13 @@ var CanaryGate = class extends CanaryGateBase {
         '@canarygate/sdk/client is browser-only. On server runtimes (Node.js, Deno, Bun, Edge) import from "@canarygate/sdk/server" instead.'
       );
     }
+    for (const key of SERVER_ONLY_OPTIONS) {
+      if (options[key] !== void 0) {
+        throw new Error(
+          `"${key}" is a server-only option and has no effect on @canarygate/sdk/client. Remove it, or use @canarygate/sdk/server.`
+        );
+      }
+    }
     super(apiKey, options, false, getOrCreateAnonId);
   }
 };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-DzuUUPOC.mjs';
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-jk1htbug.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-DzuUUPOC.js';
+import { C as CanaryGateBase, a as CanaryGateOptions } from './canary-gate-base-jk1htbug.js';
 
 declare class CanaryGate extends CanaryGateBase {
     constructor(apiKey: string, options?: CanaryGateOptions);

package/dist/server.js

@@ -69,6 +69,14 @@ function parseSseEventBlock(block) {
 var DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 65e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MIN_POLL_INTERVAL_MS = 3e3;
+var DEFAULT_BASE_URL = "http://localhost:3001";
+function resolveBaseUrl() {
+  if (typeof process !== "undefined" && typeof process.env === "object" && process.env !== null) {
+    return (process.env.CANARYGATE_BASE_URL ?? process.env.NEXT_PUBLIC_CANARYGATE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  return DEFAULT_BASE_URL;
+}
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -91,10 +99,7 @@ var CanaryGateBase = class {
     this.stale = false;
     this.lastSyncAt = null;
     this.destroyed = false;
-    this.baseUrl = (options.baseUrl ?? "http://localhost:3001").replace(
-      /\/$/,
-      ""
-    );
+    this.baseUrl = resolveBaseUrl();
     this.environment = options.environment;
     this.reconnectDelay = options.reconnectDelay ?? 5e3;
     this.maxReconnectDelay = Math.max(
@@ -103,6 +108,12 @@ var CanaryGateBase = class {
     );
     this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (options.pollIntervalMs !== void 0 && options.pollIntervalMs > 0 && options.pollIntervalMs < MIN_POLL_INTERVAL_MS) {
+      console.warn(
+        `[canarygate] pollIntervalMs must be at least ${MIN_POLL_INTERVAL_MS}ms; clamped to ${MIN_POLL_INTERVAL_MS}.`
+      );
+      this.pollIntervalMs = MIN_POLL_INTERVAL_MS;
+    }
     this.streamRetryDelay = this.reconnectDelay;
     this.anonId = anonIdFactory();
   }
@@ -359,6 +370,11 @@ var CanaryGate = class extends CanaryGateBase {
         '@canarygate/sdk/server is server-only. In browsers import from "@canarygate/sdk/client" instead.'
       );
     }
+    if (options.pollIntervalMs !== void 0) {
+      throw new Error(
+        '"pollIntervalMs" is a browser-only option and has no effect on @canarygate/sdk/server. Remove it, or use @canarygate/sdk/client.'
+      );
+    }
     super(apiKey, options, true, () => crypto.randomUUID());
   }
 };

package/dist/server.mjs

@@ -1,6 +1,6 @@
 import {
   CanaryGateBase
-} from "./chunk-ECO47H4R.mjs";
+} from "./chunk-X2JAB5XL.mjs";
 
 // src/server.ts
 var CanaryGate = class extends CanaryGateBase {
@@ -10,6 +10,11 @@ var CanaryGate = class extends CanaryGateBase {
         '@canarygate/sdk/server is server-only. In browsers import from "@canarygate/sdk/client" instead.'
       );
     }
+    if (options.pollIntervalMs !== void 0) {
+      throw new Error(
+        '"pollIntervalMs" is a browser-only option and has no effect on @canarygate/sdk/server. Remove it, or use @canarygate/sdk/client.'
+      );
+    }
     super(apiKey, options, true, () => crypto.randomUUID());
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canarygate/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CanaryGate SDK — feature flags with real-time SSE streaming",
   "exports": {
     "./client": {