flagmint-js-sdk 1.2.25 → 2.0.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { FlagClient } from './sdk/core/client';
 export type { FlagClientOptions } from './sdk/core/client';
 export type { CacheAdapter, FeatureFlags } from './sdk/core/helpers/types';
+export type { ApplicationEvent, ApplicationEventKind } from './sdk/core/helpers/applicationEvents';
 export * as syncCache from './sdk/core/helpers/cacheHelper';
 export * as asyncCache from './sdk/core/helpers/cacheHelper.async';
 export type { Transport } from './sdk/core/transports/Transport';
 export { LongPollingTransport } from './sdk/core/transports/LongPollingTransport';
-export { WebSocketTransport } from './sdk/core/transports/WebsocketTransport';
+export { SseTransport } from './sdk/core/transports/SSETransport';
 export type { FlagValue, EvaluationContext, Segment, Rollout, VariantRollout, VariantOption } from './sdk/core/evaluation/types';
 export { evaluateFlagValue } from './sdk/core/evaluation/evaluateFlagValue';
 export { evaluateRollout } from './sdk/core/evaluation/evaluateRollout';

package/dist/sdk/core/client.d.ts

@@ -1,7 +1,8 @@
 import { CacheAdapter, FeatureFlags } from '../core/helpers/types';
 import type { Transport } from '../core/transports/Transport';
 import { FlagValue } from '../core/evaluation/types';
-type TransportMode = 'auto' | 'websocket' | 'long-polling';
+import { type ConnectionShareOptions } from '../core/helpers/connectionShare';
+type TransportMode = 'auto' | 'long-polling' | 'sse';
 export interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
     apiKey: string;
     context?: C;
@@ -28,10 +29,33 @@ export interface FlagClientOptions<C extends Record<string, any> = Record<string
     deferInitialization?: boolean;
     cacheAdapter?: CacheAdapter<C>;
     restEndpoint?: string;
-    wsEndpoint?: string;
+    sseEndpoint?: string;
+    /** Override the ASL handshake URL. Use with `sseEndpoint` for self-hosted gateways. */
+    handshakeEndpoint?: string;
     debugLog?: boolean;
     env?: string;
     enableFlagmint: boolean;
