@userflow-tech/react-native 0.1.0 → 0.2.0

package/vendor/core/dist/transport/phoenix.js

@@ -0,0 +1,811 @@
+import { isServerMessage, TargetPlatform } from '@userflow-tech/protocol';
+import { UserflowAuthError, UserflowRateLimitError } from '../errors.js';
+import { CORE_VERSION } from '../version.js';
+import { createBackoff } from './backoff.js';
+import { createRateLimiter, RATE_LIMIT_PER_MINUTE } from './rateLimiter.js';
+import { defaultScheduler } from './scheduler.js';
+const TIMEOUT_MS = 15000;
+const HEARTBEAT_INTERVAL_MS = 30000;
+/**
+ * How long to wait for a heartbeat reply before declaring the socket dead.
+ * A short, bounded liveness window (vs. waiting a full heartbeat interval)
+ * means a silently-dropped socket is detected in seconds instead of up to two
+ * intervals. Capped at the heartbeat interval so tiny test intervals behave.
+ */
+const HEARTBEAT_REPLY_TIMEOUT_MS = 10000;
+/** WebSocket.OPEN readyState, referenced without the DOM/global type. */
+const WS_OPEN = 1;
+const PHOENIX_TOPIC = 'phoenix';
+const DEFAULT_CLIENT_CONTEXT = {
+    pageUrl: '',
+    viewportWidth: 390,
+    viewportHeight: 844,
+};
+/** Builds the Phoenix websocket URL for a given endpoint and client token. */
+export function buildWsUrl(serverEndpoint, clientToken) {
+    const host = serverEndpoint.replace(/\/$/, '');
+    const path = `/end-users/${encodeURIComponent(clientToken)}/socket/websocket?vsn=2.0.0`;
+    if (host.startsWith('http://'))
+        return `ws://${host.slice('http://'.length)}${path}`;
+    if (host.startsWith('https://'))
+        return `wss://${host.slice('https://'.length)}${path}`;
+    if (host.startsWith('ws://') || host.startsWith('wss://'))
+        return `${host}${path}`;
+    return `wss://${host}${path}`;
+}
+function uuid() {
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.randomUUID)
+        return webcrypto.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
+        const rand = (Math.random() * 16) | 0;
+        const value = char === 'x' ? rand : (rand & 0x3) | 0x8;
+        return value.toString(16);
+    });
+}
+function endUserJoinPayload(signature = null, flowSessionId = null, clientContext = DEFAULT_CLIENT_CONTEXT, clientConditions = []) {
+    return {
+        protocolVersion: 2,
+        userflowClientBuild: `mobile-${CORE_VERSION}`,
+        signature,
+        groupExternalId: null,
+        groupSignature: null,
+        flowSessionId,
+        checklistSessionId: null,
+        resourceCenterSessionId: null,
+        launchers: [],
+        trackers: [],
+        hasDraftSession: false,
+        clientConditions,
+        clientContext,
+        // Without this the server treats the socket as a web client and
+        // check_sessions immediately unsets any React Native draft preview.
+        targetPlatform: TargetPlatform.REACT_NATIVE,
+    };
+}
+function isSignatureRequiredError(error) {
+    return error instanceof UserflowAuthError && error.message.includes('user_signature_required');
+}
+function isNonIdempotentAttributeChange(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return 'add' in value || 'subtract' in value || 'append' in value || 'prepend' in value;
+}
+function attributesHaveNonIdempotentOps(attributes) {
+    if (attributes == null || typeof attributes !== 'object' || Array.isArray(attributes)) {
+        return false;
+    }
+    return Object.values(attributes).some(isNonIdempotentAttributeChange);
+}
+/** Idempotent client_message payloads may be replayed after a dropped ack. */
+function isReplayableClientMessage(payload) {
+    if (payload == null || typeof payload !== 'object') {
+        return true;
+    }
+    const record = payload;
+    if (record.kind === 'UpsertUser') {
+        return !attributesHaveNonIdempotentOps(record.attributes);
+    }
+    if (record.kind === 'UpsertGroup') {
+        return (!attributesHaveNonIdempotentOps(record.groupAttributes) &&
+            !attributesHaveNonIdempotentOps(record.membershipAttributes));
+    }
+    return true;
+}
+function joinError(response) {
+    if (response && typeof response === 'object') {
+        const err = response;
+        if (err.code && err.message)
+            return `${err.code}: ${err.message}`;
+        if (err.message)
+            return err.message;
+    }
+    return 'channel join rejected';
+}
+function resolveSocketCtor(ctor) {
+    const provided = ctor ?? globalThis.WebSocket;
+    if (!provided) {
+        throw new UserflowAuthError('No WebSocket implementation is available');
+    }
+    return provided;
+}
+/**
+ * A resilient Phoenix websocket connection to the Userflow end-user endpoint.
+ * It speaks the v2 serialized frame protocol (`[joinRef, ref, topic, event,
+ * payload]`), tracks an explicit lifecycle, auto-reconnects with backoff,
+ * heartbeats to keep the socket alive, queues outbound pushes while
+ * disconnected, and can be suspended/resumed for app background handling.
+ *
+ * Liveness: each heartbeat arms a short reply deadline so a silently-dropped
+ * socket is detected in seconds rather than up to two heartbeat intervals.
+ * {@link ensureAlive} fires an immediate probe (e.g. on foreground or when the
+ * host reports connectivity restored) so recovery does not wait for the next
+ * scheduled heartbeat. This keeps recovery fast with zero external
+ * dependencies; a host-provided network signal that calls `ensureAlive` is an
+ * optional optimization, not a requirement.
+ */
+export class PhoenixConnection {
+    constructor(clientToken, serverEndpoint, socketCtor, options) {
+        this.clientToken = clientToken;
+        this.serverEndpoint = serverEndpoint;
+        this.socketCtor = socketCtor;
+        this.ws = null;
+        this.ref = 0;
+        this.pending = new Map();
+        this.channelJoinRef = null;
+        this.channelTopic = null;
+        this.channelJoined = false;
+        this.state = 'disconnected';
+        this.shouldBeConnected = false;
+        this.desiredTopic = null;
+        this.desiredJoinSignature = null;
+        this.outbound = [];
+        this.establishPromise = null;
+        this.pendingConnect = null;
+        this.reconnectHandle = null;
+        this.heartbeatHandle = null;
+        this.heartbeatReplyHandle = null;
+        this.pendingHeartbeatRef = null;
+        this.activeFlowSessionId = null;
+        this.clientContext = { ...DEFAULT_CLIENT_CONTEXT };
+        this.clientConditions = [];
+        this.serverMessageHandlers = new Set();
+        /** Kinds already warned about this connection lifetime (reset on disconnect). */
+        this.warnedUnhandledKinds = new Set();
+        this.scheduler = options?.scheduler ?? defaultScheduler;
+        this.backoff = createBackoff(options?.reconnectLadderMs);
+        this.heartbeatIntervalMs = options?.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+        this.heartbeatReplyTimeoutMs =
+            options?.heartbeatReplyTimeoutMs ??
+                Math.min(HEARTBEAT_REPLY_TIMEOUT_MS, this.heartbeatIntervalMs);
+        this.rateLimitCapacity = options?.rateLimit?.capacity ?? RATE_LIMIT_PER_MINUTE;
+        this.rateLimiter = createRateLimiter({
+            ...(options?.rateLimit?.capacity !== undefined
+                ? { capacity: options.rateLimit.capacity }
+                : {}),
+            ...(options?.rateLimit?.intervalMs !== undefined
+                ? { intervalMs: options.rateLimit.intervalMs }
+                : {}),
+            ...(options?.rateLimit?.now !== undefined ? { now: options.rateLimit.now } : {}),
+        });
+        this.warn = options?.warn ?? ((message) => console.warn(message));
+    }
+    /** The current lifecycle state (observability + tests). */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Subscribe to inbound `server_message` frames on the joined end-user channel.
+     * Returns an unsubscribe function. Unknown message kinds are ignored (warned
+     * once per kind per connection lifetime).
+     */
+    onServerMessage(handler) {
+        this.serverMessageHandlers.add(handler);
+        return () => {
+            this.serverMessageHandlers.delete(handler);
+        };
+    }
+    /**
+     * Remember the active flow session id so every (re)join can resume it.
+     * Pass `null` when the session ends.
+     */
+    setFlowSessionId(flowSessionId) {
+        this.activeFlowSessionId = flowSessionId;
+    }
+    /** The flow session id currently included in end-user join payloads. */
+    getFlowSessionId() {
+        return this.activeFlowSessionId;
+    }
+    /**
+     * Remember the client-condition snapshot so every (re)join can seed the
+     * server's tracked/true/false sets. Pass the current engine snapshot
+     * (including `isTrue: null` unknowns).
+     */
+    setClientConditions(clientConditions) {
+        this.clientConditions = clientConditions.map((entry) => ({ ...entry }));
+    }
+    /** The client-condition snapshot currently included in end-user join payloads. */
+    getClientConditions() {
+        return this.clientConditions.map((entry) => ({ ...entry }));
+    }
+    /** The client context currently included in end-user join payloads. */
+    getClientContext() {
+        return { ...this.clientContext };
+    }
+    /**
+     * Remember client context so every (re)join reports the latest screen/URL.
+     * Does not push to the server; use {@link updateClientContext} for that.
+     */
+    setClientContext(clientContext) {
+        this.clientContext = { ...clientContext };
+    }
+    /**
+     * Update remembered client context and push `UpdateClientContext` when joined.
+     * Mirrors the web client's URL-change → `pushUpdateClientContext` path.
+     */
+    updateClientContext(clientContext) {
+        this.clientContext = { ...clientContext };
+        if (!this.channelTopic || !this.channelJoined) {
+            return Promise.resolve();
+        }
+        return this.enqueuePush('client_message', {
+            kind: 'UpdateClientContext',
+            clientContext: this.clientContext,
+        });
+    }
+    /**
+     * Push a Phase 3 client message on the joined channel. Reuses the outbound
+     * queue. `ToggleClientCondition` skips the rate limiter (web parity: meta
+     * messages must not be starved by UpsertUser / GoToStep traffic, and
+     * condition churn must not fail closed until the next rejoin).
+     * `BeginBatch` / `EndBatch` are the same class of meta message.
+     */
+    send(message) {
+        if (!this.channelTopic || !this.channelJoined) {
+            return Promise.reject(new UserflowAuthError('Not joined to an end-user channel'));
+        }
+        return this.enqueuePush('client_message', message, {
+            skipRateLimit: message.kind === 'ToggleClientCondition' ||
+                message.kind === 'BeginBatch' ||
+                message.kind === 'EndBatch',
+        });
+    }
+    /** Validates the client token by probing an anonymous end-user channel join. */
+    async validate() {
+        await this.openSocket();
+        try {
+            try {
+                await this.join(`end_users:anon-${uuid()}`, endUserJoinPayload());
+            }
+            catch (error) {
+                if (!isSignatureRequiredError(error))
+                    throw error;
+            }
+        }
+        finally {
+            this.disconnect();
+        }
+    }
+    /** Joins the end-user channel for `userId` and upserts the given attributes. */
+    async identify(userId, attributes, signature = null) {
+        this.shouldBeConnected = true;
+        this.desiredJoinSignature = signature;
+        await this.ensureJoined(`end_users:${userId}`);
+        await this.enqueuePush('client_message', { kind: 'UpsertUser', attributes });
+    }
+    /** Joins (or re-joins) the end-user channel when the socket dropped since identify. */
+    async ensureEndUserChannel(userId, signature = null) {
+        this.shouldBeConnected = true;
+        this.desiredJoinSignature = signature;
+        await this.ensureJoined(`end_users:${userId}`);
+    }
+    /** Upserts a group and the current user's membership on the joined channel. */
+    async group(payload) {
+        if (!this.channelTopic || !this.channelJoined) {
+            return Promise.reject(new UserflowAuthError('Not joined to an end-user channel'));
+        }
+        await this.enqueuePush('client_message', {
+            kind: 'UpsertGroup',
+            groupExternalId: payload.groupExternalId,
+            groupSignature: payload.groupSignature,
+            groupAttributes: payload.groupAttributes,
+            membershipAttributes: payload.membershipAttributes,
+        });
+    }
+    /** Push `UpsertUser` on an already-joined channel (no re-identify). */
+    async updateUser(attributes) {
+        if (!this.channelTopic || !this.channelJoined) {
+            return Promise.reject(new UserflowAuthError('Not joined to an end-user channel'));
+        }
+        await this.enqueuePush('client_message', { kind: 'UpsertUser', attributes });
+    }
+    /** Intentional teardown: stop everything, reject queued/in-flight work, clear intent. */
+    disconnect() {
+        this.shouldBeConnected = false;
+        this.desiredTopic = null;
+        this.desiredJoinSignature = null;
+        this.activeFlowSessionId = null;
+        this.clientContext = { ...DEFAULT_CLIENT_CONTEXT };
+        this.clientConditions = [];
+        this.warnedUnhandledKinds.clear();
+        this.state = 'disconnected';
+        this.cancelReconnect();
+        this.stopHeartbeat();
+        this.abortPendingConnect(new UserflowAuthError('Connection closed'));
+        this.discardInFlightPushes();
+        this.rejectPending(new UserflowAuthError('Connection closed'));
+        this.rejectQueue(new UserflowAuthError('Connection closed'));
+        this.detachAndClose(this.ws);
+        this.resetChannel();
+    }
+    /** Background handling: close but keep intent + queued pushes so `resume()` recovers. */
+    suspend() {
+        if (this.state === 'suspended')
+            return;
+        this.state = 'suspended';
+        this.cancelReconnect();
+        this.stopHeartbeat();
+        this.abortPendingConnect(new UserflowAuthError('Connection suspended'));
+        this.discardInFlightPushes();
+        this.rejectPending(new UserflowAuthError('Connection suspended'));
+        this.detachAndClose(this.ws);
+        this.resetChannel();
+    }
+    /** Foreground handling: reconnect, rejoin the desired topic, and flush the queue. */
+    resume() {
+        if (this.state !== 'suspended')
+            return;
+        if (!this.shouldBeConnected) {
+            this.state = 'disconnected';
+            return;
+        }
+        this.state = 'reconnecting';
+        this.attemptEstablish();
+    }
+    /**
+     * Eager reconnect when the host reports connectivity restored.
+     * No-op while suspended (lifecycle owns that path), while already connecting /
+     * connected, or when the SDK does not intend to be connected.
+     */
+    reconnectNow() {
+        if (!this.shouldBeConnected)
+            return;
+        if (this.state === 'suspended' || this.state === 'connecting' || this.state === 'connected') {
+            return;
+        }
+        this.cancelReconnect();
+        this.backoff.reset();
+        this.state = 'reconnecting';
+        this.attemptEstablish();
+    }
+    /**
+     * Verify the connection is really alive right now and recover fast if not.
+     * Called on foreground and other "the socket may have silently died" moments.
+     *
+     * - connected: fire an immediate heartbeat probe with a short reply deadline;
+     *   a dead socket is detected within {@link heartbeatReplyTimeoutMs} instead of
+     *   waiting for the next scheduled heartbeat.
+     * - reconnecting / disconnected (with intent): reconnect eagerly.
+     * - suspended / connecting: no-op (those paths already own recovery).
+     *
+     * This is the zero-dependency liveness path; it does not require any
+     * host-provided network signal.
+     */
+    ensureAlive() {
+        if (!this.shouldBeConnected)
+            return;
+        if (this.state === 'connected' && this.ws) {
+            // A beat is already outstanding — its reply deadline will catch a death.
+            if (this.pendingHeartbeatRef !== null)
+                return;
+            this.clearHeartbeatTimer();
+            this.sendHeartbeat();
+            return;
+        }
+        this.reconnectNow();
+    }
+    async ensureJoined(topic) {
+        this.desiredTopic = topic;
+        if (this.state === 'connected' && this.channelTopic === topic && this.channelJoined) {
+            return;
+        }
+        if (this.state === 'connected' && this.channelTopic !== topic && this.ws) {
+            this.detachAndClose(this.ws);
+            this.resetChannel();
+        }
+        this.cancelReconnect();
+        await this.establish();
+    }
+    establish() {
+        if (this.establishPromise)
+            return this.establishPromise;
+        this.establishPromise = this.doEstablish().finally(() => {
+            this.establishPromise = null;
+        });
+        return this.establishPromise;
+    }
+    async doEstablish() {
+        this.state = 'connecting';
+        await this.openSocket();
+        if (this.desiredTopic) {
+            await this.joinChannel(this.desiredTopic);
+        }
+        this.state = 'connected';
+        this.backoff.reset();
+        this.startHeartbeat();
+        this.flush();
+    }
+    attemptEstablish() {
+        void this.establish().catch(() => {
+            if (this.shouldBeConnected && this.state !== 'suspended') {
+                this.scheduleReconnect();
+            }
+        });
+    }
+    openSocket() {
+        return new Promise((resolve, reject) => {
+            const SocketCtor = resolveSocketCtor(this.socketCtor);
+            const ws = new SocketCtor(buildWsUrl(this.serverEndpoint, this.clientToken));
+            this.ws = ws;
+            let settled = false;
+            const timer = this.scheduler.setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.pendingConnect = null;
+                this.detachAndClose(ws);
+                reject(new UserflowAuthError('WebSocket connection timed out'));
+            }, TIMEOUT_MS);
+            const finish = () => {
+                settled = true;
+                this.pendingConnect = null;
+                this.scheduler.clearTimeout(timer);
+            };
+            this.pendingConnect = {
+                reject: (error) => {
+                    if (settled)
+                        return;
+                    finish();
+                    this.detachAndClose(ws);
+                    reject(error);
+                },
+            };
+            ws.onopen = () => {
+                if (settled)
+                    return;
+                finish();
+                resolve();
+            };
+            ws.onmessage = (event) => this.handleMessage(event);
+            ws.onerror = () => {
+                if (!settled) {
+                    finish();
+                    this.detachAndClose(ws);
+                    reject(new UserflowAuthError('WebSocket connection failed'));
+                }
+                else {
+                    this.onSocketDown(ws);
+                }
+            };
+            ws.onclose = () => {
+                if (!settled) {
+                    finish();
+                    this.detachAndClose(ws);
+                    reject(new UserflowAuthError('WebSocket closed before connect completed'));
+                }
+                else {
+                    this.onSocketDown(ws);
+                }
+            };
+        });
+    }
+    onSocketDown(socket) {
+        if (this.ws !== socket)
+            return;
+        this.detachAndClose(socket);
+        this.channelJoined = false;
+        this.channelJoinRef = null;
+        this.stopHeartbeat();
+        this.discardInFlightPushes();
+        this.rejectPending(new UserflowAuthError('Connection dropped'));
+        if (this.shouldBeConnected && this.state !== 'suspended') {
+            this.state = 'reconnecting';
+            this.scheduleReconnect();
+        }
+        else {
+            this.state = 'disconnected';
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectHandle !== null)
+            return;
+        const delay = this.backoff.nextDelay();
+        this.reconnectHandle = this.scheduler.setTimeout(() => {
+            this.reconnectHandle = null;
+            if (!this.shouldBeConnected || this.state === 'suspended')
+                return;
+            this.attemptEstablish();
+        }, delay);
+    }
+    cancelReconnect() {
+        if (this.reconnectHandle !== null) {
+            this.scheduler.clearTimeout(this.reconnectHandle);
+            this.reconnectHandle = null;
+        }
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.scheduleNextHeartbeat();
+    }
+    stopHeartbeat() {
+        this.clearHeartbeatTimer();
+        this.clearHeartbeatReplyTimer();
+        this.pendingHeartbeatRef = null;
+    }
+    scheduleNextHeartbeat() {
+        this.clearHeartbeatTimer();
+        this.heartbeatHandle = this.scheduler.setTimeout(() => this.sendHeartbeat(), this.heartbeatIntervalMs);
+    }
+    clearHeartbeatTimer() {
+        if (this.heartbeatHandle !== null) {
+            this.scheduler.clearTimeout(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+    }
+    clearHeartbeatReplyTimer() {
+        if (this.heartbeatReplyHandle !== null) {
+            this.scheduler.clearTimeout(this.heartbeatReplyHandle);
+            this.heartbeatReplyHandle = null;
+        }
+    }
+    /**
+     * Send one heartbeat and arm a short reply deadline. The next heartbeat is
+     * scheduled when the reply lands (see {@link handleMessage}); if the deadline
+     * fires first with the beat still pending, the socket is declared dead.
+     */
+    sendHeartbeat() {
+        this.heartbeatHandle = null;
+        if (this.state !== 'connected' || !this.ws)
+            return;
+        // A prior beat was never answered (defensive; the reply timer normally
+        // catches this first).
+        if (this.pendingHeartbeatRef !== null) {
+            this.onSocketDown(this.ws);
+            return;
+        }
+        const ref = this.nextRef();
+        this.pendingHeartbeatRef = ref;
+        this.ws.send(JSON.stringify([null, ref, PHOENIX_TOPIC, 'heartbeat', {}]));
+        this.armHeartbeatReplyTimeout();
+    }
+    armHeartbeatReplyTimeout() {
+        this.clearHeartbeatReplyTimer();
+        this.heartbeatReplyHandle = this.scheduler.setTimeout(() => {
+            this.heartbeatReplyHandle = null;
+            if (this.state !== 'connected' || !this.ws)
+                return;
+            if (this.pendingHeartbeatRef !== null) {
+                this.onSocketDown(this.ws);
+            }
+        }, this.heartbeatReplyTimeoutMs);
+    }
+    handleMessage(event) {
+        let frame;
+        try {
+            frame = JSON.parse(String(event.data));
+        }
+        catch {
+            return;
+        }
+        if (!Array.isArray(frame) || frame.length < 5)
+            return;
+        const [, id, topic, eventName, payload] = frame;
+        if (eventName === 'server_message') {
+            this.dispatchServerMessage(topic, payload);
+            return;
+        }
+        if (eventName !== 'phx_reply' || typeof id !== 'string')
+            return;
+        if (topic === PHOENIX_TOPIC && id === this.pendingHeartbeatRef) {
+            this.pendingHeartbeatRef = null;
+            this.clearHeartbeatReplyTimer();
+            if (this.state === 'connected')
+                this.scheduleNextHeartbeat();
+            return;
+        }
+        const wait = this.pending.get(id);
+        if (!wait || wait.topic !== topic)
+            return;
+        this.pending.delete(id);
+        this.scheduler.clearTimeout(wait.timer);
+        const reply = payload;
+        if (reply.status === 'ok') {
+            wait.ok();
+            return;
+        }
+        wait.fail(new UserflowAuthError(`${topic}: ${joinError(reply.response)}`));
+    }
+    dispatchServerMessage(topic, payload) {
+        if (!this.channelTopic || topic !== this.channelTopic)
+            return;
+        if (!isServerMessage(payload)) {
+            if (typeof payload === 'object' &&
+                payload !== null &&
+                'kind' in payload &&
+                typeof payload.kind === 'string') {
+                const kind = payload.kind;
+                if (!this.warnedUnhandledKinds.has(kind)) {
+                    this.warnedUnhandledKinds.add(kind);
+                    this.warn(`Userflow: ignoring unsupported server message kind "${kind}" ` +
+                        '(not implemented by the mobile SDK)');
+                }
+            }
+            return;
+        }
+        for (const handler of this.serverMessageHandlers) {
+            try {
+                handler(payload);
+            }
+            catch {
+                // Never let a subscriber break the socket message loop.
+            }
+        }
+    }
+    nextRef() {
+        this.ref += 1;
+        return String(this.ref);
+    }
+    async joinChannel(topic) {
+        this.channelTopic = topic;
+        await this.join(topic, endUserJoinPayload(this.desiredJoinSignature, this.activeFlowSessionId, this.clientContext, this.clientConditions));
+        this.channelJoined = true;
+    }
+    join(topic, payload) {
+        return this.request(topic, (joinRef, ref) => {
+            if (topic.startsWith('end_users:')) {
+                this.channelJoinRef = joinRef;
+            }
+            return [joinRef, ref, topic, 'phx_join', payload];
+        });
+    }
+    request(topic, buildFrame) {
+        return new Promise((ok, fail) => {
+            if (!this.ws || this.ws.readyState !== WS_OPEN) {
+                fail(new UserflowAuthError('WebSocket is not open'));
+                return;
+            }
+            const joinRef = topic.startsWith('end_users:')
+                ? (this.channelJoinRef ?? this.nextRef())
+                : this.nextRef();
+            const ref = this.nextRef();
+            const timer = this.scheduler.setTimeout(() => {
+                const wait = this.pending.get(ref);
+                if (!wait)
+                    return;
+                this.pending.delete(ref);
+                wait.fail(new UserflowAuthError(`${topic}: reply timed out`));
+            }, TIMEOUT_MS);
+            this.pending.set(ref, { topic, timer, ok, fail });
+            this.ws.send(JSON.stringify(buildFrame(joinRef, ref)));
+        });
+    }
+    /**
+     * Enqueue an outbound push. Only `client_message` events pass through here.
+     * Channel joins (`phx_join`) and heartbeats bypass this gate. Meta messages
+     * such as `ToggleClientCondition` may set `skipRateLimit` so condition
+     * updates are not dropped under UpsertUser / GoToStep load.
+     */
+    enqueuePush(event, payload, options) {
+        if (!options?.skipRateLimit && !this.rateLimiter.tryAcquire()) {
+            return Promise.reject(new UserflowRateLimitError(`Client message rate limit exceeded (${this.rateLimitCapacity}/min)`));
+        }
+        return new Promise((resolve, reject) => {
+            this.outbound.push({
+                event,
+                payload,
+                inFlight: false,
+                inFlightRef: null,
+                replay: isReplayableClientMessage(payload),
+                resolve,
+                reject,
+            });
+            this.flush();
+        });
+    }
+    flush() {
+        if (this.state !== 'connected' || !this.channelJoined || !this.ws)
+            return;
+        for (const item of this.outbound) {
+            if (item.inFlight)
+                continue;
+            this.sendPush(item);
+        }
+    }
+    sendPush(item) {
+        if (!this.ws || !this.channelTopic || !this.channelJoinRef)
+            return;
+        const topic = this.channelTopic;
+        const joinRef = this.channelJoinRef;
+        const ref = this.nextRef();
+        const timer = this.scheduler.setTimeout(() => {
+            const wait = this.pending.get(ref);
+            if (!wait)
+                return;
+            this.pending.delete(ref);
+            wait.fail(new UserflowAuthError(`${topic}: reply timed out`));
+        }, TIMEOUT_MS);
+        this.pending.set(ref, {
+            topic,
+            timer,
+            ok: () => {
+                this.removeFromQueue(item);
+                item.resolve();
+            },
+            fail: (error) => {
+                this.removeFromQueue(item);
+                item.reject(error);
+            },
+        });
+        item.inFlight = true;
+        item.inFlightRef = ref;
+        this.ws.send(JSON.stringify([joinRef, ref, topic, item.event, item.payload]));
+    }
+    removeFromQueue(item) {
+        const index = this.outbound.indexOf(item);
+        if (index !== -1)
+            this.outbound.splice(index, 1);
+    }
+    /**
+     * On a drop/suspend, forget the in-flight reply for each queued push.
+     * Idempotent messages are reset and re-sent after the next (re)join
+     * (at-least-once). Non-idempotent attribute ops (`add` / `subtract` /
+     * `append` / `prepend`) are rejected instead, so a lost ack cannot apply
+     * the mutation twice.
+     */
+    discardInFlightPushes() {
+        const kept = [];
+        for (const item of this.outbound) {
+            if (item.inFlight && item.inFlightRef) {
+                const wait = this.pending.get(item.inFlightRef);
+                if (wait) {
+                    this.scheduler.clearTimeout(wait.timer);
+                    this.pending.delete(item.inFlightRef);
+                }
+                if (!item.replay) {
+                    item.reject(new UserflowAuthError('Connection dropped before acknowledgement'));
+                    continue;
+                }
+            }
+            item.inFlight = false;
+            item.inFlightRef = null;
+            kept.push(item);
+        }
+        this.outbound = kept;
+    }
+    rejectPending(error) {
+        for (const wait of this.pending.values()) {
+            this.scheduler.clearTimeout(wait.timer);
+            wait.fail(error);
+        }
+        this.pending.clear();
+        this.pendingHeartbeatRef = null;
+    }
+    rejectQueue(error) {
+        const items = this.outbound;
+        this.outbound = [];
+        for (const item of items)
+            item.reject(error);
+    }
+    abortPendingConnect(error) {
+        const pending = this.pendingConnect;
+        this.pendingConnect = null;
+        pending?.reject(error);
+    }
+    detachAndClose(ws) {
+        if (!ws)
+            return;
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onerror = null;
+        ws.onclose = null;
+        try {
+            ws.close();
+        }
+        catch {
+            // ignore
+        }
+        if (this.ws === ws)
+            this.ws = null;
+    }
+    resetChannel() {
+        this.channelJoinRef = null;
+        this.channelTopic = null;
+        this.channelJoined = false;
+    }
+}
+/** Convenience helper: open a connection, validate credentials, and close it. */
+export function validateCredentials(clientToken, serverEndpoint, socketCtor) {
+    return new PhoenixConnection(clientToken, serverEndpoint, socketCtor).validate();
+}
+//# sourceMappingURL=phoenix.js.map