@togglerino/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,198 @@
+/**
+ * Configuration for the Togglerino SDK client.
+ */
+interface TogglerinoConfig {
+    /** Base URL of the Togglerino server (e.g. "http://localhost:8080"). */
+    serverUrl: string;
+    /** SDK key for authenticating with the server. */
+    sdkKey: string;
+    /** Optional evaluation context (user, attributes). */
+    context?: EvaluationContext;
+    /**
+     * Whether to use SSE streaming for real-time flag updates.
+     * Falls back to polling if SSE connection fails.
+     * @default true
+     */
+    streaming?: boolean;
+    /**
+     * Polling interval in milliseconds. Used when streaming is disabled
+     * or as a fallback when SSE connection fails.
+     * @default 30000
+     */
+    pollingInterval?: number;
+}
+/**
+ * Context passed to the server for flag evaluation (targeting rules).
+ */
+interface EvaluationContext {
+    /** Unique user identifier. Maps to "user_id" on the server. */
+    userId?: string;
+    /** Arbitrary attributes for targeting (e.g. { plan: "pro", country: "US" }). */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Result of evaluating a single flag.
+ */
+interface EvaluationResult {
+    value: unknown;
+    variant: string;
+    reason: string;
+}
+/**
+ * SSE event emitted when a flag changes.
+ */
+interface FlagChangeEvent {
+    flagKey: string;
+    value: unknown;
+    variant: string;
+}
+/**
+ * SSE event emitted when a flag is deleted.
+ */
+interface FlagDeletedEvent {
+    flagKey: string;
+}
+/**
+ * Events emitted by the Togglerino client.
+ * - "ready": fired after initial flag fetch completes.
+ * - "change": fired when a flag value changes (via SSE or polling).
+ * - "deleted": fired when a flag is deleted (via SSE). Payload is FlagDeletedEvent.
+ * - "context_change": fired after updateContext() completes. Payload is EvaluationContext.
+ * - "error": fired on fetch/SSE errors.
+ * - "reconnecting": fired when scheduling an SSE reconnection attempt. Payload: { attempt: number, delay: number }.
+ * - "reconnected": fired when SSE successfully reconnects after a disconnection.
+ */
+type EventType = 'change' | 'deleted' | 'context_change' | 'error' | 'ready' | 'reconnecting' | 'reconnected';
+
+type Listener = (...args: any[]) => void;
+/**
+ * Togglerino SDK client.
+ *
+ * Usage:
+ * ```ts
+ * const client = new Togglerino({
+ *   serverUrl: 'http://localhost:8080',
+ *   sdkKey: 'sdk_abc123',
+ *   context: { userId: 'user-42' },
+ * })
+ *
+ * await client.initialize()
+ *
+ * if (client.getBool('dark-mode')) {
+ *   enableDarkMode()
+ * }
+ *
+ * client.on('change', (event) => {
+ *   console.log('flag changed:', event.flagKey, event.value)
+ * })
+ * ```
+ */
+declare class Togglerino {
+    private config;
+    private flags;
+    private listeners;
+    private pollTimer;
+    private sseAbortController;
+    private initialized;
+    private sseRetryCount;
+    private sseRetryTimeout;
+    private readonly maxRetryDelay;
+    constructor(config: TogglerinoConfig);
+    /**
+     * Initialize the client: fetch all flags and start listening for updates.
+     * Must be called before reading any flag values.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get a boolean flag value.
+     * Returns `defaultValue` if the flag is not found or is not a boolean.
+     */
+    getBool(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get a string flag value.
+     * Returns `defaultValue` if the flag is not found or is not a string.
+     */
+    getString(key: string, defaultValue?: string): string;
+    /**
+     * Get a numeric flag value.
+     * Returns `defaultValue` if the flag is not found or is not a number.
+     */
+    getNumber(key: string, defaultValue?: number): number;
+    /**
+     * Get a JSON flag value (object, array, etc.).
+     * Returns `defaultValue` if the flag is not found.
+     */
+    getJson<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Get the raw EvaluationResult for a flag.
+     * Returns undefined if the flag is not found.
+     */
+    getDetail(key: string): EvaluationResult | undefined;
+    /**
+     * Subscribe to SDK events.
+     * Returns an unsubscribe function.
+     *
+     * Events:
+     * - "ready": no payload, fired after initialize() completes.
+     * - "change": payload is FlagChangeEvent.
+     * - "context_change": payload is EvaluationContext, fired after updateContext() completes.
+     * - "error": payload is Error.
+     * - "reconnecting": payload is { attempt: number, delay: number }, fired when scheduling SSE reconnect.
+     * - "reconnected": no payload, fired when SSE successfully reconnects after a disconnection.
+     */
+    on(event: EventType, listener: Listener): () => void;
+    /**
+     * Get the current evaluation context.
+     */
+    getContext(): EvaluationContext;
+    /**
+     * Update the evaluation context and re-fetch all flags.
+     * Useful when the user logs in / changes attributes.
+     */
+    updateContext(context: Partial<EvaluationContext>): Promise<void>;
+    /**
+     * Stop all background activity (SSE stream, polling) and remove listeners.
+     * Call this when the client is no longer needed.
+     */
+    close(): void;
+    /**
+     * Fetch all flags from the server evaluation endpoint.
+     */
+    private fetchFlags;
+    /**
+     * Calculate the next retry delay using exponential backoff.
+     * Sequence: 1s, 2s, 4s, 8s, 16s, 30s (capped).
+     */
+    private getRetryDelay;
+    /**
+     * Schedule an SSE reconnection attempt with exponential backoff.
+     * Starts polling as a fallback while retrying.
+     */
+    private scheduleSSEReconnect;
+    /**
+     * Start an SSE connection using fetch + ReadableStream.
+     * This allows us to send an Authorization header (unlike native EventSource).
+     * On failure, schedules a reconnection attempt with exponential backoff
+     * and uses polling as a fallback in the meantime.
+     */
+    private startSSE;
+    /**
+     * Read and parse SSE events from a ReadableStream.
+     * SSE format:
+     *   event: flag_update
+     *   data: {"flagKey":"dark-mode","value":true,"variant":"on"}
+     *
+     */
+    private processSSEStream;
+    /**
+     * Parse a single SSE event block and update flags accordingly.
+     */
+    private handleSSEEvent;
+    /**
+     * Start periodic polling as a fallback when SSE is unavailable.
+     */
+    private startPolling;
+    private emit;
+}
+
+export { type EvaluationContext, type EvaluationResult, type EventType, type FlagChangeEvent, type FlagDeletedEvent, Togglerino, type TogglerinoConfig };

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Configuration for the Togglerino SDK client.
+ */
+interface TogglerinoConfig {
+    /** Base URL of the Togglerino server (e.g. "http://localhost:8080"). */
+    serverUrl: string;
+    /** SDK key for authenticating with the server. */
+    sdkKey: string;
+    /** Optional evaluation context (user, attributes). */
+    context?: EvaluationContext;
+    /**
+     * Whether to use SSE streaming for real-time flag updates.
+     * Falls back to polling if SSE connection fails.
+     * @default true
+     */
+    streaming?: boolean;
+    /**
+     * Polling interval in milliseconds. Used when streaming is disabled
+     * or as a fallback when SSE connection fails.
+     * @default 30000
+     */
+    pollingInterval?: number;
+}
+/**
+ * Context passed to the server for flag evaluation (targeting rules).
+ */
+interface EvaluationContext {
+    /** Unique user identifier. Maps to "user_id" on the server. */
+    userId?: string;
+    /** Arbitrary attributes for targeting (e.g. { plan: "pro", country: "US" }). */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Result of evaluating a single flag.
+ */
+interface EvaluationResult {
+    value: unknown;
+    variant: string;
+    reason: string;
+}
+/**
+ * SSE event emitted when a flag changes.
+ */
+interface FlagChangeEvent {
+    flagKey: string;
+    value: unknown;
+    variant: string;
+}
+/**
+ * SSE event emitted when a flag is deleted.
+ */
+interface FlagDeletedEvent {
+    flagKey: string;
+}
+/**
+ * Events emitted by the Togglerino client.
+ * - "ready": fired after initial flag fetch completes.
+ * - "change": fired when a flag value changes (via SSE or polling).
+ * - "deleted": fired when a flag is deleted (via SSE). Payload is FlagDeletedEvent.
+ * - "context_change": fired after updateContext() completes. Payload is EvaluationContext.
+ * - "error": fired on fetch/SSE errors.
+ * - "reconnecting": fired when scheduling an SSE reconnection attempt. Payload: { attempt: number, delay: number }.
+ * - "reconnected": fired when SSE successfully reconnects after a disconnection.
+ */
+type EventType = 'change' | 'deleted' | 'context_change' | 'error' | 'ready' | 'reconnecting' | 'reconnected';
+
+type Listener = (...args: any[]) => void;
+/**
+ * Togglerino SDK client.
+ *
+ * Usage:
+ * ```ts
+ * const client = new Togglerino({
+ *   serverUrl: 'http://localhost:8080',
+ *   sdkKey: 'sdk_abc123',
+ *   context: { userId: 'user-42' },
+ * })
+ *
+ * await client.initialize()
+ *
+ * if (client.getBool('dark-mode')) {
+ *   enableDarkMode()
+ * }
+ *
+ * client.on('change', (event) => {
+ *   console.log('flag changed:', event.flagKey, event.value)
+ * })
+ * ```
+ */
+declare class Togglerino {
+    private config;
+    private flags;
+    private listeners;
+    private pollTimer;
+    private sseAbortController;
+    private initialized;
+    private sseRetryCount;
+    private sseRetryTimeout;
+    private readonly maxRetryDelay;
+    constructor(config: TogglerinoConfig);
+    /**
+     * Initialize the client: fetch all flags and start listening for updates.
+     * Must be called before reading any flag values.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get a boolean flag value.
+     * Returns `defaultValue` if the flag is not found or is not a boolean.
+     */
+    getBool(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get a string flag value.
+     * Returns `defaultValue` if the flag is not found or is not a string.
+     */
+    getString(key: string, defaultValue?: string): string;
+    /**
+     * Get a numeric flag value.
+     * Returns `defaultValue` if the flag is not found or is not a number.
+     */
+    getNumber(key: string, defaultValue?: number): number;
+    /**
+     * Get a JSON flag value (object, array, etc.).
+     * Returns `defaultValue` if the flag is not found.
+     */
+    getJson<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Get the raw EvaluationResult for a flag.
+     * Returns undefined if the flag is not found.
+     */
+    getDetail(key: string): EvaluationResult | undefined;
+    /**
+     * Subscribe to SDK events.
+     * Returns an unsubscribe function.
+     *
+     * Events:
+     * - "ready": no payload, fired after initialize() completes.
+     * - "change": payload is FlagChangeEvent.
+     * - "context_change": payload is EvaluationContext, fired after updateContext() completes.
+     * - "error": payload is Error.
+     * - "reconnecting": payload is { attempt: number, delay: number }, fired when scheduling SSE reconnect.
+     * - "reconnected": no payload, fired when SSE successfully reconnects after a disconnection.
+     */
+    on(event: EventType, listener: Listener): () => void;
+    /**
+     * Get the current evaluation context.
+     */
+    getContext(): EvaluationContext;
+    /**
+     * Update the evaluation context and re-fetch all flags.
+     * Useful when the user logs in / changes attributes.
+     */
+    updateContext(context: Partial<EvaluationContext>): Promise<void>;
+    /**
+     * Stop all background activity (SSE stream, polling) and remove listeners.
+     * Call this when the client is no longer needed.
+     */
+    close(): void;
+    /**
+     * Fetch all flags from the server evaluation endpoint.
+     */
+    private fetchFlags;
+    /**
+     * Calculate the next retry delay using exponential backoff.
+     * Sequence: 1s, 2s, 4s, 8s, 16s, 30s (capped).
+     */
+    private getRetryDelay;
+    /**
+     * Schedule an SSE reconnection attempt with exponential backoff.
+     * Starts polling as a fallback while retrying.
+     */
+    private scheduleSSEReconnect;
+    /**
+     * Start an SSE connection using fetch + ReadableStream.
+     * This allows us to send an Authorization header (unlike native EventSource).
+     * On failure, schedules a reconnection attempt with exponential backoff
+     * and uses polling as a fallback in the meantime.
+     */
+    private startSSE;
+    /**
+     * Read and parse SSE events from a ReadableStream.
+     * SSE format:
+     *   event: flag_update
+     *   data: {"flagKey":"dark-mode","value":true,"variant":"on"}
+     *
+     */
+    private processSSEStream;
+    /**
+     * Parse a single SSE event block and update flags accordingly.
+     */
+    private handleSSEEvent;
+    /**
+     * Start periodic polling as a fallback when SSE is unavailable.
+     */
+    private startPolling;
+    private emit;
+}
+
+export { type EvaluationContext, type EvaluationResult, type EventType, type FlagChangeEvent, type FlagDeletedEvent, Togglerino, type TogglerinoConfig };

package/dist/index.js

@@ -0,0 +1,392 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Togglerino: () => Togglerino
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var Togglerino = class {
+  constructor(config) {
+    this.flags = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Map();
+    this.pollTimer = null;
+    this.sseAbortController = null;
+    this.initialized = false;
+    this.sseRetryCount = 0;
+    this.sseRetryTimeout = null;
+    this.maxRetryDelay = 3e4;
+    this.config = {
+      serverUrl: config.serverUrl.replace(/\/+$/, ""),
+      // strip trailing slash
+      sdkKey: config.sdkKey,
+      context: config.context ?? {},
+      streaming: config.streaming ?? true,
+      pollingInterval: config.pollingInterval ?? 3e4
+    };
+  }
+  /**
+   * Initialize the client: fetch all flags and start listening for updates.
+   * Must be called before reading any flag values.
+   */
+  async initialize() {
+    await this.fetchFlags();
+    this.initialized = true;
+    if (this.config.streaming) {
+      this.startSSE();
+    } else {
+      this.startPolling();
+    }
+    this.emit("ready", void 0);
+  }
+  // ---------------------------------------------------------------------------
+  // Typed flag getters (synchronous, read from local cache)
+  // ---------------------------------------------------------------------------
+  /**
+   * Get a boolean flag value.
+   * Returns `defaultValue` if the flag is not found or is not a boolean.
+   */
+  getBool(key, defaultValue = false) {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "boolean") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a string flag value.
+   * Returns `defaultValue` if the flag is not found or is not a string.
+   */
+  getString(key, defaultValue = "") {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "string") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a numeric flag value.
+   * Returns `defaultValue` if the flag is not found or is not a number.
+   */
+  getNumber(key, defaultValue = 0) {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "number") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a JSON flag value (object, array, etc.).
+   * Returns `defaultValue` if the flag is not found.
+   */
+  getJson(key, defaultValue) {
+    const result = this.flags.get(key);
+    if (result === void 0) {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get the raw EvaluationResult for a flag.
+   * Returns undefined if the flag is not found.
+   */
+  getDetail(key) {
+    return this.flags.get(key);
+  }
+  // ---------------------------------------------------------------------------
+  // Event emitter
+  // ---------------------------------------------------------------------------
+  /**
+   * Subscribe to SDK events.
+   * Returns an unsubscribe function.
+   *
+   * Events:
+   * - "ready": no payload, fired after initialize() completes.
+   * - "change": payload is FlagChangeEvent.
+   * - "context_change": payload is EvaluationContext, fired after updateContext() completes.
+   * - "error": payload is Error.
+   * - "reconnecting": payload is { attempt: number, delay: number }, fired when scheduling SSE reconnect.
+   * - "reconnected": no payload, fired when SSE successfully reconnects after a disconnection.
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return () => {
+      this.listeners.get(event)?.delete(listener);
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Context management
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the current evaluation context.
+   */
+  getContext() {
+    return {
+      ...this.config.context,
+      attributes: this.config.context.attributes ? { ...this.config.context.attributes } : void 0
+    };
+  }
+  /**
+   * Update the evaluation context and re-fetch all flags.
+   * Useful when the user logs in / changes attributes.
+   */
+  async updateContext(context) {
+    this.config.context = {
+      ...this.config.context,
+      ...context
+    };
+    await this.fetchFlags();
+    this.emit("context_change", this.getContext());
+  }
+  // ---------------------------------------------------------------------------
+  // Cleanup
+  // ---------------------------------------------------------------------------
+  /**
+   * Stop all background activity (SSE stream, polling) and remove listeners.
+   * Call this when the client is no longer needed.
+   */
+  close() {
+    if (this.pollTimer !== null) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.sseAbortController) {
+      this.sseAbortController.abort();
+      this.sseAbortController = null;
+    }
+    if (this.sseRetryTimeout) {
+      clearTimeout(this.sseRetryTimeout);
+      this.sseRetryTimeout = null;
+    }
+    this.sseRetryCount = 0;
+    this.listeners.clear();
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: flag fetching
+  // ---------------------------------------------------------------------------
+  /**
+   * Fetch all flags from the server evaluation endpoint.
+   */
+  async fetchFlags() {
+    const url = `${this.config.serverUrl}/api/v1/evaluate`;
+    const body = {
+      context: {
+        user_id: this.config.context.userId ?? "",
+        attributes: this.config.context.attributes ?? {}
+      }
+    };
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.sdkKey}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Togglerino: flag evaluation failed with status ${response.status}`
+        );
+      }
+      const data = await response.json();
+      const oldFlags = new Map(this.flags);
+      this.flags.clear();
+      for (const [key, result] of Object.entries(data.flags)) {
+        this.flags.set(key, result);
+        if (this.initialized) {
+          const old = oldFlags.get(key);
+          if (!old || JSON.stringify(old.value) !== JSON.stringify(result.value)) {
+            this.emit("change", {
+              flagKey: key,
+              value: result.value,
+              variant: result.variant
+            });
+          }
+        }
+      }
+    } catch (error) {
+      this.emit("error", error);
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: SSE streaming (fetch-based with ReadableStream)
+  // ---------------------------------------------------------------------------
+  /**
+   * Calculate the next retry delay using exponential backoff.
+   * Sequence: 1s, 2s, 4s, 8s, 16s, 30s (capped).
+   */
+  getRetryDelay() {
+    const delay = Math.min(1e3 * Math.pow(2, this.sseRetryCount), this.maxRetryDelay);
+    this.sseRetryCount++;
+    return delay;
+  }
+  /**
+   * Schedule an SSE reconnection attempt with exponential backoff.
+   * Starts polling as a fallback while retrying.
+   */
+  scheduleSSEReconnect() {
+    if (this.pollTimer === null) {
+      this.startPolling();
+    }
+    const delay = this.getRetryDelay();
+    this.emit("reconnecting", { attempt: this.sseRetryCount, delay });
+    this.sseRetryTimeout = setTimeout(() => {
+      this.sseRetryTimeout = null;
+      this.startSSE();
+    }, delay);
+  }
+  /**
+   * Start an SSE connection using fetch + ReadableStream.
+   * This allows us to send an Authorization header (unlike native EventSource).
+   * On failure, schedules a reconnection attempt with exponential backoff
+   * and uses polling as a fallback in the meantime.
+   */
+  async startSSE() {
+    const url = `${this.config.serverUrl}/api/v1/stream`;
+    this.sseAbortController = new AbortController();
+    const wasReconnecting = this.sseRetryCount > 0;
+    try {
+      const response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${this.config.sdkKey}`,
+          Accept: "text/event-stream"
+        },
+        signal: this.sseAbortController.signal
+      });
+      if (!response.ok || !response.body) {
+        this.scheduleSSEReconnect();
+        return;
+      }
+      if (wasReconnecting) {
+        this.emit("reconnected", void 0);
+      }
+      this.sseRetryCount = 0;
+      if (this.pollTimer !== null) {
+        clearInterval(this.pollTimer);
+        this.pollTimer = null;
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      this.processSSEStream(reader, decoder).then(
+        () => {
+          this.scheduleSSEReconnect();
+        },
+        () => {
+          this.scheduleSSEReconnect();
+        }
+      );
+    } catch {
+      this.scheduleSSEReconnect();
+    }
+  }
+  /**
+   * Read and parse SSE events from a ReadableStream.
+   * SSE format:
+   *   event: flag_update
+   *   data: {"flagKey":"dark-mode","value":true,"variant":"on"}
+   *
+   */
+  async processSSEStream(reader, decoder) {
+    let buffer = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+      for (const part of parts) {
+        this.handleSSEEvent(part);
+      }
+    }
+  }
+  /**
+   * Parse a single SSE event block and update flags accordingly.
+   */
+  handleSSEEvent(raw) {
+    let eventType = "";
+    let data = "";
+    for (const line of raw.split("\n")) {
+      if (line.startsWith("event:")) {
+        eventType = line.slice("event:".length).trim();
+      } else if (line.startsWith("data:")) {
+        data = line.slice("data:".length).trim();
+      }
+    }
+    if (!data) return;
+    if (eventType === "flag_deleted") {
+      try {
+        const event = JSON.parse(data);
+        this.flags.delete(event.flagKey);
+        this.emit("deleted", event);
+      } catch {
+      }
+      return;
+    }
+    if (eventType !== "flag_update") return;
+    try {
+      const event = JSON.parse(data);
+      const existing = this.flags.get(event.flagKey);
+      this.flags.set(event.flagKey, {
+        value: event.value,
+        variant: event.variant,
+        reason: existing?.reason ?? "stream_update"
+      });
+      this.emit("change", event);
+    } catch {
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: polling fallback
+  // ---------------------------------------------------------------------------
+  /**
+   * Start periodic polling as a fallback when SSE is unavailable.
+   */
+  startPolling() {
+    if (this.pollTimer !== null) return;
+    this.pollTimer = setInterval(() => {
+      this.fetchFlags().catch(() => {
+      });
+    }, this.config.pollingInterval);
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: event emission
+  // ---------------------------------------------------------------------------
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        listener(payload);
+      } catch {
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Togglerino
+});

package/dist/index.mjs

@@ -0,0 +1,365 @@
+// src/client.ts
+var Togglerino = class {
+  constructor(config) {
+    this.flags = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Map();
+    this.pollTimer = null;
+    this.sseAbortController = null;
+    this.initialized = false;
+    this.sseRetryCount = 0;
+    this.sseRetryTimeout = null;
+    this.maxRetryDelay = 3e4;
+    this.config = {
+      serverUrl: config.serverUrl.replace(/\/+$/, ""),
+      // strip trailing slash
+      sdkKey: config.sdkKey,
+      context: config.context ?? {},
+      streaming: config.streaming ?? true,
+      pollingInterval: config.pollingInterval ?? 3e4
+    };
+  }
+  /**
+   * Initialize the client: fetch all flags and start listening for updates.
+   * Must be called before reading any flag values.
+   */
+  async initialize() {
+    await this.fetchFlags();
+    this.initialized = true;
+    if (this.config.streaming) {
+      this.startSSE();
+    } else {
+      this.startPolling();
+    }
+    this.emit("ready", void 0);
+  }
+  // ---------------------------------------------------------------------------
+  // Typed flag getters (synchronous, read from local cache)
+  // ---------------------------------------------------------------------------
+  /**
+   * Get a boolean flag value.
+   * Returns `defaultValue` if the flag is not found or is not a boolean.
+   */
+  getBool(key, defaultValue = false) {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "boolean") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a string flag value.
+   * Returns `defaultValue` if the flag is not found or is not a string.
+   */
+  getString(key, defaultValue = "") {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "string") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a numeric flag value.
+   * Returns `defaultValue` if the flag is not found or is not a number.
+   */
+  getNumber(key, defaultValue = 0) {
+    const result = this.flags.get(key);
+    if (result === void 0 || typeof result.value !== "number") {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get a JSON flag value (object, array, etc.).
+   * Returns `defaultValue` if the flag is not found.
+   */
+  getJson(key, defaultValue) {
+    const result = this.flags.get(key);
+    if (result === void 0) {
+      return defaultValue;
+    }
+    return result.value;
+  }
+  /**
+   * Get the raw EvaluationResult for a flag.
+   * Returns undefined if the flag is not found.
+   */
+  getDetail(key) {
+    return this.flags.get(key);
+  }
+  // ---------------------------------------------------------------------------
+  // Event emitter
+  // ---------------------------------------------------------------------------
+  /**
+   * Subscribe to SDK events.
+   * Returns an unsubscribe function.
+   *
+   * Events:
+   * - "ready": no payload, fired after initialize() completes.
+   * - "change": payload is FlagChangeEvent.
+   * - "context_change": payload is EvaluationContext, fired after updateContext() completes.
+   * - "error": payload is Error.
+   * - "reconnecting": payload is { attempt: number, delay: number }, fired when scheduling SSE reconnect.
+   * - "reconnected": no payload, fired when SSE successfully reconnects after a disconnection.
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return () => {
+      this.listeners.get(event)?.delete(listener);
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Context management
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the current evaluation context.
+   */
+  getContext() {
+    return {
+      ...this.config.context,
+      attributes: this.config.context.attributes ? { ...this.config.context.attributes } : void 0
+    };
+  }
+  /**
+   * Update the evaluation context and re-fetch all flags.
+   * Useful when the user logs in / changes attributes.
+   */
+  async updateContext(context) {
+    this.config.context = {
+      ...this.config.context,
+      ...context
+    };
+    await this.fetchFlags();
+    this.emit("context_change", this.getContext());
+  }
+  // ---------------------------------------------------------------------------
+  // Cleanup
+  // ---------------------------------------------------------------------------
+  /**
+   * Stop all background activity (SSE stream, polling) and remove listeners.
+   * Call this when the client is no longer needed.
+   */
+  close() {
+    if (this.pollTimer !== null) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.sseAbortController) {
+      this.sseAbortController.abort();
+      this.sseAbortController = null;
+    }
+    if (this.sseRetryTimeout) {
+      clearTimeout(this.sseRetryTimeout);
+      this.sseRetryTimeout = null;
+    }
+    this.sseRetryCount = 0;
+    this.listeners.clear();
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: flag fetching
+  // ---------------------------------------------------------------------------
+  /**
+   * Fetch all flags from the server evaluation endpoint.
+   */
+  async fetchFlags() {
+    const url = `${this.config.serverUrl}/api/v1/evaluate`;
+    const body = {
+      context: {
+        user_id: this.config.context.userId ?? "",
+        attributes: this.config.context.attributes ?? {}
+      }
+    };
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.sdkKey}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Togglerino: flag evaluation failed with status ${response.status}`
+        );
+      }
+      const data = await response.json();
+      const oldFlags = new Map(this.flags);
+      this.flags.clear();
+      for (const [key, result] of Object.entries(data.flags)) {
+        this.flags.set(key, result);
+        if (this.initialized) {
+          const old = oldFlags.get(key);
+          if (!old || JSON.stringify(old.value) !== JSON.stringify(result.value)) {
+            this.emit("change", {
+              flagKey: key,
+              value: result.value,
+              variant: result.variant
+            });
+          }
+        }
+      }
+    } catch (error) {
+      this.emit("error", error);
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: SSE streaming (fetch-based with ReadableStream)
+  // ---------------------------------------------------------------------------
+  /**
+   * Calculate the next retry delay using exponential backoff.
+   * Sequence: 1s, 2s, 4s, 8s, 16s, 30s (capped).
+   */
+  getRetryDelay() {
+    const delay = Math.min(1e3 * Math.pow(2, this.sseRetryCount), this.maxRetryDelay);
+    this.sseRetryCount++;
+    return delay;
+  }
+  /**
+   * Schedule an SSE reconnection attempt with exponential backoff.
+   * Starts polling as a fallback while retrying.
+   */
+  scheduleSSEReconnect() {
+    if (this.pollTimer === null) {
+      this.startPolling();
+    }
+    const delay = this.getRetryDelay();
+    this.emit("reconnecting", { attempt: this.sseRetryCount, delay });
+    this.sseRetryTimeout = setTimeout(() => {
+      this.sseRetryTimeout = null;
+      this.startSSE();
+    }, delay);
+  }
+  /**
+   * Start an SSE connection using fetch + ReadableStream.
+   * This allows us to send an Authorization header (unlike native EventSource).
+   * On failure, schedules a reconnection attempt with exponential backoff
+   * and uses polling as a fallback in the meantime.
+   */
+  async startSSE() {
+    const url = `${this.config.serverUrl}/api/v1/stream`;
+    this.sseAbortController = new AbortController();
+    const wasReconnecting = this.sseRetryCount > 0;
+    try {
+      const response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${this.config.sdkKey}`,
+          Accept: "text/event-stream"
+        },
+        signal: this.sseAbortController.signal
+      });
+      if (!response.ok || !response.body) {
+        this.scheduleSSEReconnect();
+        return;
+      }
+      if (wasReconnecting) {
+        this.emit("reconnected", void 0);
+      }
+      this.sseRetryCount = 0;
+      if (this.pollTimer !== null) {
+        clearInterval(this.pollTimer);
+        this.pollTimer = null;
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      this.processSSEStream(reader, decoder).then(
+        () => {
+          this.scheduleSSEReconnect();
+        },
+        () => {
+          this.scheduleSSEReconnect();
+        }
+      );
+    } catch {
+      this.scheduleSSEReconnect();
+    }
+  }
+  /**
+   * Read and parse SSE events from a ReadableStream.
+   * SSE format:
+   *   event: flag_update
+   *   data: {"flagKey":"dark-mode","value":true,"variant":"on"}
+   *
+   */
+  async processSSEStream(reader, decoder) {
+    let buffer = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+      for (const part of parts) {
+        this.handleSSEEvent(part);
+      }
+    }
+  }
+  /**
+   * Parse a single SSE event block and update flags accordingly.
+   */
+  handleSSEEvent(raw) {
+    let eventType = "";
+    let data = "";
+    for (const line of raw.split("\n")) {
+      if (line.startsWith("event:")) {
+        eventType = line.slice("event:".length).trim();
+      } else if (line.startsWith("data:")) {
+        data = line.slice("data:".length).trim();
+      }
+    }
+    if (!data) return;
+    if (eventType === "flag_deleted") {
+      try {
+        const event = JSON.parse(data);
+        this.flags.delete(event.flagKey);
+        this.emit("deleted", event);
+      } catch {
+      }
+      return;
+    }
+    if (eventType !== "flag_update") return;
+    try {
+      const event = JSON.parse(data);
+      const existing = this.flags.get(event.flagKey);
+      this.flags.set(event.flagKey, {
+        value: event.value,
+        variant: event.variant,
+        reason: existing?.reason ?? "stream_update"
+      });
+      this.emit("change", event);
+    } catch {
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: polling fallback
+  // ---------------------------------------------------------------------------
+  /**
+   * Start periodic polling as a fallback when SSE is unavailable.
+   */
+  startPolling() {
+    if (this.pollTimer !== null) return;
+    this.pollTimer = setInterval(() => {
+      this.fetchFlags().catch(() => {
+      });
+    }, this.config.pollingInterval);
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: event emission
+  // ---------------------------------------------------------------------------
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        listener(payload);
+      } catch {
+      }
+    }
+  }
+};
+export {
+  Togglerino
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@togglerino/sdk",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for togglerino feature flags",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "feature-flags",
+    "togglerino",
+    "sdk"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}