+    wrapperInfo?: {
+        name: string;
+        version: string;
+    };
+    EventSourceImpl?: any;
+    /**
+     * Share one streaming connection across same-origin documents (tabs / iframes)
+     * that use the same API key. Defaults to true in browsers with BroadcastChannel,
+     * false in Node (cluster workers each keep their own stream).
+     *
+     * Followers do not handshake or open EventSource. They receive flags from the
+     * leader and forward updateContext() to it. Do not enable this when two clients
+     * must evaluate different contexts at the same time on one page, or when the
+     * origin hosts untrusted documents that should not steer or read this stream.
+     */
+    shareConnection?: boolean;
+    /**
+     * Test/runtime hooks for the share hub (channel, storage, timers).
+     * Omit in production.
+     */
+    share?: ConnectionShareOptions;
 }
 type FlagUpdateCallback<T> = (flags: FeatureFlags<T>) => void;
 export declare class FlagClient<T = unknown, C extends Record<string, any> = Record<string, any>> {
@@ -44,7 +68,13 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private cacheTTL;
     private transport;
     private restEndpoint;
-    private wsEndpoint;
+    private eventsEndpoint;
+    private aslHandshakeUrl;
+    private sseEndpoint;
+    private eventQueue;
+    private eventFlushTimer;
+    /** null = server has not sent a map yet; send and let ingest drop. */
+    private analyticsByFlag;
     private readyPromise;
     private resolveReady;
     private rejectReady;
@@ -58,6 +88,8 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
     private initializationOptions?;
     private isInitialized;
     private subscribers;
+    private shareHub;
+    private shareConnection;
     /**
      * Creates a new FlagClient instance.
      * @param options - Configuration options for the client.
@@ -67,9 +99,40 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * Initializes the client by loading cached flags and context, setting up the transport layer.
      */
     private initialize;
+    private bindTransport;
     /**
-     * Sets up the transport layer for the client.
+     * @returns true when this document is a follower and should skip opening a stream.
      */
+    private joinConnectionShare;
+    private attachShareLeader;
+    /**
+   * Creates and initializes the transport layer used to receive feature flags
+   * updates from the Flagmint platform.
+   *
+   * This method performs the authentication handshake to obtain a fresh session
+   * identifier, selects the appropriate transport based on the configured
+   * transport mode, and initializes it before attaching the internal flag update
+   * listener.
+   *
+   * When operating in `auto` mode, the client attempts to establish a
+   * Server-Sent Events (SSE) connection first. If SSE initialization fails,
+   * it automatically falls back to the long-polling transport to maintain
+   * feature flag delivery.
+   *
+   * Once the transport is ready, any available initial flags are immediately
+   * synchronized into the client state before future updates are received
+   * through the transport's notification callbacks.
+   *
+   * @param {FlagClientOptions<C>} options - The client configuration used to
+   * authenticate the handshake request and determine which transport strategy
+   * to initialize.
+   *
+   * @returns {Promise<void>} A promise that resolves once the selected transport
+   * has been initialized and wired into the FlagClient.
+   *
+   * @throws {Error} If the authentication handshake fails, the session identifier
+   * cannot be obtained, or the configured transport fails to initialize.
+   */
     private setupTransport;
     /**
      * Updates flags and notifies all subscribers.
@@ -94,6 +157,23 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      * Get a single flag value.
      */
     getFlag<K extends keyof FeatureFlags<T>>(key: K, fallback?: FeatureFlags<T>[K]): FeatureFlags<T>[K];
+    /**
+     * Report an application error that happened after this flag was served.
+     * Fire-and-forget: events are batched and never throw.
+     * No-ops when Analytics Tracking is off for that flag.
+     */
+    trackError(flagKey: string, error?: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Report a custom metric event attributed to the currently served variation.
+     * Fire-and-forget: events are batched and never throw.
+     * No-ops when Analytics Tracking is off for that flag.
+     */
+    track(flagKey: string, eventName: string, extra?: Record<string, unknown>): void;
+    /**
+     * Whether Analytics Tracking is on for this flag in the last streamed payload.
+     * `undefined` means the server has not sent a map yet (older API / long-polling).
+     */
+    isAnalyticsEnabled(flagKey: string): boolean | undefined;
     /**
      * Update the evaluation context.
      */
@@ -103,15 +183,75 @@ export declare class FlagClient<T = unknown, C extends Record<string, any> = Rec
      */
     destroy(): void;
     /**
-     * Wait for the client to be ready.
-     * Resolves when: flags are available AND initialization succeeded.
-     * Rejects if: initialization/connection fails (even if cached flags exist).
-     */
+   * Waits until the FlagClient is fully initialized and ready for feature flag
+   * evaluation.
+   *
+   * If deferred initialization is enabled, this method will first perform the
+   * initial client setup. It then waits for the first feature flag payload to
+   * become available (or until the specified timeout expires) before awaiting
+   * completion of the underlying transport initialization.
+   *
+   * This method guarantees that transport or connection failures are surfaced,
+   * even when feature flags have already been restored from cache.
+   *
+   * @param {number} [timeoutMs=3000] - The maximum amount of time, in
+   * milliseconds, to wait for the initial feature flag payload before
+   * continuing initialization.
+   *
+   * @returns {Promise<void>} A promise that resolves when the client is fully
+   * initialized and ready to evaluate feature flags.
+   *
+   * @throws {Error} If client initialization or the underlying transport fails,
+   * such as authentication, rate limiting, or connection errors.
+   */
     ready(timeoutMs?: number): Promise<void>;
     /**
      * Evaluate flags locally (for preview mode).
      */
     private evaluateLocally;
+    /**
+   * Waits until the client receives its first non-empty feature flag payload,
+   * or until the specified timeout elapses.
+   *
+   * This method subscribes to flag updates and resolves as soon as at least one
+   * feature flag is available. If no flags are received within the allotted
+   * timeout, the promise still resolves, allowing the SDK to continue
+   * initialization using default or cached values instead of blocking
+   * indefinitely.
+   *
+   * The internal subscription is automatically removed when either condition
+   * is met to prevent memory leaks.
+   *
+   * @param {number} timeoutMs - The maximum amount of time, in milliseconds,
+   * to wait for the initial feature flag payload before resolving.
+   *
+   * @returns {Promise<void>} A promise that resolves when the first non-empty
+   * flag payload is received or when the timeout expires, whichever occurs first.
+   */
     private waitForFlags;
+    private updateAnalytics;
+    private queueApplicationEvent;
+    private flushApplicationEvents;
+    /**
+     * Performs the initial authentication handshake with the Flagmint server
+     * to obtain a fresh, single-use session identifier.
+     *
+     * The returned session ID is used by streaming transports (SSE/WebSocket)
+     * to establish an authenticated real-time connection. Session identifiers
+     * are intentionally short-lived and should not be reused across new
+     * streaming connections.
+     *
+     * @param {string} apiKey - The Flagmint API key used to authenticate the
+     * handshake request.
+     *
+     * @returns {Promise<string>} A promise that resolves with a newly issued
+     * session identifier.
+     *
+     * @throws {Error} If the API credentials are invalid (`ERR_AUTH`).
+     * @throws {Error} If the client has exceeded its rate limit (`ERR_RATE_LIMITED`).
+     * @throws {Error} If the handshake endpoint returns an unexpected HTTP error.
+     * @throws {Error} If the handshake response does not contain a valid session ID.
+     */
+    private fetchFreshSessionId;
 }
 export {};

package/dist/sdk/core/helpers/applicationEvents.d.ts

@@ -0,0 +1,20 @@
+export declare const MAX_EVENT_BATCH = 20;
+export declare const EVENT_FLUSH_MS = 2000;
+export type ApplicationEventKind = 'error' | 'custom';
+export interface ApplicationEvent {
+    flagKey: string;
+    kind: ApplicationEventKind;
+    eventName?: string;
+    variationValue?: unknown;
+    userKey?: string;
+    timestamp: string;
+    extra?: Record<string, unknown>;
+}
+export declare function eventsUrlFromRestEndpoint(restEndpoint: string): string;
+export declare function userKeyFromContext(context: Record<string, unknown> | undefined): string | undefined;
+export declare function extraFromError(error: unknown, extra?: Record<string, unknown>): Record<string, unknown> | undefined;
+/**
+ * When the server has sent an analytics map, only flags with analytics on
+ * are reported. A null map means an older server — send and let ingest drop.
+ */
+export declare function shouldReportApplicationEvent(analyticsByFlag: Record<string, boolean> | null, flagKey: string): boolean;

package/dist/sdk/core/helpers/connectionShare.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Same-origin connection sharing for Flagmint streaming transports.
+ *
+ * When two or more FlagClient instances run in the same origin — typical cases
+ * are a host page plus sibling iframes, or two widgets on one Python-embedded
+ * page — each would otherwise open its own ASL handshake and SSE/long-poll
+ * stream. That doubles evaluation quota and is almost never intended.
+ *
+ * This hub elects a single **leader** per API key:
+ *
+ * - **Leader** holds the real transport (handshake + EventSource). It broadcasts
+ *   flag snapshots and errors over {@link BroadcastChannel}.
+ * - **Followers** skip handshake and EventSource. They apply the leader's flags
+ *   and forward `updateContext()` to the leader, which runs it on the shared
+ *   stream.
+ *
+ * Leadership is stored in `localStorage` (`flagmint_share_lock:<apiKey>`) with a
+ * short TTL and heartbeat. `destroy()` and a `pagehide` / `beforeunload` listener
+ * post `bye` and release the lock so another member can take over immediately.
+ * If the document is killed without those events, followers wait until the lock
+ * TTL expires.
+ *
+ * Sharing is a **browser** feature. Node cluster workers each need their own
+ * stream — {@link isConnectionSharingAvailable} is false there. Do not share
+ * when two clients on one page must keep different evaluation contexts at the
+ * same time; `/context` is per connection, so the last write wins.
+ *
+ * Trust: `BroadcastChannel` and `localStorage` are same-origin. Any document
+ * on this origin (including a third-party iframe you host there) can join the
+ * group, POST a context through the leader's authenticated stream, and read
+ * the flags broadcast back. That is expected among trusted siblings. If the
+ * origin serves untrusted content, set `shareConnection: false`.
+ *
+ * @module connectionShare
+ */
+import type { Transport } from '../../core/transports/Transport';
+/** Role this document plays in the share group for a given API key. */
+export type ShareRole = 'leader' | 'follower';
+/**
+ * Persistence used for the leadership lock.
+ * Defaults to `localStorage` so sibling iframes on the same origin can compete.
+ */
+export interface ShareStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Cross-document bus. Production uses {@link BroadcastChannel};
+ * tests inject an in-memory implementation.
+ */
+export interface ShareChannel {
+    postMessage(data: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+/**
+ * Test/runtime hooks. Omit in production — the hub uses `BroadcastChannel`,
+ * `localStorage`, and `setInterval`.
+ */
+export interface ConnectionShareOptions {
+    /** Override `new BroadcastChannel(name)` (tests). */
+    channelFactory?: (name: string) => ShareChannel;
+    /** Override `localStorage` for the leadership lock (tests). */
+    storage?: ShareStorage;
+    /** Clock used for lock expiry. */
+    now?: () => number;
+    setTimer?: (handler: () => void, ms: number) => ReturnType<typeof setInterval>;
+    clearTimer?: (id: ReturnType<typeof setInterval>) => void;
+    /** Delay used to stagger lock confirmation (tests inject a no-op). */
+    delay?: (ms: number) => Promise<void>;
+}
+/**
+ * Whether this runtime can share a stream across documents.
+ *
+ * @returns `true` in a browser with {@link BroadcastChannel} (includes same-origin
+ * iframes). `false` in Node, so cluster workers each keep their own connection.
+ */
+export declare function isConnectionSharingAvailable(): boolean;
+/**
+ * Elects a single streaming leader per API key across same-origin documents.
+ *
+ * {@link FlagClient} constructs one hub when `shareConnection` is enabled (the
+ * browser default). The leader opens SSE; followers use
+ * {@link ConnectionShareHub.createFollowerTransport} instead.
+ *
+ * @template C Evaluation context forwarded from follower `updateContext` calls.
+ * @template T Flag value type in snapshots broadcast by the leader.
+ */
+export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown> {
+    private readonly apiKey;
+    /** Stable id for this document in channel messages and the lock record. */
+    readonly memberId: string;
+    private role;
+    private channel;
+    private heartbeatId;
+    private watchId;
+    private closed;
+    private latestFlags;
+    private flagsWaiters;
+    private contextWaiters;
+    private onPromoteCallback?;
+    private leaderContextHandler?;
+    private followerFlagsCallback?;
+    private followerErrorCallback?;
+    private readonly now;
+    private readonly storage;
+    private readonly channelFactory?;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly delay;
+    private unloadHandler?;
+    private readonly lockKey;
+    private readonly channelName;
+    /**
+     * @param apiKey Share groups are keyed by API key. Distinct keys never share.
+     * @param options Optional test doubles for channel, storage, and timers.
+     */
+    constructor(apiKey: string, options?: ConnectionShareOptions);
+    /** `leader` if this document holds the lock; otherwise `follower`. */
+    get currentRole(): ShareRole;
+    /**
+     * Join the share group: compete for the lock, subscribe to the channel.
+     *
+     * If {@link BroadcastChannel} is missing, this member becomes leader locally
+     * and never shares (same as a Node process).
+     *
+     * @returns The role this member should take. Only the leader should call
+     * ASL handshake / `SseTransport.init()`.
+     */
+    join(): Promise<ShareRole>;
+    /**
+     * Invoked after a follower wins the lock (leader `bye` or expired heartbeat).
+     * The client should open a real transport here, then
+     * {@link ConnectionShareHub.broadcastFlags}.
+     */
+    onPromote(callback: () => void | Promise<void>): void;
+    /**
+     * Leader-only: run `updateContext` on the real transport when a follower
+     * sends `context-request`. The context is whatever that same-origin
+     * document posted; the leader does not authenticate the sender beyond origin.
+     */
+    setLeaderContextHandler(handler: (context: C, options?: {
+        persist?: boolean;
+    }) => Promise<Record<string, T>>): void;
+    /**
+     * Leader-only: publish the current evaluated flags to all followers.
+     * No-op on followers (avoids echo loops).
+     */
+    broadcastFlags(flags: Record<string, T>): void;
+    /** Leader-only: mirror a transport `onError` (auth, quota) to followers. */
+    broadcastError(error: Error): void;
+    /**
+     * Transport used by follower FlagClients. `init` waits for the leader
+     * snapshot; `fetchFlags` RPCs `updateContext` through the leader.
+     * `destroy` is a no-op — {@link ConnectionShareHub.destroy} owns teardown.
+     */
+    createFollowerTransport(): Transport<C, T>;
+    /**
+     * Leave the share group. Leaders release the lock and post `bye` so another
+     * iframe can open the stream. Also invoked from `pagehide` / `beforeunload`.
+     * Channel close is deferred one tick so `bye` can flush on native
+     * {@link BroadcastChannel}.
+     */
+    destroy(): void;
+    private bindUnloadListener;
+    private unbindUnloadListener;
+    /** Open the BroadcastChannel for this API key, or a test factory channel. */
+    private openChannel;
+    /** Mark this member leader and start lock heartbeat + `alive` pings. */
+    private becomeLeader;
+    /**
+     * Follower poll: if the lock is free or expired, take it and run
+     * {@link ConnectionShareHub.onPromote}.
+     */
+    private maybeTakeover;
+    /** Dispatch a {@link ShareMessage} from another document in the group. */
+    private handleMessage;
+    /**
+     * Leader: evaluate a follower's context on the real transport and reply.
+     * Any same-origin document can trigger this; the resulting flags are
+     * broadcast to the whole group.
+     */
+    private handleContextRequest;
+    /**
+     * Block until the leader has sent a `flags` snapshot, or {@link FOLLOWER_WAIT_MS}.
+     * Used by follower `init()`.
+     */
+    private waitForFlags;
+    /**
+     * Follower `fetchFlags`: ask the leader to POST `/context` and wait for
+     * `context-result`. Leaders run the handler locally.
+     *
+     * The posted context is not origin-isolated beyond BroadcastChannel itself.
+     * Untrusted same-origin frames must not share a connection with a trusted
+     * leader — set `shareConnection: false` on those clients.
+     */
+    private requestContextUpdate;
+    /** Read the leadership lock, or `null` if missing/corrupt. */
+    private readLock;
+    /**
+     * Write the lock, wait so a competing write can land, then re-read.
+     * localStorage has no compare-and-set; the delay plus confirm is the
+     * best we can do so two iframes do not both become leader.
+     *
+     * @returns `true` if this member still owns the lock after the confirm.
+     */
+    private tryAcquireLock;
+    /** Extend lock expiry; no-op if another member stole the lock. */
+    private refreshLock;
+    /** Drop the lock only if this member still owns it. */
+    private releaseLock;
+}

package/dist/sdk/core/transports/LongPollingTransport.d.ts

@@ -13,6 +13,7 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private backoffMultiplier;
     private pollTimeoutId;
     private onUpdateCallback?;
+    private onAnalyticsUpdatedCallback?;
     private currentContext;
     private currentFlags;
     private consecutiveErrors;
@@ -23,7 +24,10 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private poll;
     private applyBackoff;
     private flagsChanged;
-    fetchFlags(context: C): Promise<Record<string, T>>;
+    fetchFlags(context: C, options?: {
+        persist?: boolean;
+    }): Promise<Record<string, T>>;
     onFlagsUpdated(callback: (flags: Record<string, T>) => void): void;
+    onAnalyticsUpdated(callback: (analytics: Record<string, boolean>) => void): void;
     destroy(): void;
 }

package/dist/sdk/core/transports/SSETransport.d.ts

@@ -0,0 +1,90 @@
+import type { Transport } from './Transport';
+export interface SseTransportConfig {
+    endpoint: string;
+    apiKey: string;
+    context: any;
+    wrapper?: {
+        name: string;
+        version: string;
+    };
+    EventSourceImpl?: any;
+}
+/**
+ * A Server-Sent Events (SSE) transport implementation responsible for
+ * maintaining a persistent streaming connection to the Flagmint platform.
+ *
+ * Handshake: `POST /auth/asl-handshake` issues a single-use sessionId.
+ * Stream: `GET {endpoint}/stream?sessionId&context&sdkVersion&platform&wrapper*`
+ *   emits `connected` then `flags`. Heartbeats are SSE comments (`: heartbeat`)
+ *   and are not visible to EventSource — they only keep the TCP connection alive.
+ * Context: `POST {endpoint}/context` with `x-api-key` returns 202 and the
+ *   re-evaluated flags arrive on the existing stream after a 400ms debounce.
+ *
+ * @template C The shape of the evaluation context sent to the Flagmint server.
+ * @template T The feature flag value type returned by the platform.
+ *
+ * @implements {Transport<C, T>}
+ */
+export declare class SseTransport<C, T> implements Transport<C, T> {
+    private endpoint;
+    private sessionId;
+    private refreshTokenCallback?;
+    private configOptions?;
+    private eventSource;
+    private flags;
+    private context;
+    private connectionId;
+    private onFlagsUpdatedCallback?;
+    private onAnalyticsUpdatedCallback?;
+    private onErrorCallback?;
+    private initialFlagsReceived;
+    private initialFlagsResolve;
+    private initialFlagsReject;
+    private nextFlagsResolve;
+    private connectPromise;
+    private connectResolve;
+    private connectReject;
+    private connectionListener?;
+    private flagsListener?;
+    private quotaListener?;
+    private errorListener?;
+    private reconnectTimeoutId;
+    private reconnectAttempts;
+    private terminalClose;
+    private contextUpdateQueue;
+    constructor(endpoint: string, sessionId: string, initialContext: C, refreshTokenCallback?: (() => Promise<string>) | undefined, configOptions?: Partial<SseTransportConfig> | undefined);
+    init(): Promise<void>;
+    /**
+     * POST /v2/flags/context. FF-EU always returns 202 and pushes the next
+     * `flags` event on the open SSE stream (after a 400ms debounce). The HTTP
+     * body does not contain evaluated flags — browser and Node share this path.
+     */
+    fetchFlags(context: C, options?: {
+        persist?: boolean;
+    }): Promise<Record<string, T>>;
+    onFlagsUpdated(callback: (flags: Record<string, T>) => void): void;
+    onAnalyticsUpdated(callback: (analytics: Record<string, boolean>) => void): void;
+    onError(callback: (error: Error) => void): void;
+    destroy(): void;
+    private get apiKey();
+    private applyFlags;
+    private emitError;
+    private performContextUpdate;
+    private safeReadJson;
+    private quotaExtra;
+    private handleQuotaPayload;
+    private cleanupEventSource;
+    private resolveEventSourceImpl;
+    private connect;
+    private scheduleActiveReconnection;
+    private createConnectionListener;
+    private createFlagsListener;
+    private createQuotaListener;
+    /**
+     * Named `error` events from FF-EU (`event: error`) after the stream is hijacked.
+     * Distinct from EventSource.onerror, which fires on network/connection failure.
+     */
+    private createStreamErrorListener;
+    private mapStreamErrorCode;
+    private resetInitialResolvers;
+}

package/dist/sdk/core/transports/Transport.d.ts

@@ -1,7 +1,11 @@
 export interface Transport<C, T> {
     init(onUpdate?: (flags: Record<string, T>) => void): Promise<void>;
-    fetchFlags(context: C): Promise<Record<string, T>>;
+    fetchFlags(context: C, options?: {
+        persist?: boolean;
+    }): Promise<Record<string, T>>;
     destroy(): void;
     onFlagsUpdated?: (callback: (flags: Record<string, T>) => void) => void;
+    onAnalyticsUpdated?: (callback: (analytics: Record<string, boolean>) => void) => void;
     onContextUpdated?: (callback: (context: C) => void) => void;
+    onError?: (callback: (error: Error) => void) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagmint-js-sdk",
-  "version": "1.2.25",
+  "version": "2.0.0",
   "description": "Framework-agnostic JavaScript SDK for managing feature flags in Flagmint applications.",
   "author": "Flagmint Team",
   "license": "BSD 3-Clause",
@@ -22,7 +22,10 @@
   "scripts": {
     "clean": "rimraf dist",
     "build": "npm run clean && vite build",
-    "test": "jest --runInBand --detectOpenHandles"
+    "test": "jest --runInBand --detectOpenHandles",
+    "simulate:unreachable": "npm run build && node ./scripts/simulate-unreachable-server.js",
+    "simulate:cache-fallback": "npm run build && node ./scripts/simulate-cache-adapter-fallback.js",
+    "simulate:asl-gen": "npm run build && node ./scripts/test-asl-handshake.mjs"
   },
   "peerDependencies": {
     "crypto": "*"
@@ -42,7 +45,11 @@
     "vite-plugin-dts": "^2.0.0"
   },
   "dependencies": {
-    "buffer": "^6.0.3"
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "buffer": "^6.0.3",
+    "node-fetch": "^3.3.2"
   },
   "optionalDependencies": {
     "ws": "^8.0.0"

package/dist/sdk/core/transports/WebsocketTransport.d.ts

@@ -1,33 +0,0 @@
-import type { Transport } from './Transport';
-type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed';
-export declare class WebSocketTransport<C, T> implements Transport<C, T> {
-    private wsUrl;
-    private apiKey;
-    private maxRetries;
-    private initialBackoffMs;
-    private socket;
-    private flags;
-    private context;
-    private isReady;
-    private initialFlagsReceived;
-    private initialFlagsPromise;
-    private initialFlagsResolve;
-    private initialFlagsReject;
-    private onFlagsUpdatedCallback?;
-    private onConnectionStateCallback?;
-    private retries;
-    private reconnectTimeoutId;
-    constructor(wsUrl: string, apiKey: string, maxRetries?: number, initialBackoffMs?: number);
-    init(): Promise<void>;
-    private waitForInitialFlags;
-    private connectWithRetry;
-    private cleanupSocket;
-    private setConnectionState;
-    private getWebSocketImplementation;
-    fetchFlags(context: C): Promise<Record<string, T>>;
-    onFlagsUpdated(callback: (flags: Record<string, T>) => void): void;
-    onConnectionStateChanged(callback: (state: ConnectionState) => void): void;
-    destroy(): void;
-    private sendContext;
-}
-export {};