flagmint-js-sdk 2.0.0 → 2.2.0

package/dist/sdk/core/config-sync/signPayload.d.ts

@@ -0,0 +1,17 @@
+import type { SignableConfigBody } from './types';
+/**
+ * Stable JSON for HMAC: sort object keys recursively so field order cannot
+ * invalidate signatures across language runtimes.
+ * Must match FF-EU `canonicalizeForSigning`.
+ */
+export declare function canonicalizeForSigning(value: unknown): string;
+/**
+ * HMAC-SHA256 hex digest over the payload with `signature` omitted.
+ */
+export declare function signConfigPayload(body: SignableConfigBody, secret: Uint8Array | string): string;
+/**
+ * Verify HMAC-SHA256 hex `signature` on a config-sync payload.
+ * Prefer the ASL ECDH-derived session MAC key.
+ */
+export declare function verifyConfigPayloadSignature(body: SignableConfigBody, secret: Uint8Array | string): boolean;
+export declare function isConfigPayloadExpired(expiresAt: number, now?: number): boolean;

package/dist/sdk/core/config-sync/stringHash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * djb2 variant matching npm `string-hash` (and Go `evaluate.StringHash`).
+ * Iterates right-to-left with XOR — required for rollout bucket parity.
+ */
+export declare function stringHash(input: string): number;
+/** Stable bucket in [0, 99] for percentage / variant rollouts. */
+export declare function hashPercent(input: string): number;

package/dist/sdk/core/config-sync/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Wire types for SSE config-sync (aligned with FF-EU `modules/evaluator/config-sync.ts`).
+ */
+export type SdkFlagConfig = {
+    key: string;
+    type: 'boolean' | 'string' | 'number' | 'json';
+    is_active: boolean;
+    default_value: unknown;
+    off_variation_id?: string | null;
+    targeting_rules: unknown[];
+    variations: Array<{
+        id: string;
+        value: unknown;
+        key?: string;
+        name?: string;
+    }>;
+    rollouts: Record<string, unknown>;
+    analytics_enabled: boolean;
+};
+export type SdkSegment = {
+    id: string;
+    rules: unknown[];
+    logical_op?: string;
+    force?: boolean;
+};
+export type SignableConfigBody = Record<string, unknown> & {
+    signature?: string;
+};
+export type LeasePayload = {
+    type: 'lease';
+    version: number;
+    serverNow: number;
+    expiresAt: number;
+    signature: string;
+};
+export type FullConfigPayload = {
+    type: 'fullConfig';
+    version: number;
+    compiledAt: number;
+    expiresAt: number;
+    flags: SdkFlagConfig[];
+    segments: Record<string, SdkSegment>;
+    warnings?: string[];
+    signature: string;
+};
+export type DeltaConfigPayload = {
+    type: 'delta';
+    fromVersion: number;
+    toVersion: number;
+    compiledAt: number;
+    expiresAt: number;
+    upserts: SdkFlagConfig[];
+    deletes: string[];
+    segments: Record<string, SdkSegment>;
+    signature: string;
+};
+export type DeltasCatchUpPayload = {
+    type: 'deltas';
+    fromVersion: number;
+    toVersion: number;
+    expiresAt: number;
+    items: DeltaConfigPayload[];
+    signature: string;
+};
+export type ConfigSyncPayload = LeasePayload | FullConfigPayload | DeltaConfigPayload | DeltasCatchUpPayload;
+/** Persisted cache for reconnect (`fullConfig` vs `sinceVersion`). */
+export type RulesCacheSnapshot = {
+    version: number;
+    expiresAt: number;
+    flags: SdkFlagConfig[];
+    segments: Record<string, SdkSegment>;
+};

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

@@ -11,6 +11,13 @@ export interface ApplicationEvent {
     extra?: Record<string, unknown>;
 }
 export declare function eventsUrlFromRestEndpoint(restEndpoint: string): string;
