@userflow-tech/react-native 0.1.0 → 0.1.1

package/vendor/core/dist/engine/FlowSessionEngine.js

@@ -0,0 +1,310 @@
+import { EndFlowReasonInput, TooltipMissingBehavior } from '@userflow-tech/protocol';
+import { UserflowAuthError } from '../errors.js';
+import { defaultScheduler } from '../transport/scheduler.js';
+import { handleActions } from './handleActions.js';
+/** Cap for in-memory client-message retry after transport failure. */
+const MAX_PENDING_SENDS = 20;
+function isValidFlowSession(session) {
+    if (session == null || typeof session !== 'object')
+        return false;
+    const candidate = session;
+    if (typeof candidate.id !== 'string' || candidate.id.length === 0)
+        return false;
+    if (candidate.version == null || typeof candidate.version !== 'object')
+        return false;
+    if (!Array.isArray(candidate.version.steps))
+        return false;
+    if (candidate.currentStep == null || typeof candidate.currentStep !== 'object')
+        return false;
+    if (typeof candidate.currentStep.id !== 'string' || candidate.currentStep.id.length === 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Framework-agnostic flow session state machine (Phase 3 WS2).
+ *
+ * Ports web `userflow-client` session/clock/wait-timer semantics onto the
+ * Phoenix transport seam. Call {@link attach} after identify.
+ */
+export class FlowSessionEngine {
+    constructor(deps) {
+        this.clientClock = 1;
+        this.serverClock = 1;
+        this.flowSessionClock = 0;
+        this.flowSession = null;
+        this.listeners = new Set();
+        this.conditionWaitTimers = new Map();
+        this.pendingSends = [];
+        this.flushingPending = false;
+        this.unsubscribeServerMessages = null;
+        this.transport = deps.transport;
+        this.onOpenExternalUrl = deps.onOpenExternalUrl;
+        this.warn = deps.warn ?? ((message) => console.warn(message));
+        this.scheduler = deps.scheduler ?? defaultScheduler;
+    }
+    /** Subscribe to inbound server messages. Must be called after identify. */
+    attach() {
+        this.detach();
+        this.unsubscribeServerMessages = this.transport.onServerMessage((message) => {
+            this.handleServerMessage(message);
+        });
+        void this.flushPendingSends();
+        return () => this.detach();
+    }
+    /**
+     * Unsubscribe from server messages and clear wait timers (keeps session state).
+     * Note: in-flight condition wait timers are dropped and not restarted on
+     * re-attach; the server must send StartConditionWaitTimer again if needed.
+     */
+    detach() {
+        this.unsubscribeServerMessages?.();
+        this.unsubscribeServerMessages = null;
+        this.clearConditionWaitTimers();
+    }
+    on(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    getFlowSession() {
+        return this.flowSession;
+    }
+    getCurrentStep() {
+        const session = this.flowSession;
+        if (!session?.currentStep)
+            return null;
+        return session.version.steps.find((step) => step.id === session.currentStep.id) ?? null;
+    }
+    /** Visible for tests / advanced callers; prefer {@link attach}. */
+    handleServerMessage(message) {
+        switch (message.kind) {
+            case 'SetFlowSession': {
+                if (!isValidFlowSession(message.session)) {
+                    this.warn('Userflow: ignoring malformed SetFlowSession (missing id/version.steps/currentStep)');
+                    return;
+                }
+                if (this.flowSessionClock <= this.serverClock ||
+                    this.flowSession?.id === message.session.id) {
+                    this.setFlowSession(message.session, this.serverClock);
+                }
+                return;
+            }
+            case 'UnsetFlowSession': {
+                if (this.flowSessionClock > this.serverClock)
+                    return;
+                if (this.flowSession?.id === message.sessionId) {
+                    this.setFlowSession(null, this.serverClock);
+                }
+                return;
+            }
+            case 'ForceGoToStep': {
+                // Matches web: emit only — does not update session.currentStep.
+                // getCurrentStep() stays stale until a later SetFlowSession; UI must
+                // resolve the step from this event (or wait for SetFlowSession).
+                if (this.flowSessionClock > this.serverClock)
+                    return;
+                if (this.flowSession?.id === message.sessionId) {
+                    this.emit({
+                        type: 'goToStep',
+                        sessionId: message.sessionId,
+                        stepId: message.stepId,
+                    });
+                }
+                return;
+            }
+            case 'StartConditionWaitTimer': {
+                this.startConditionWaitTimer(message.conditionId, message.waitTime);
+                return;
+            }
+            case 'CancelConditionWaitTimer': {
+                this.cancelConditionWaitTimer(message.conditionId);
+                return;
+            }
+            case 'TrackClientCondition':
+            case 'UntrackClientCondition':
+                // Handled by ClientConditionEngine (separate subscriber).
+                return;
+        }
+    }
+    async goToStep(step) {
+        const session = this.requireFlowSession();
+        const promise = this.sendTracked({
+            kind: 'GoToStep',
+            sessionId: session.id,
+            stepId: step.id,
+        });
+        // Mutates the live session object already emitted via sessionChange.
+        // Listeners that hold that reference and only re-render on sessionChange
+        // will not see this update — they must also handle the goToStep event
+        // (or we should clone before mutating in a later pass).
+        session.currentStep = { id: step.id, crossVersionId: step.crossVersionId };
+        this.emit({ type: 'goToStep', sessionId: session.id, stepId: step.id });
+        await promise;
+    }
+    async endFlow(endReason) {
+        const session = this.requireFlowSession();
+        const sessionId = session.id;
+        const flowId = session.flow.id;
+        this.optimisticClockUIUpdate(() => {
+            if (this.flowSession?.id === sessionId) {
+                this.setFlowSession(null, this.clientClock);
+            }
+        });
+        this.emit({ type: 'flowEnded', flowId, endReason });
+        await this.sendTracked({
+            kind: 'EndFlow',
+            sessionId,
+            endReason,
+        });
+    }
+    async reportTooltipTargetMissing(stepId) {
+        const session = this.requireFlowSession();
+        await this.sendTracked({
+            kind: 'ReportTooltipTargetMissing',
+            sessionId: session.id,
+            stepId,
+        });
+        const theme = session.version.theme;
+        if (theme.tooltipMissingBehavior === TooltipMissingBehavior.END && !session.draftMode) {
+            await this.endFlow(EndFlowReasonInput.TOOLTIP_TARGET_MISSING);
+        }
+    }
+    handleActions(actions) {
+        const session = this.requireFlowSession();
+        return handleActions(session, actions, {
+            engine: this,
+            ...(this.onOpenExternalUrl !== undefined
+                ? { onOpenExternalUrl: this.onOpenExternalUrl }
+                : {}),
+            warn: this.warn,
+        });
+    }
+    /**
+     * Clear the local flow session and join resume id without detaching from
+     * server messages. Used when a long background makes mid-flow resume stale.
+     */
+    clearLocalSession() {
+        this.clearConditionWaitTimers();
+        if (this.flowSession !== null) {
+            this.flowSession = null;
+            this.transport.setFlowSessionId(null);
+            this.emit({ type: 'sessionChange', session: null });
+        }
+        else {
+            this.transport.setFlowSessionId(null);
+        }
+    }
+    /** Clear session, clocks, timers, pending sends, and join resume id; detach from transport. */
+    reset() {
+        this.detach();
+        this.clientClock = 1;
+        this.serverClock = 1;
+        this.flowSessionClock = 0;
+        this.pendingSends.length = 0;
+        this.clearLocalSession();
+    }
+    /**
+     * Flush client messages queued after transport failure.
+     * Call after reconnect / lifecycle resume (`ensureConnected` path).
+     */
+    async flushPendingSends() {
+        if (this.flushingPending || this.pendingSends.length === 0)
+            return;
+        this.flushingPending = true;
+        try {
+            while (this.pendingSends.length > 0) {
+                const message = this.pendingSends[0];
+                try {
+                    await this.transport.send(message);
+                    this.pendingSends.shift();
+                }
+                catch {
+                    // Keep the head (and rest) queued until the next successful reconnect.
+                    return;
+                }
+            }
+        }
+        finally {
+            this.flushingPending = false;
+        }
+    }
+    /** @internal Test helper. */
+    getPendingSendCountForTests() {
+        return this.pendingSends.length;
+    }
+    setFlowSession(session, clock) {
+        this.flowSession = session;
+        this.flowSessionClock = clock;
+        this.transport.setFlowSessionId(session?.id ?? null);
+        this.emit({ type: 'sessionChange', session });
+    }
+    optimisticClockUIUpdate(callback) {
+        this.clientClock += 1;
+        callback();
+    }
+    enqueuePendingSend(message) {
+        if (this.pendingSends.length >= MAX_PENDING_SENDS) {
+            this.pendingSends.shift();
+        }
+        this.pendingSends.push(message);
+    }
+    async sendTracked(message) {
+        const clock = this.clientClock;
+        try {
+            await this.transport.send(message);
+            void this.flushPendingSends();
+        }
+        catch {
+            this.enqueuePendingSend(message);
+            this.warn(`Userflow: failed to send ${message.kind}; queued for retry on reconnect`);
+        }
+        finally {
+            this.serverClock = clock;
+        }
+    }
+    startConditionWaitTimer(conditionId, waitTime) {
+        if (this.conditionWaitTimers.has(conditionId))
+            return;
+        const ms = parseFloat(waitTime) * 1000;
+        const handle = this.scheduler.setTimeout(() => {
+            this.conditionWaitTimers.delete(conditionId);
+            void this.sendTracked({
+                kind: 'FireConditionWaitTimer',
+                conditionId,
+            });
+        }, Number.isFinite(ms) ? Math.max(0, ms) : 0);
+        this.conditionWaitTimers.set(conditionId, handle);
+    }
+    cancelConditionWaitTimer(conditionId) {
+        const handle = this.conditionWaitTimers.get(conditionId);
+        if (handle === undefined)
+            return;
+        this.scheduler.clearTimeout(handle);
+        this.conditionWaitTimers.delete(conditionId);
+    }
+    clearConditionWaitTimers() {
+        for (const handle of this.conditionWaitTimers.values()) {
+            this.scheduler.clearTimeout(handle);
+        }
+        this.conditionWaitTimers.clear();
+    }
+    requireFlowSession() {
+        if (!this.flowSession) {
+            throw new UserflowAuthError('No active flow session');
+        }
+        return this.flowSession;
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Never let a subscriber break the engine.
+            }
+        }
+    }
+}
+//# sourceMappingURL=FlowSessionEngine.js.map

package/vendor/core/dist/engine/FlowSessionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowSessionEngine.js","sourceRoot":"","sources":["../../src/engine/FlowSessionEngine.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAErF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAoC,MAAM,2BAA2B,CAAC;AAE/F,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,sEAAsE;AACtE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAwB7B,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACjE,MAAM,SAAS,GAAG,OAAuC,CAAC;IAC1D,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAChF,IAAI,SAAS,CAAC,OAAO,IAAI,IAAI,IAAI,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,IAAI,SAAS,CAAC,WAAW,IAAI,IAAI,IAAI,OAAO,SAAS,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7F,IAAI,OAAO,SAAS,CAAC,WAAW,CAAC,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAiB5B,YAAY,IAA2B;QAX/B,gBAAW,GAAG,CAAC,CAAC;QAChB,gBAAW,GAAG,CAAC,CAAC;QAChB,qBAAgB,GAAG,CAAC,CAAC;QACrB,gBAAW,GAA+B,IAAI,CAAC;QAEtC,cAAS,GAAG,IAAI,GAAG,EAA6B,CAAC;QACjD,wBAAmB,GAAG,IAAI,GAAG,EAAuB,CAAC;QACrD,iBAAY,GAAoB,EAAE,CAAC;QAC5C,oBAAe,GAAG,KAAK,CAAC;QACxB,8BAAyB,GAAwB,IAAI,CAAC;QAG5D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACtD,CAAC;IAED,2EAA2E;IAC3E,MAAM;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,EAAE;YAC1E,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QACH,KAAK,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC9B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,IAAI,CAAC,yBAAyB,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC;QACtC,IAAI,CAAC,wBAAwB,EAAE,CAAC;IAClC,CAAC;IAED,EAAE,CAAC,QAAmC;QACpC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,cAAc;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;QACjC,IAAI,CAAC,OAAO,EAAE,WAAW;YAAE,OAAO,IAAI,CAAC;QACvC,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,WAAY,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IAC3F,CAAC;IAED,mEAAmE;IACnE,mBAAmB,CAAC,OAAsB;QACxC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzC,IAAI,CAAC,IAAI,CACP,oFAAoF,CACrF,CAAC;oBACF,OAAO;gBACT,CAAC;gBACD,IACE,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,WAAW;oBACzC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,EAC3C,CAAC;oBACD,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBACzD,CAAC;gBACD,OAAO;YACT,CAAC;YAED,KAAK,kBAAkB,CAAC,CAAC,CAAC;gBACxB,IAAI,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,WAAW;oBAAE,OAAO;gBACrD,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;oBAC/C,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC9C,CAAC;gBACD,OAAO;YACT,CAAC;YAED,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,gEAAgE;gBAChE,qEAAqE;gBACrE,iEAAiE;gBACjE,IAAI,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,WAAW;oBAAE,OAAO;gBACrD,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;oBAC/C,IAAI,CAAC,IAAI,CAAC;wBACR,IAAI,EAAE,UAAU;wBAChB,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;qBACvB,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO;YACT,CAAC;YAED,KAAK,yBAAyB,CAAC,CAAC,CAAC;gBAC/B,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACpE,OAAO;YACT,CAAC;YAED,KAAK,0BAA0B,CAAC,CAAC,CAAC;gBAChC,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACnD,OAAO;YACT,CAAC;YAED,KAAK,sBAAsB,CAAC;YAC5B,KAAK,wBAAwB;gBAC3B,0DAA0D;gBAC1D,OAAO;QACX,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAsB;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;YAC/B,IAAI,EAAE,UAAU;YAChB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,MAAM,EAAE,IAAI,CAAC,EAAE;SAChB,CAAC,CAAC;QACH,qEAAqE;QACrE,yEAAyE;QACzE,sEAAsE;QACtE,wDAAwD;QACxD,OAAO,CAAC,WAAW,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3E,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACxE,MAAM,OAAO,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,SAA6B;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAE/B,IAAI,CAAC,uBAAuB,CAAC,GAAG,EAAE;YAChC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,SAAS,EAAE,CAAC;gBACvC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAEpD,MAAM,IAAI,CAAC,WAAW,CAAC;YACrB,IAAI,EAAE,SAAS;YACf,SAAS;YACT,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,0BAA0B,CAAC,MAAc;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1C,MAAM,IAAI,CAAC,WAAW,CAAC;YACrB,IAAI,EAAE,4BAA4B;YAClC,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,MAAM;SACP,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QACpC,IAAI,KAAK,CAAC,sBAAsB,KAAK,sBAAsB,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACtF,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,aAAa,CAAC,OAA6B;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1C,OAAO,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE;YACrC,MAAM,EAAE,IAAI;YACZ,GAAG,CAAC,IAAI,CAAC,iBAAiB,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE;gBAC/C,CAAC,CAAC,EAAE,CAAC;YACP,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,iBAAiB;QACf,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,+FAA+F;IAC/F,KAAK;QACH,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB;QACrB,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACnE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAE,CAAC;gBACtC,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBACnC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;gBAC5B,CAAC;gBAAC,MAAM,CAAC;oBACP,uEAAuE;oBACvE,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,6BAA6B;IAC7B,2BAA2B;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;IAClC,CAAC;IAEO,cAAc,CAAC,OAAmC,EAAE,KAAa;QACvE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;QAC9B,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC;IAEO,uBAAuB,CAAC,QAAoB;QAClD,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QACtB,QAAQ,EAAE,CAAC;IACb,CAAC;IAEO,kBAAkB,CAAC,OAAsB;QAC/C,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC;YAClD,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,OAAsB;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACnC,KAAK,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,4BAA4B,OAAO,CAAC,IAAI,iCAAiC,CAAC,CAAC;QACvF,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IAEO,uBAAuB,CAAC,WAAmB,EAAE,QAAgB;QACnE,IAAI,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO;QAEtD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CACtC,GAAG,EAAE;YACH,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC7C,KAAK,IAAI,CAAC,WAAW,CAAC;gBACpB,IAAI,EAAE,wBAAwB;gBAC9B,WAAW;aACZ,CAAC,CAAC;QACL,CAAC,EACD,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAC1C,CAAC;QAEF,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAEO,wBAAwB,CAAC,WAAmB;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QACjC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IAEO,wBAAwB;QAC9B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,EAAE,CAAC;YACvD,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;IAEO,kBAAkB;QACxB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,iBAAiB,CAAC,wBAAwB,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,IAAI,CAAC,KAA6B;QACxC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/vendor/core/dist/engine/PairingEngine.d.ts

@@ -0,0 +1,92 @@
+import type { ClientMessage, ServerMessage } from '@userflow-tech/protocol';
+import { PairingConnection, type PairingConnectionOptions } from '../transport/pairing.js';
+export type PairingEngineStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'token_expired' | 'device_already_paired' | 'error';
+export interface PairingEngineState {
+    status: PairingEngineStatus;
+    pairingId: string | null;
+    deviceId: string | null;
+    previewActive: boolean;
+    lastError: string | null;
+    /** True when a re-scan is required (expired token or hard failure). */
+    needsRescan: boolean;
+    /**
+     * True while the server waits for the previewed flow's start condition to
+     * match (the `TestStartCondition` preview mode). The preview is live but the
+     * flow has not appeared yet, which is otherwise indistinguishable from a
+     * condition that never fires.
+     */
+    awaitingStartCondition: boolean;
+}
+export type PairingEngineListener = (state: PairingEngineState) => void;
+export interface PairingEngineDeps {
+    /** Send a client message on the end-user channel (after identify). */
+    sendClientMessage: (message: ClientMessage) => Promise<void>;
+    /**
+     * Subscribe to inbound end-user server messages, returning an unsubscribe.
+     * Only used to notice `TestStartConditionSuccess`. Subscribed lazily because
+     * the end-user channel does not exist until identify, while pairing starts
+     * before it.
+     */
+    onServerMessage?: (handler: (message: ServerMessage) => void) => () => void;
+    /** Whether an end-user identity is currently active. */
+    isIdentified: () => boolean;
+    /** Optional device metadata included on pairing join. */
+    deviceMeta?: () => {
+        model?: string;
+        os?: string;
+        app_version?: string;
+    };
+    pairingOptions?: PairingConnectionOptions;
+    createConnection?: (options: PairingConnectionOptions) => PairingConnection;
+}
+/**
+ * Orchestrates a pairing session: connect/join the pairing socket, bridge
+ * `startFlowWithToken` onto the end-user channel, and expose preview-mode state.
+ */
+export declare class PairingEngine {
+    private connection;
+    private unsubscribe;
+    private state;
+    private readonly listeners;
+    private pendingStartTokens;
+    /** True while the server is waiting on a start condition (see TestStartCondition). */
+    private testingStartCondition;
+    private startConditionUnsub;
+    private readonly deps;
+    constructor(deps: PairingEngineDeps);
+    getState(): PairingEngineState;
+    isPreviewActive(): boolean;
+    onStateChange(listener: PairingEngineListener): () => void;
+    /**
+     * Begin (or replace) a pairing session with a JWT from a deep link.
+     * Closes any existing pairing websocket first (warm re-scan).
+     */
+    start(pairingToken: string): Promise<void>;
+    /** Exit preview: disconnect pairing and clear queued preview tokens. */
+    stop(): void;
+    /**
+     * Listen for the server confirming the tested start condition matched. Called
+     * only after a `TestStartCondition` send succeeded, which means the end-user
+     * channel exists and subscribing is safe.
+     */
+    private watchStartCondition;
+    private unwatchStartCondition;
+    /**
+     * The tested start condition matched, so the flow is now on screen. Stops the
+     * waiting state and makes `stop()` skip a cancel the server no longer needs.
+     */
+    private notifyStartConditionMatched;
+    /**
+     * Call after end-user identify so queued `startFlowWithToken` relays can flush.
+     */
+    notifyIdentified(): void;
+    ensureAlive(): void;
+    private handleConnectionEvent;
+    private handleStartFlowWithToken;
+    private flushPendingStartTokens;
+    private deliverStartFlowWithToken;
+    private pushStartResult;
+    private teardownConnection;
+    private setState;
+}
+//# sourceMappingURL=PairingEngine.d.ts.map

package/vendor/core/dist/engine/PairingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PairingEngine.d.ts","sourceRoot":"","sources":["../../src/engine/PairingEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAEd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,iBAAiB,EAEjB,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,eAAe,GACf,uBAAuB,GACvB,OAAO,CAAC;AAEZ,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,iBAAiB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,wDAAwD;IACxD,YAAY,EAAE,MAAM,OAAO,CAAC;IAC5B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,iBAAiB,CAAC;CAC7E;AAYD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAC9D,OAAO,CAAC,kBAAkB,CAAwC;IAClE,sFAAsF;IACtF,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;gBAE7B,IAAI,EAAE,iBAAiB;IAInC,QAAQ,IAAI,kBAAkB;IAI9B,eAAe,IAAI,OAAO;IAI1B,aAAa,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAO1D;;;OAGG;IACG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0ChD,wEAAwE;IACxE,IAAI,IAAI,IAAI;IAgBZ;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,qBAAqB;IAK7B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAOnC;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAIxB,WAAW,IAAI,IAAI;IAInB,OAAO,CAAC,qBAAqB;YAqEf,wBAAwB;YA0BxB,uBAAuB;YASvB,yBAAyB;YA+BzB,eAAe;IAiB7B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,QAAQ;CAUjB"}