@toggld/browser 0.0.0-stage → 0.1.0

package/dist/client-BwTN-sJD.js

@@ -0,0 +1,742 @@
+// ../spec/src/index.ts
+/**
+* Subprotocol entry carrying the bearer credential on a sync WebSocket
+* upgrade: `toggld.bearer.<token>`. The standard `WebSocket` constructor
+* cannot set an `Authorization` header, so the token rides the
+* `Sec-WebSocket-Protocol` offer instead (a recognized pattern — it stays out
+* of URLs and access logs). Servers accept either this or a real
+* `Authorization: Bearer` header.
+*/
+const SYNC_BEARER_PROTOCOL_PREFIX = "toggld.bearer.";
+/**
+* The evaluation stream: `GET /eval/v1/stream` with a WebSocket upgrade. Unlike
+* the sync stream, it carries evaluated values, never targeting rules, so it
+* accepts public tokens (`ffp_…`) as well as evaluation keys. Authenticate with
+* the {@link SYNC_BEARER_PROTOCOL_PREFIX} subprotocol entry, offered after this
+* protocol name.
+*/
+const EVAL_STREAM_PATH = "/eval/v1/stream";
+const EVAL_STREAM_PROTOCOL = "toggld.eval.v1";
+/**
+* Heartbeat on the evaluation stream: the client sends the text frame
+* {@link STREAM_PING} (not JSON) and the server answers {@link STREAM_PONG}.
+* Without it, a connection that a proxy or a sleeping laptop dropped silently
+* would look open forever. Plain fixed strings, so a Durable Object can answer
+* with an auto-response without waking from hibernation.
+*/
+const STREAM_PING = "ping";
+/** How often the client pings, and how long it waits for the pong before it reconnects. */
+const STREAM_PING_INTERVAL_MS = 3e4;
+const STREAM_PONG_TIMEOUT_MS = 1e4;
+// src/internal/client.ts
+const DEFAULT_ENDPOINT = "https://api.toggld.io";
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_READY_TIMEOUT_MS = 5e3;
+const DEFAULT_STALE_AFTER_MS = 6e4;
+const MIN_POLL_INTERVAL_MS = 5e3;
+const RETRY_BASE_MS = 1e3;
+const RETRY_MAX_MS = 6e4;
+const STREAM_RETRY_MAX_MS = 3e4;
+/** After a 4429 close (too many context changes), wait out the server's one-minute window. */
+const RATE_LIMITED_RECONNECT_MS = 61e3;
+/**
+* Connects in a row that close before opening, after which the stream stops
+* reconnecting on its own. A rejected upgrade (401/403/404/400/429) reaches a
+* page only as a 1006 close, and its usual causes do not heal: an older
+* self-hosted server without the stream, a revoked token, or the shared rate
+* limit, which every retry spends for all visitors.
+*/
+const MAX_FAILED_CONNECTS = 3;
+const NORMAL_CLOSURE = 1e3;
+const ABNORMAL_CLOSURE = 1006;
+const isRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+const describe = (e) => isRecord(e) && typeof e.message === "string" ? e.message : String(e);
+/**
+* Deep-freeze a JSON value. Results are shared between every reader (and React
+* renders), so they must not be mutable. Freezing instead of cloning also keeps
+* an object flag's identity stable across reads.
+*/
+const freeze = (value) => {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const v of Object.values(value)) freeze(v);
+	}
+	return value;
+};
+/** Structural equality for JSON values, for context and result comparisons. */
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* Exponential backoff from 1 s, capped, with ±20% jitter, so many visitors that
+* failed together do not retry together.
+*/
+const backoff = (attempt, maxMs) => Math.min(maxMs, RETRY_BASE_MS * 2 ** attempt) * (.8 + Math.random() * .4);
+/** `Retry-After` as milliseconds from now: delay-seconds or an HTTP date. */
+const parseRetryAfter = (header) => {
+	if (header === null) return void 0;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(header);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+};
+const errorDetails = (flagKey, value, errorCode, errorMessage, flagMetadata = {}) => ({
+	flagKey,
+	value,
+	variant: void 0,
+	reason: "ERROR",
+	errorCode,
+	errorMessage,
+	flagMetadata
+});
+/** One entry of an OFREP bulk response, or `undefined` when it is malformed. */
+const fromWire = (raw) => {
+	if (!isRecord(raw) || typeof raw.key !== "string") return void 0;
+	const flagMetadata = freeze(isRecord(raw.metadata) ? raw.metadata : {});
+	if (typeof raw.errorCode === "string") return {
+		flagKey: raw.key,
+		value: null,
+		variant: void 0,
+		reason: "ERROR",
+		errorCode: raw.errorCode,
+		errorMessage: typeof raw.errorDetails === "string" ? raw.errorDetails : void 0,
+		flagMetadata
+	};
+	if (!("value" in raw) || typeof raw.reason !== "string") return void 0;
+	return {
+		flagKey: raw.key,
+		value: freeze(raw.value),
+		variant: typeof raw.variant === "string" ? raw.variant : void 0,
+		reason: raw.reason,
+		errorCode: void 0,
+		errorMessage: void 0,
+		flagMetadata
+	};
+};
+/**
+* A bootstrap entry. It may have passed through JSON (server-side rendering),
+* which drops `undefined` fields, so every field is optional on the way in.
+*/
+const fromBootstrap = (raw) => {
+	if (!isRecord(raw) || typeof raw.flagKey !== "string") return void 0;
+	return {
+		flagKey: raw.flagKey,
+		value: freeze(raw.value ?? null),
+		variant: typeof raw.variant === "string" ? raw.variant : void 0,
+		reason: typeof raw.reason === "string" ? raw.reason : "UNKNOWN",
+		errorCode: typeof raw.errorCode === "string" ? raw.errorCode : void 0,
+		errorMessage: typeof raw.errorMessage === "string" ? raw.errorMessage : void 0,
+		flagMetadata: freeze(isRecord(raw.flagMetadata) ? { ...raw.flagMetadata } : {})
+	};
+};
+const isPresent = (v) => v !== void 0;
+/** A stable fingerprint of a result, cached per (immutable) result object. */
+const signatures = /* @__PURE__ */ new WeakMap();
+const signature = (d) => {
+	let s = signatures.get(d);
+	if (s === void 0) {
+		s = JSON.stringify([
+			d.value,
+			d.variant,
+			d.reason,
+			d.errorCode,
+			d.errorMessage,
+			d.flagMetadata
+		]);
+		signatures.set(d, s);
+	}
+	return s;
+};
+/**
+* Merge fresh results into the previous map with structural sharing: a result
+* that did not change keeps its old object, and when nothing changed the old
+* map itself is returned. Readers that compare by identity see no change.
+*/
+const mergeFlags = (previous, incoming) => {
+	const next = /* @__PURE__ */ new Map();
+	let changed = previous.size !== incoming.length;
+	for (const entry of incoming) {
+		const old = previous.get(entry.flagKey);
+		if (old !== void 0 && signature(old) === signature(entry)) next.set(entry.flagKey, old);
+		else {
+			next.set(entry.flagKey, entry);
+			changed = true;
+		}
+	}
+	return changed ? next : previous;
+};
+const matches = (value, type) => {
+	switch (type) {
+		case "boolean": return typeof value === "boolean";
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "object": return typeof value === "object" && value !== null;
+	}
+};
+/**
+* A Toggld client for browser code. Create one per page (outside any React
+* render), with {@link ToggldClient.create} to await the first values or with
+* `new ToggldClient(options)` to start loading in the background.
+*/
+var ToggldClient = class ToggldClient {
+	#fetch;
+	#url;
+	#token;
+	#timeoutMs;
+	#staleAfterMs;
+	#refreshOnVisible;
+	/** The WebSocket constructor for the evaluation stream, if it is enabled and available. */
+	#webSocket;
+	#streamUrl;
+	#snapshot;
+	#listeners = /* @__PURE__ */ new Set();
+	/** Increments on every context change; responses for an older one are dropped. */
+	#generation = 0;
+	#inFlight;
+	#retryTimer;
+	#retryAttempt = 0;
+	#pollTimer;
+	/** No request before this time (`Date.now()`), after a 429. */
+	#blockedUntil = 0;
+	/** The token was rejected (401/403): evaluations report `PROVIDER_FATAL`. */
+	#fatal = false;
+	/**
+	* The last failure was permanent (a rejected token or context), so background
+	* refreshes stop until an explicit `refresh()` or a new context.
+	*/
+	#halted = false;
+	#closed = false;
+	#socket;
+	#reconnectTimer;
+	#reconnectAttempt = 0;
+	/** The server closed with 1008 (policy), or the socket cannot be built: never reconnect. */
+	#streamStopped = false;
+	/**
+	* Waiting instead of reconnecting: `context` after 1007/1009 (a new context
+	* retries), `connect` after too many failed connects (see
+	* {@link MAX_FAILED_CONNECTS}; `setContext()` or `refresh()` tries once more).
+	*/
+	#parked;
+	#failedConnects = 0;
+	/** The current socket delivered values for the current generation. */
+	#socketLive = false;
+	/** Adopted pushes, so an HTTP response can tell if one arrived during its flight. */
+	#pushes = 0;
+	#pingTimer;
+	/** Set while a ping awaits its answer. */
+	#pongTimer;
+	#hiddenAt;
+	#readyResolved = false;
+	#ready;
+	#resolveReady;
+	#onVisibilityChange = () => this.#handleVisible();
+	constructor(options) {
+		if (typeof options.publicToken !== "string" || options.publicToken.length === 0) throw new TypeError("[toggld] `publicToken` is required: the environment's public token (ffp_…).");
+		if (options.publicToken.startsWith("ffk_")) console.warn("[toggld] `publicToken` looks like a secret key (ffk_…). Secret keys must never ship to browsers. Use the environment's public token (ffp_…) from Settings → API Keys.");
+		const poll = options.pollIntervalMs;
+		if (poll !== void 0 && !(Number.isFinite(poll) && poll >= MIN_POLL_INTERVAL_MS)) throw new RangeError(`[toggld] \`pollIntervalMs\` must be a finite number of at least ${MIN_POLL_INTERVAL_MS}.`);
+		const fetchImpl = options.fetch ?? globalThis.fetch;
+		this.#fetch = (input, init) => fetchImpl(input, init);
+		this.#url = `${(options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/ofrep/v1/evaluate/flags`;
+		this.#token = options.publicToken;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+		this.#refreshOnVisible = options.refreshOnVisible ?? true;
+		const base = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+		this.#streamUrl = `${base.replace(/^http(s?):\/\//i, "ws$1://")}${EVAL_STREAM_PATH}`;
+		const webSocket = options.webSocket ?? (typeof WebSocket === "function" ? WebSocket : void 0);
+		this.#webSocket = options.stream !== false && typeof webSocket === "function" && (options.webSocket !== void 0 || typeof document !== "undefined") ? webSocket : void 0;
+		this.#ready = new Promise((resolve) => {
+			this.#resolveReady = resolve;
+		});
+		const bootstrap = (options.bootstrap ?? []).map(fromBootstrap).filter(isPresent);
+		const context = freeze({ ...options.context });
+		this.#snapshot = bootstrap.length > 0 ? {
+			status: "ready",
+			context,
+			flags: mergeFlags(/* @__PURE__ */ new Map(), bootstrap),
+			error: void 0,
+			updatedAt: Date.now(),
+			streaming: false
+		} : {
+			status: "loading",
+			context,
+			flags: /* @__PURE__ */ new Map(),
+			error: void 0,
+			updatedAt: void 0,
+			streaming: false
+		};
+		if (bootstrap.length > 0) this.#markReady();
+		else this.#request();
+		if (typeof document !== "undefined") {
+			document.addEventListener("visibilitychange", this.#onVisibilityChange);
+			if (poll !== void 0) this.#pollTimer = setInterval(() => this.#poll(), poll);
+		}
+		this.#connect();
+	}
+	/**
+	* Create a client and wait for its first values, or for `readyTimeoutMs`
+	* (default 5 s), whichever is first. It never rejects: on a timeout or a
+	* failure the client serves caller defaults and keeps retrying.
+	*/
+	static async create(options) {
+		const client = new ToggldClient(options);
+		let timer;
+		await Promise.race([client.ready(), new Promise((resolve) => {
+			timer = setTimeout(resolve, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+		})]);
+		clearTimeout(timer);
+		return client;
+	}
+	/**
+	* Resolves once the client first has values for its context, or once a
+	* failure makes that impossible (a rejected token or context). It never
+	* rejects. A client built with a bootstrap is ready at once.
+	*/
+	ready() {
+		return this.#ready;
+	}
+	/** The current {@link ClientSnapshot}: the same object until something changes. */
+	getSnapshot = () => this.#snapshot;
+	/**
+	* Call `listener` after every state change: new values, a status change, or
+	* a new context. Returns a function that removes it. The signature matches
+	* React's `useSyncExternalStore`, so `client.subscribe` can be passed as is.
+	*/
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	};
+	get status() {
+		return this.#snapshot.status;
+	}
+	get context() {
+		return this.#snapshot.context;
+	}
+	/**
+	* Evaluate for a new context: for example after sign-in, or when an
+	* attribute that targeting rules use changes. The context is **replaced**,
+	* not merged. Until the new values arrive the status is `"reconciling"` and
+	* the previous values are still served. Resolves when the request settles; it
+	* never rejects. Setting an identical context does nothing. An open stream
+	* receives the new context too.
+	*/
+	setContext(context) {
+		if (this.#closed) return Promise.resolve();
+		if (sameJson(context, this.#snapshot.context)) return this.#inFlight?.promise ?? Promise.resolve();
+		this.#generation++;
+		this.#socketLive = false;
+		this.#clearRetry();
+		this.#halted = false;
+		const hasValues = this.#snapshot.updatedAt !== void 0;
+		this.#update({
+			context: freeze({ ...context }),
+			status: hasValues ? "reconciling" : "loading"
+		});
+		if (this.#snapshot.streaming) this.#sendContext();
+		else if (this.#parked !== void 0) this.#unpark();
+		return this.#request();
+	}
+	/**
+	* Fetch fresh values for the current context now. A request already in
+	* flight for it is shared rather than repeated. Resolves when it settles; it
+	* never rejects. After a 429 it waits for `Retry-After` first. While the
+	* stream is live it does nothing: the values are already current.
+	*/
+	refresh() {
+		if (this.#closed) return Promise.resolve();
+		if (this.#live()) return this.#inFlight?.promise ?? Promise.resolve();
+		this.#halted = false;
+		if (this.#parked === "connect") this.#unpark();
+		return this.#request();
+	}
+	/**
+	* Stop all background work (requests, retries, polling, the stream,
+	* listeners). Values stay readable, but they no longer update.
+	*/
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#inFlight?.controller.abort();
+		this.#inFlight = void 0;
+		this.#clearRetry();
+		if (this.#pollTimer !== void 0) clearInterval(this.#pollTimer);
+		if (typeof document !== "undefined") document.removeEventListener("visibilitychange", this.#onVisibilityChange);
+		this.#listeners.clear();
+		this.#teardown();
+		this.#markReady();
+	}
+	/** Resolve a flag, returning full details with an untyped (JSON) value. */
+	evaluate(key, defaultValue) {
+		const snapshot = this.#snapshot;
+		const entry = snapshot.flags.get(key);
+		if (entry === void 0) {
+			if (snapshot.updatedAt !== void 0) return errorDetails(key, defaultValue, "FLAG_NOT_FOUND", `Flag '${key}' not found`);
+			return this.#fatal ? errorDetails(key, defaultValue, "PROVIDER_FATAL", snapshot.error ?? "The client cannot evaluate flags") : errorDetails(key, defaultValue, "PROVIDER_NOT_READY", snapshot.error ?? "Flag values are not loaded yet");
+		}
+		if (entry.errorCode !== void 0) return errorDetails(key, defaultValue, entry.errorCode, entry.errorMessage ?? "", entry.flagMetadata);
+		return entry;
+	}
+	/** The last result of every flag for the current context. */
+	allFlags() {
+		return Array.from(this.#snapshot.flags.values());
+	}
+	getBooleanValue(key, defaultValue) {
+		return this.getBooleanDetails(key, defaultValue).value;
+	}
+	getBooleanDetails(key, defaultValue) {
+		return this.#typed(key, defaultValue, "boolean");
+	}
+	getStringValue(key, defaultValue) {
+		return this.getStringDetails(key, defaultValue).value;
+	}
+	getStringDetails(key, defaultValue) {
+		return this.#typed(key, defaultValue, "string");
+	}
+	getNumberValue(key, defaultValue) {
+		return this.getNumberDetails(key, defaultValue).value;
+	}
+	getNumberDetails(key, defaultValue) {
+		return this.#typed(key, defaultValue, "number");
+	}
+	/** Object values are deep-frozen and shared: do not mutate them. */
+	getObjectValue(key, defaultValue) {
+		return this.getObjectDetails(key, defaultValue).value;
+	}
+	getObjectDetails(key, defaultValue) {
+		return this.#typed(key, defaultValue, "object");
+	}
+	#typed(key, defaultValue, type) {
+		const details = this.evaluate(key, defaultValue);
+		if (details.errorCode !== void 0 || matches(details.value, type)) return details;
+		return errorDetails(key, defaultValue, "TYPE_MISMATCH", `Flag '${key}' is not a ${type} flag`, details.flagMetadata);
+	}
+	#update(patch) {
+		const prev = this.#snapshot;
+		const next = {
+			...prev,
+			...patch
+		};
+		if (next.status === prev.status && next.context === prev.context && next.flags === prev.flags && next.error === prev.error && next.updatedAt === prev.updatedAt && next.streaming === prev.streaming) return;
+		this.#snapshot = next;
+		for (const listener of [...this.#listeners]) try {
+			listener();
+		} catch (e) {
+			console.error("[toggld] A subscriber threw:", e);
+		}
+	}
+	#markReady() {
+		if (this.#readyResolved) return;
+		this.#readyResolved = true;
+		this.#resolveReady();
+	}
+	/** Start (or join) the request for the current context. */
+	#request() {
+		const generation = this.#generation;
+		if (this.#inFlight?.generation === generation) return this.#inFlight.promise;
+		this.#inFlight?.controller.abort();
+		const controller = new AbortController();
+		const pushes = this.#pushes;
+		const promise = this.#fetchAll(this.#snapshot.context, controller.signal).then((outcome) => {
+			if (this.#inFlight?.controller === controller) this.#inFlight = void 0;
+			this.#settle(generation, outcome, pushes);
+		});
+		this.#inFlight = {
+			generation,
+			controller,
+			promise
+		};
+		return promise;
+	}
+	/**
+	* Apply a finished HTTP request (`pushes`: the push count when it started).
+	* HTTP may come from a cache that lags the stream, so it must not overwrite
+	* pushed values: it is dropped if a push for its context arrived during its
+	* flight, or if the stream is live. (A request started after the stream
+	* dropped can still briefly return older cached values; fixing that needs an
+	* ordered version on both channels.)
+	*/
+	#settle(generation, outcome, pushes) {
+		if (this.#closed || generation !== this.#generation || outcome.kind === "aborted") return;
+		if (pushes !== this.#pushes || this.#live()) return;
+		if (outcome.kind === "ok") {
+			this.#adopt(outcome.flags);
+			return;
+		}
+		if (outcome.retryAfterMs !== void 0) this.#blockedUntil = Math.max(this.#blockedUntil, Date.now() + outcome.retryAfterMs);
+		if (outcome.kind !== "retry") this.#halted = true;
+		if (outcome.kind === "fatal") {
+			this.#fatal = true;
+			this.#teardown();
+		}
+		if (this.#snapshot.status === "ready") {
+			this.#update({ error: outcome.message });
+			return;
+		}
+		this.#update({
+			status: "error",
+			error: outcome.message
+		});
+		if (outcome.kind === "retry") this.#scheduleRetry();
+		else this.#markReady();
+	}
+	/** Take fresh values for the current context, from HTTP or the stream. */
+	#adopt(flags) {
+		this.#clearRetry();
+		this.#halted = false;
+		if (this.#fatal) {
+			this.#fatal = false;
+			this.#connect();
+		}
+		this.#update({
+			status: "ready",
+			flags: mergeFlags(this.#snapshot.flags, flags),
+			error: void 0,
+			updatedAt: Date.now()
+		});
+		this.#markReady();
+	}
+	#scheduleRetry() {
+		this.#clearRetry();
+		const delay = backoff(this.#retryAttempt, RETRY_MAX_MS);
+		this.#retryAttempt++;
+		this.#retryTimer = setTimeout(() => {
+			this.#retryTimer = void 0;
+			this.#request();
+		}, delay);
+	}
+	#clearRetry() {
+		if (this.#retryTimer !== void 0) clearTimeout(this.#retryTimer);
+		this.#retryTimer = void 0;
+		this.#retryAttempt = 0;
+	}
+	/**
+	* Open, and this socket delivered values for the current context: a socket
+	* that never answers must not stop polling.
+	*/
+	#live() {
+		return this.#snapshot.streaming && this.#socketLive;
+	}
+	/** May a background trigger (poll, visibility) send a request now? */
+	#backgroundAllowed() {
+		return !this.#closed && !this.#halted && !this.#live() && this.#retryTimer === void 0 && Date.now() >= this.#blockedUntil && (typeof document === "undefined" || document.visibilityState !== "hidden");
+	}
+	#poll() {
+		if (this.#backgroundAllowed()) this.#request();
+	}
+	#handleVisible() {
+		if (document.visibilityState === "hidden") {
+			this.#hiddenAt = Date.now();
+			return;
+		}
+		const hiddenFor = this.#hiddenAt === void 0 ? 0 : Date.now() - this.#hiddenAt;
+		this.#hiddenAt = void 0;
+		if (this.#snapshot.streaming && hiddenFor >= this.#staleAfterMs) this.#ping();
+		this.#refreshIfStale();
+	}
+	#refreshIfStale() {
+		if (!this.#refreshOnVisible || !this.#backgroundAllowed()) return;
+		const { updatedAt } = this.#snapshot;
+		if (updatedAt !== void 0 && Date.now() - updatedAt >= this.#staleAfterMs) this.#request();
+	}
+	/**
+	* Open the evaluation stream, unless it is off, open, or stopped. Handlers
+	* are guarded and ignore stale sockets: a socket never breaks evaluation.
+	*/
+	#connect() {
+		clearTimeout(this.#reconnectTimer);
+		this.#reconnectTimer = void 0;
+		const WebSocketImpl = this.#webSocket;
+		if (WebSocketImpl === void 0 || this.#closed || this.#streamStopped || this.#fatal || this.#socket !== void 0) return;
+		let socket;
+		try {
+			socket = new WebSocketImpl(this.#streamUrl, [EVAL_STREAM_PROTOCOL, SYNC_BEARER_PROTOCOL_PREFIX + this.#token]);
+		} catch {
+			this.#streamStopped = true;
+			return;
+		}
+		this.#socket = socket;
+		this.#socketLive = false;
+		let opened = false;
+		const guard = (f) => (...args) => {
+			if (this.#socket !== socket) return;
+			try {
+				f(...args);
+			} catch (e) {
+				console.error("[toggld] The evaluation stream failed:", e);
+			}
+		};
+		socket.onopen = guard(() => {
+			opened = true;
+			this.#failedConnects = 0;
+			this.#pingTimer = setInterval(() => this.#ping(), STREAM_PING_INTERVAL_MS);
+			this.#update({ streaming: true });
+			this.#sendContext();
+		});
+		socket.onmessage = guard((event) => this.#receive(event.data));
+		socket.onclose = guard((event) => this.#disconnected(event.code, opened));
+	}
+	#send(data) {
+		try {
+			this.#socket?.send(data);
+		} catch {}
+	}
+	#sendContext() {
+		const message = {
+			type: "context",
+			seq: this.#generation,
+			context: this.#snapshot.context
+		};
+		this.#send(JSON.stringify(message));
+	}
+	/**
+	* Send a heartbeat, unless one is waiting. With no frame back in time, the
+	* connection died silently (a proxy timeout, a sleep): drop it and reconnect.
+	*/
+	#ping() {
+		if (this.#socket === void 0 || this.#pongTimer !== void 0) return;
+		this.#pongTimer = setTimeout(() => {
+			this.#pongTimer = void 0;
+			this.#disconnected(ABNORMAL_CLOSURE, true);
+			this.#refreshIfStale();
+		}, STREAM_PONG_TIMEOUT_MS);
+		this.#send(STREAM_PING);
+	}
+	#receive(data) {
+		clearTimeout(this.#pongTimer);
+		this.#pongTimer = void 0;
+		if (typeof data !== "string" || data === "pong") return;
+		let message;
+		try {
+			message = JSON.parse(data);
+		} catch {
+			return;
+		}
+		if (!isRecord(message) || message.type !== "flags" || typeof message.seq !== "number") return;
+		if (!Array.isArray(message.flags)) return;
+		this.#reconnectAttempt = 0;
+		if (message.seq !== this.#generation) return;
+		this.#pushes++;
+		this.#socketLive = true;
+		this.#adopt(message.flags.map(fromWire).filter(isPresent));
+	}
+	#teardown() {
+		const socket = this.#socket;
+		this.#socket = void 0;
+		this.#socketLive = false;
+		clearInterval(this.#pingTimer);
+		clearTimeout(this.#pongTimer);
+		clearTimeout(this.#reconnectTimer);
+		this.#pingTimer = this.#pongTimer = this.#reconnectTimer = void 0;
+		try {
+			socket?.close(NORMAL_CLOSURE);
+		} catch {}
+		this.#update({ streaming: false });
+	}
+	#unpark() {
+		this.#parked = void 0;
+		this.#connect();
+	}
+	#disconnected(code, opened) {
+		this.#teardown();
+		let delay;
+		if (!opened && ++this.#failedConnects >= MAX_FAILED_CONNECTS) this.#parked = "connect";
+		else if (code === 1008) this.#streamStopped = true;
+		else if (code === 4429) delay = RATE_LIMITED_RECONNECT_MS;
+		else if (code === 1007 || code === 1009) this.#parked = "context";
+		else delay = backoff(this.#reconnectAttempt++, STREAM_RETRY_MAX_MS);
+		if (delay !== void 0) this.#reconnectTimer = setTimeout(() => this.#connect(), delay);
+	}
+	/** One OFREP bulk request, mapped to an {@link Outcome}. Never rejects. */
+	async #fetchAll(context, signal) {
+		const wait = this.#blockedUntil - Date.now();
+		if (wait > 0) {
+			if (!await new Promise((resolve) => {
+				const timer = setTimeout(() => resolve(true), wait);
+				signal.addEventListener("abort", () => {
+					clearTimeout(timer);
+					resolve(false);
+				}, { once: true });
+			})) return { kind: "aborted" };
+		}
+		const timeout = new AbortController();
+		const timer = setTimeout(() => timeout.abort(), this.#timeoutMs);
+		const onAbort = () => timeout.abort();
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			let response;
+			try {
+				response = await this.#fetch(this.#url, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${this.#token}`,
+						"Content-Type": "application/json"
+					},
+					body: JSON.stringify({ context }),
+					signal: timeout.signal
+				});
+			} catch (e) {
+				if (signal.aborted) return { kind: "aborted" };
+				if (timeout.signal.aborted) return {
+					kind: "retry",
+					message: `The request timed out after ${this.#timeoutMs} ms`
+				};
+				return {
+					kind: "retry",
+					message: `The request failed: ${describe(e)}`
+				};
+			}
+			return await this.#readResponse(response);
+		} catch (e) {
+			if (signal.aborted) return { kind: "aborted" };
+			return {
+				kind: "retry",
+				message: `The response could not be read: ${describe(e)}`
+			};
+		} finally {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	async #readResponse(response) {
+		switch (response.status) {
+			case 401: return {
+				kind: "fatal",
+				message: "The API rejected the public token (HTTP 401). Check that `publicToken` is the environment's ffp_… token."
+			};
+			case 403: return {
+				kind: "fatal",
+				message: "The token cannot evaluate flags (HTTP 403)."
+			};
+			case 429: {
+				const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+				return {
+					kind: "retry",
+					message: `The API rate limit was reached (HTTP 429)${retryAfterMs !== void 0 ? `. Retrying in ${Math.ceil(retryAfterMs / 1e3)} s` : ""}.`,
+					retryAfterMs
+				};
+			}
+			case 400: {
+				const body = await response.json().catch(() => void 0);
+				return {
+					kind: "rejected",
+					message: `The API rejected the evaluation context (${isRecord(body) && typeof body.errorCode === "string" ? body.errorCode : "GENERAL"})${isRecord(body) && typeof body.errorDetails === "string" ? `: ${body.errorDetails}` : ""}`
+				};
+			}
+		}
+		if (!response.ok) return {
+			kind: "retry",
+			message: `Unexpected response status ${response.status}`
+		};
+		const body = await response.json().catch(() => void 0);
+		if (!isRecord(body) || !Array.isArray(body.flags)) return {
+			kind: "retry",
+			message: "The response is not a valid OFREP bulk evaluation response (PARSE_ERROR)"
+		};
+		return {
+			kind: "ok",
+			flags: body.flags.map(fromWire).filter(isPresent)
+		};
+	}
+};
+export { ToggldClient as t };