+/**
+ * API base for `POST …/context` (and similar) from the REST evaluate URL.
+ * Stream hosts may be SSE-only (`STREAM_HOSTS`); context must stay on the API host.
+ *
+ * `https://api…/evaluator/evaluate` → `https://api…/evaluator/v2/flags`
+ */
+export declare function flagsBaseFromRestEndpoint(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;
 /**

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

@@ -100,6 +100,7 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     private closed;
     private latestFlags;
     private flagsWaiters;
+    private flagsTimeouts;
     private contextWaiters;
     private onPromoteCallback?;
     private leaderContextHandler?;
@@ -167,6 +168,12 @@ export declare class ConnectionShareHub<C = Record<string, unknown>, T = unknown
     destroy(): void;
     private bindUnloadListener;
     private unbindUnloadListener;
+    /**
+     * JSON-clone then post. Native `BroadcastChannel` structured-clones the
+     * payload; Vue reactive Proxies and similar host objects throw
+     * `DataCloneError`. JSON.stringify can walk those Proxies.
+     */
+    private post;
     /** Open the BroadcastChannel for this API key, or a test factory channel. */
     private openChannel;
     /** Mark this member leader and start lock heartbeat + `alive` pings. */

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

@@ -0,0 +1,2 @@
+export declare const ERR_CONTEXT_NOT_CLONEABLE = "ERR_CONTEXT_NOT_CLONEABLE";
+export declare function toJsonCloneable<T>(value: T): T;

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

@@ -13,7 +13,6 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private backoffMultiplier;
     private pollTimeoutId;
     private onUpdateCallback?;
-    private onAnalyticsUpdatedCallback?;
     private currentContext;
     private currentFlags;
     private consecutiveErrors;
@@ -24,10 +23,7 @@ export declare class LongPollingTransport<C, T> implements Transport<C, T> {
     private poll;
     private applyBackoff;
     private flagsChanged;
-    fetchFlags(context: C, options?: {
-        persist?: boolean;
-    }): Promise<Record<string, T>>;
+    fetchFlags(context: C): 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

@@ -1,5 +1,5 @@
 import type { Transport } from './Transport';
-export interface SseTransportConfig {
+export interface SseTransportConfig<C = unknown, T = unknown> {
     endpoint: string;
     apiKey: string;
     context: any;
@@ -8,6 +8,37 @@ export interface SseTransportConfig {
         version: string;
     };
     EventSourceImpl?: any;
+    /**
+     * When true, stream uses config-sync (`fullConfig` / `sinceVersion`) and
+     * listens for lease / fullConfig / delta / deltas instead of evaluated `flags`.
+     */
+    configSync?: boolean;
+    /** Build config-mode query params for each connect/reconnect. */
+    getConfigSyncParams?: () => {
+        wantFullConfig: boolean;
+        sinceVersion?: number;
+    };
+    /**
+     * Apply a signed config-sync payload (verify + reduce). Return whether the
+     * rules store is ready enough to publish evaluated flags.
+     */
+    onConfigSyncEvent?: (eventName: 'lease' | 'fullConfig' | 'delta' | 'deltas', payload: Record<string, unknown>) => {
+        publish: boolean;
+    };
+    /** Evaluate current rules store against the given (or last) context. */
+    getEvaluatedFlags?: (context: C) => Record<string, T>;
+    /** Analytics map from the rules store (flag key → analytics_enabled). */
+    getAnalyticsMap?: () => Record<string, boolean>;
+    /**
+     * When true (config sync), POST /context is fire-and-forget telemetry —
+     * flags are re-evaluated locally and returned immediately.
+     */
+    contextAsTelemetry?: boolean;
+    /**
+     * API base for `POST …/context` (defaults to `endpoint`). Use the API host
+     * when `endpoint` is a stream-only hostname.
+     */
+    contextEndpoint?: string;
 }
 /**
  * A Server-Sent Events (SSE) transport implementation responsible for
@@ -17,8 +48,9 @@ export interface SseTransportConfig {
  * 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
+ * Context: `POST {contextEndpoint|endpoint}/context` with `x-api-key` returns 202 and the
  *   re-evaluated flags arrive on the existing stream after a 400ms debounce.
+ *   Prefer the API host when `endpoint` is stream-only (`STREAM_HOSTS`).
  *
  * @template C The shape of the evaluation context sent to the Flagmint server.
  * @template T The feature flag value type returned by the platform.
@@ -33,6 +65,7 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private eventSource;
     private flags;
     private context;
+    private lastSentContext;
     private connectionId;
     private onFlagsUpdatedCallback?;
     private onAnalyticsUpdatedCallback?;
@@ -46,13 +79,20 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private connectReject;
     private connectionListener?;
     private flagsListener?;
+    private leaseListener?;
+    private fullConfigListener?;
+    private deltaListener?;
+    private deltasListener?;
     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);
+    /** Wall time when the current SSE `connected` event was received (debug lifecycle). */
+    private connectedAtMs;
+    constructor(endpoint: string, sessionId: string, initialContext: C, refreshTokenCallback?: (() => Promise<string>) | undefined, configOptions?: Partial<SseTransportConfig<C, T>> | undefined);
+    private get configSyncEnabled();
     init(): Promise<void>;
     /**
      * POST /v2/flags/context. FF-EU always returns 202 and pushes the next
@@ -66,10 +106,21 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     onAnalyticsUpdated(callback: (analytics: Record<string, boolean>) => void): void;
     onError(callback: (error: Error) => void): void;
     destroy(): void;
+    /**
+     * Opt-in SSE lifecycle lines (`FlagClient` `debugLog: true`).
+     * Example: `[SseTransport] disconnected connectionId=… upMs=900012 reason=network_error retryInMs=1500`
+     */
+    private logLifecycle;
+    private logLifecycleConnected;
+    private logLifecycleDisconnected;
     private get apiKey();
+    /** Host for POST /context — API when stream host is SSE-only. */
+    private get contextBase();
     private applyFlags;
     private emitError;
     private performContextUpdate;
+    /** Fire-and-forget observed-context telemetry for config-sync mode. */
+    private postContextTelemetry;
     private safeReadJson;
     private quotaExtra;
     private handleQuotaPayload;
@@ -79,6 +130,7 @@ export declare class SseTransport<C, T> implements Transport<C, T> {
     private scheduleActiveReconnection;
     private createConnectionListener;
     private createFlagsListener;
+    private createConfigSyncListener;
     private createQuotaListener;
     /**
      * Named `error` events from FF-EU (`event: error`) after the stream is hijacked.

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

@@ -1,11 +1,7 @@
 export interface Transport<C, T> {
     init(onUpdate?: (flags: Record<string, T>) => void): Promise<void>;
-    fetchFlags(context: C, options?: {
-        persist?: boolean;
-    }): Promise<Record<string, T>>;
+    fetchFlags(context: C): 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": "2.0.0",
+  "version": "2.2.0",
   "description": "Framework-agnostic JavaScript SDK for managing feature flags in Flagmint applications.",
   "author": "Flagmint Team",
   "license": "BSD 3-Clause",