@polymorfa/sdk 0.1.0-dev.20260922093854

package/dist/calls/call.js

@@ -0,0 +1,860 @@
+import { CallReporter } from "./diagnostics.js";
+import { CallClaimedError, CallsAuthError, CallsError } from "./errors.js";
+import { Emitter } from "./events.js";
+import { MediaSocket, } from "./media.js";
+import { createConnectionId, isConnectionId, } from "./protocol.js";
+function videoSource(source) {
+    if (source.participant !== undefined)
+        return {
+            id: source.source,
+            label: source.participant.phoneNumber ?? source.participant.id,
+            participant: source.participant,
+        };
+    return {
+        id: source.source,
+        label: source.connectionParticipant ?? source.connectionId,
+        connectionId: source.connectionId,
+        ...(source.connectionParticipant === undefined
+            ? {}
+            : { connectionParticipant: source.connectionParticipant }),
+    };
+}
+/**
+ * The call's merged audio as signed 16-bit mono PCM samples at
+ * {@link sampleRate}: `on("data")` is the call → you, `write()` is you → the call.
+ */
+export class AudioTrack extends Emitter {
+    #socket;
+    #sampleRate;
+    constructor(sampleRate) {
+        super();
+        this.#sampleRate = sampleRate;
+    }
+    /** s16le mono PCM rate both directions use. Final once the call is connected. */
+    get sampleRate() {
+        return this.#sampleRate;
+    }
+    /** Push s16le mono PCM at {@link sampleRate}. Returns false when no media is attached. */
+    write(pcm) {
+        return this.#socket?.writeAudio(pcm) ?? false;
+    }
+    /** @internal */
+    _attach(socket, sampleRate) {
+        this.#socket = socket;
+        if (sampleRate !== undefined)
+            this.#sampleRate = sampleRate;
+    }
+    /** @internal */
+    _push(pcm) {
+        this.emit("data", pcm);
+    }
+    /** @internal */
+    _detach() {
+        this.#socket = undefined;
+        this.removeAllListeners();
+    }
+}
+/**
+ * The call's video: one outgoing H.264 stream, and one received stream per
+ * remote participant. Streams are separate; nothing is composed.
+ */
+export class VideoTrack extends Emitter {
+    #socket;
+    #sources = new Map();
+    /** Remote participant videos by `id`. */
+    get sources() {
+        return this.#sources;
+    }
+    /** Send one encoded frame. Returns false when no media is attached. */
+    write(frame) {
+        return (this.#socket?.writeVideo({
+            keyframe: frame.keyframe,
+            timestampUs: frame.timestampUs,
+            data: frame.data,
+        }) ?? false);
+    }
+    /** @internal */
+    _attach(socket) {
+        this.#socket = socket;
+    }
+    /** @internal */
+    _frame(frame) {
+        this.emit("frame", {
+            source: frame.source,
+            keyframe: frame.keyframe,
+            timestampUs: frame.timestampUs,
+            data: frame.data,
+        });
+    }
+    /** @internal */
+    _source(source) {
+        const neutral = videoSource(source);
+        this.#sources.set(neutral.id, neutral);
+        this.emit("source", neutral);
+    }
+    /** @internal */
+    _sourceRemoved(handle) {
+        if (!this.#sources.delete(handle))
+            return;
+        this.emit("sourceRemoved", handle);
+    }
+    /** @internal */
+    _clearSources() {
+        for (const handle of [...this.#sources.keys()])
+            this._sourceRemoved(handle);
+    }
+    /** @internal */
+    _keyframeRequest() {
+        this.emit("keyframeRequest");
+    }
+    /** @internal */
+    _detach() {
+        this.#socket = undefined;
+        this.#sources.clear();
+        this.removeAllListeners();
+    }
+}
+export const DEFAULT_CALL_CAPABILITIES = Object.freeze({
+    video: true,
+    invite: true,
+});
+/**
+ * Read platform-reported capabilities, keeping `fallback` (the defaults
+ * unless given) for absent or malformed fields.
+ */
+export function capabilitiesFrom(value, fallback = DEFAULT_CALL_CAPABILITIES) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return fallback;
+    const reported = value;
+    return {
+        video: typeof reported["video"] === "boolean"
+            ? reported["video"]
+            : fallback.video,
+        invite: typeof reported["invite"] === "boolean"
+            ? reported["invite"]
+            : fallback.invite,
+    };
+}
+/** Upper bound on the platform release after a local media failure. */
+const RELEASE_TIMEOUT_MS = 5_000;
+/**
+ * One call. Created by the client for every inbound `call.received` and every
+ * successful `place()`. Lifecycle transitions arrive from the client's socket;
+ * media arrives on this call's own connection once accepted.
+ */
+export class Call extends Emitter {
+    id;
+    session;
+    direction;
+    peer;
+    /** True when the call offered video and the call can carry it. */
+    get hasVideo() {
+        return this.#offeredVideo && this.#capabilities.video;
+    }
+    /**
+     * What this call supports. An outbound call starts with the defaults and
+     * takes the platform's report from `call.accepted` (`capabilities` event).
+     */
+    get capabilities() {
+        return this.#capabilities;
+    }
+    #offeredVideo;
+    #capabilities;
+    /** This client's media connection id; reused on reconnect. */
+    connectionId;
+    audio;
+    video;
+    #api;
+    #mediaOptions;
+    #participant;
+    #self;
+    #now;
+    #reconnectAttempts;
+    #participants = new Map();
+    #departedParticipants = new Set();
+    #participantRevisions = new Map();
+    #rosterRevision = 0;
+    #state;
+    #media;
+    #endReason;
+    #startedAt;
+    #connectedAt;
+    #endedAt;
+    /** The in-flight answer or join, through media attachment. */
+    #accepting;
+    /** The in-flight accept request alone, without media attachment. */
+    #acceptRequest;
+    /** This client's accept succeeded. */
+    #accepted = false;
+    #answered = false;
+    #answeredBy;
+    #exclusive = false;
+    #claimedByOther = false;
+    /** This client claimed the call: its own answer, or an exclusive placement. */
+    #claimedByUs = false;
+    #reconnectTimer;
+    #externalMedia;
+    #reporter;
+    /** Media attached at least once, so there is a connection to report on. */
+    #mediaAttached = false;
+    /** Successful media reattachments of this connection. */
+    #reconnects = 0;
+    #mediaReady = false;
+    constructor(init) {
+        super();
+        this.id = init.id;
+        this.session = init.session;
+        this.direction = init.direction;
+        this.peer = init.peer;
+        this.#capabilities = init.capabilities ?? DEFAULT_CALL_CAPABILITIES;
+        this.#offeredVideo = init.video;
+        if (init.connectionId !== undefined && !isConnectionId(init.connectionId))
+            throw new CallsError("invalid_connection_id", "connectionId must be 8–64 characters of A–Z, a–z, 0–9, _ or -.");
+        this.connectionId = init.connectionId ?? createConnectionId();
+        this.#api = init.api;
+        this.#mediaOptions = init.media;
+        this.#participant = init.participant;
+        this.#self = init.self ?? (() => undefined);
+        this.#externalMedia = init.mediaMode === "external";
+        const report = init.api.report;
+        this.#reporter =
+            init.diagnostics === undefined ||
+                this.#externalMedia ||
+                report === undefined
+                ? undefined
+                : new CallReporter({
+                    connectionId: this.connectionId,
+                    client: init.diagnostics,
+                    ...(init.now === undefined ? {} : { now: init.now }),
+                    send: (body) => report.call(init.api, this.id, {
+                        ...body,
+                        ...(init.participant === undefined
+                            ? {}
+                            : { participant: init.participant }),
+                    }),
+                });
+        this.#reconnectAttempts = init.reconnectAttempts ?? 3;
+        this.#now = init.now ?? Date.now;
+        this.#state = init.direction === "inbound" ? "incoming" : "ringing";
+        this.#startedAt = this.#now();
+        this.audio = new AudioTrack(16_000);
+        this.video = new VideoTrack();
+        // The placing participant owns an outbound call.
+        if (init.direction === "outbound") {
+            this.#accepted = true;
+            this.#claimedByUs = init.exclusive === true;
+        }
+    }
+    get state() {
+        return this.#state;
+    }
+    get ended() {
+        return this.#state === "ended";
+    }
+    get endReason() {
+        return this.#endReason;
+    }
+    get startedAt() {
+        return this.#startedAt;
+    }
+    get connectedAt() {
+        return this.#connectedAt;
+    }
+    /** Seconds of connected time; frozen at the end so a retained call stops counting. */
+    get duration() {
+        if (this.#connectedAt === undefined)
+            return 0;
+        const until = this.#endedAt ?? this.#now();
+        return Math.max(0, Math.floor((until - this.#connectedAt) / 1000));
+    }
+    get endedAt() {
+        return this.#endedAt;
+    }
+    get participants() {
+        return [...this.#participants.values()];
+    }
+    /** Answer and claim state, as last reported by the platform. */
+    get claim() {
+        return {
+            answered: this.#answered,
+            ...(this.#answeredBy === undefined
+                ? {}
+                : { answeredBy: this.#answeredBy }),
+            exclusive: this.#exclusive,
+            claimedByOther: this.claimedByOther,
+            canJoin: this.canJoin,
+        };
+    }
+    /**
+     * @internal This client holds the claim: its own exclusive answer, or a
+     * placement with `exclusive: true`. Media adapters end such a call, rather
+     * than leave it, when its media fails.
+     */
+    get _claimedBySelf() {
+        return this.#claimedByUs;
+    }
+    get claimedByOther() {
+        return this.#claimedByOther && !this.#accepted && !this.ended;
+    }
+    get canJoin() {
+        return (this.#state === "incoming" &&
+            this.#answered &&
+            !this.#exclusive &&
+            !this.#claimedByOther);
+    }
+    /**
+     * Answer a ringing call and attach media. With `exclusive: true` the call
+     * is claimed: other participants stop ringing and cannot join. Resolves
+     * once media is connected (after acceptance for external media). Rejects
+     * with {@link CallClaimedError} when another participant claimed the call;
+     * the call then stays visible as `claimedByOther`.
+     */
+    answer(options = {}) {
+        return this.#accept({
+            exclusive: options.exclusive === true,
+            video: options.video ?? this.hasVideo,
+        });
+    }
+    /**
+     * Join a call another participant answered without claiming it. Never
+     * claims. Rejects with {@link CallClaimedError} when the call is claimed.
+     */
+    join(options = {}) {
+        if (!this.#answered && this.#state === "incoming")
+            return Promise.reject(new CallsError("call_not_answered", "Nobody has answered this call yet; answer it instead."));
+        return this.#accept({
+            exclusive: false,
+            video: options.video ?? this.hasVideo,
+        });
+    }
+    #accept(options) {
+        // A concurrent answer or join settles with the attempt already running,
+        // so it also waits for media and fails if media fails.
+        if (this.#accepting !== undefined)
+            return this.#accepting;
+        if (this.#state !== "incoming")
+            return Promise.reject(new CallsError("invalid_state", `Cannot answer a call in state "${this.#state}".`));
+        if (this.claimedByOther)
+            return Promise.reject(new CallClaimedError());
+        let accepted = false;
+        const accepting = (async () => {
+            this.#transition("connecting");
+            const result = await this.#api.accept(this.id, {
+                exclusive: options.exclusive,
+                video: options.video,
+                ...(this.#participant === undefined
+                    ? {}
+                    : { participant: this.#participant }),
+            });
+            accepted = true;
+            this.#accepted = true;
+            this.#claimedByUs = result.exclusive;
+            this.#applyClaim({
+                answered: result.answered,
+                answeredBy: result.answeredBy,
+                exclusive: result.exclusive,
+            });
+        })();
+        const run = accepting
+            .then(() => this.#bridge())
+            .catch(async (cause) => {
+            this.#accepting = undefined;
+            if (this.#state === "ended")
+                throw cause;
+            if (!accepted) {
+                // The accept itself was refused: nothing changed on the platform.
+                if (cause instanceof CallClaimedError) {
+                    this.#claimedByOther = true;
+                    this.#applyClaim({ answered: true, exclusive: true });
+                }
+                this.#transition("incoming");
+                throw cause;
+            }
+            this.#reportFailure(cause);
+            await this.#release(cause);
+            this.#mediaFailed(cause);
+            throw cause;
+        });
+        this.#accepting = run;
+        this.#acceptRequest = accepting;
+        void accepting
+            .finally(() => {
+            if (this.#acceptRequest === accepting)
+                this.#acceptRequest = undefined;
+        })
+            .catch(() => undefined);
+        // Once settled, later answer() and join() calls check the call's state
+        // again instead of reusing this result. Failures already clear it above.
+        void run.then(() => {
+            if (this.#accepting === run)
+                this.#accepting = undefined;
+        }, () => undefined);
+        return run;
+    }
+    /**
+     * Decline a ringing call. This ends the call for every participant, so
+     * applications decide when to call it; the client never declines on its own.
+     */
+    async reject() {
+        if (this.#state !== "incoming")
+            throw new CallsError("invalid_state", `Cannot reject a call in state "${this.#state}".`);
+        if (this.#answered)
+            throw new CallsError("call_not_ringing", "The call is already answered. Join it or leave it; declining is not possible.");
+        await this.#api.reject(this.id, undefined, this.#participant);
+        this.#end("rejected");
+    }
+    /**
+     * Leave the call: close this client's media connection. The call continues
+     * for everyone else. On a call this client never joined, only local
+     * tracking stops.
+     */
+    async leave() {
+        if (this.#state === "ended")
+            return;
+        // Nobody else is on a placed call the remote party has not answered, so
+        // leaving it would keep that party ringing with no way to stop it.
+        if (this.direction === "outbound" && this.#state === "ringing") {
+            await this.end();
+            return;
+        }
+        // An accept still in flight may yet succeed and put this client on the
+        // call (possibly with a claim); wait for it, so a successful one is left
+        // on the platform too instead of only dropped here.
+        const acceptRequest = this.#acceptRequest;
+        if (!this.#accepted && acceptRequest !== undefined) {
+            await acceptRequest.catch(() => undefined);
+            if (this.ended)
+                return;
+        }
+        const attached = this.#accepted;
+        const media = this.#media;
+        // A refused request leaves the call live so it can be retried; the local
+        // model only goes terminal once this client is really out of the call.
+        if (attached && !(media?.leave() ?? false))
+            await this.#api.leave(this.id, this.connectionId, undefined, this.#participant);
+        this.#end("left");
+    }
+    /** End the call for every participant. Idempotent. */
+    async end() {
+        if (this.#state === "ended")
+            return;
+        await this.#api.end(this.id);
+        this.#end("hangup");
+    }
+    /** Invite another party, turning a 1:1 call into a group call. */
+    async addParticipant(to) {
+        if (this.#state === "ended")
+            throw new CallsError("invalid_state", "Cannot add a participant to an ended call.");
+        const requestedAtRevision = this.#rosterRevision;
+        const participant = await this.#api.addParticipant(this.id, to);
+        // The lifecycle stream may move this participant forward, or report it
+        // left, while the request is in flight. Its acknowledgement is then older
+        // than the roster and must not overwrite or restore that entry.
+        if ((this.#participantRevisions.get(participant.id) ?? 0) <=
+            requestedAtRevision)
+            this.#applyInviteReply(participant);
+        return participant;
+    }
+    /**
+     * @internal `call.accepted` arrived. For an outbound call the remote party
+     * answered; for an inbound call it names who answered and whether they
+     * claimed it.
+     */
+    async _remoteAccepted(claim = {}) {
+        if (!this.ended &&
+            claim.capabilities !== undefined &&
+            (claim.capabilities.video !== this.#capabilities.video ||
+                claim.capabilities.invite !== this.#capabilities.invite)) {
+            this.#capabilities = Object.freeze({ ...claim.capabilities });
+            this.emit("capabilities", this.#capabilities);
+        }
+        if (this.direction === "outbound") {
+            if (this.#state !== "ringing")
+                return;
+            // The remote party answered. A placement with `exclusive: true` holds
+            // the claim even when the event does not repeat it.
+            this.#applyClaim({
+                answered: true,
+                ...(claim.answeredBy === undefined
+                    ? {}
+                    : { answeredBy: claim.answeredBy }),
+                exclusive: claim.exclusive === true || this.#claimedByUs,
+            });
+            this.#transition("connecting");
+            try {
+                await this.#bridge();
+            }
+            catch (cause) {
+                this.#reportFailure(cause);
+                await this.#release(cause);
+                this.#mediaFailed(cause);
+            }
+            return;
+        }
+        if (this.ended)
+            return;
+        const exclusive = claim.exclusive === true;
+        const answeredBy = claim.answeredBy;
+        const self = this.#self();
+        const byUs = answeredBy !== undefined && self !== undefined && answeredBy === self;
+        if (exclusive && !byUs && !this.#accepted && this.#accepting === undefined)
+            this.#claimedByOther = true;
+        this.#applyClaim({
+            answered: true,
+            ...(answeredBy === undefined ? {} : { answeredBy }),
+            exclusive,
+        });
+    }
+    /** @internal The platform reported the call over. */
+    _remoteEnded(reason) {
+        this.#end(reason);
+    }
+    /** @internal Apply a validated participant update from either transport. */
+    _remoteParticipant(frame) {
+        if (this.ended)
+            return;
+        const participantId = frame.type === "participant_left"
+            ? frame.participantId
+            : frame.participant.id;
+        this.#rosterRevision += 1;
+        this.#participantRevisions.set(participantId, this.#rosterRevision);
+        this.#applyParticipant(frame);
+    }
+    /**
+     * @internal Media owned by another Polymorfa package connected. An outbound
+     * call still waits for the remote party to accept. Socket media ignores this.
+     */
+    mediaConnected() {
+        if (!this.#externalMedia || this.ended)
+            return;
+        this.#mediaReady = true;
+        if (this.#state !== "connecting")
+            return;
+        this.#connectedAt = this.#now();
+        this.#transition("connected");
+        this.emit("connected");
+    }
+    #applyClaim(next) {
+        const before = this.claim;
+        this.#answered = this.#answered || next.answered;
+        if (next.answeredBy !== undefined)
+            this.#answeredBy = next.answeredBy;
+        this.#exclusive = next.exclusive;
+        const after = this.claim;
+        if (before.answered !== after.answered ||
+            before.answeredBy !== after.answeredBy ||
+            before.exclusive !== after.exclusive ||
+            before.claimedByOther !== after.claimedByOther ||
+            before.canJoin !== after.canJoin)
+            this.emit("claim", after);
+    }
+    #applyInviteReply(participant) {
+        if (this.ended)
+            return;
+        const previous = this.#participants.get(participant.id);
+        if (previous !== undefined &&
+            participantStateRank(participant.state) <
+                participantStateRank(previous.state))
+            return;
+        if (previous !== undefined && sameParticipant(previous, participant))
+            return;
+        this.#rosterRevision += 1;
+        this.#participantRevisions.set(participant.id, this.#rosterRevision);
+        this.#applyParticipant({ type: "participant_joined", participant });
+    }
+    #applyParticipant(frame) {
+        if (this.ended)
+            return;
+        if (frame.type === "participant_left") {
+            if (this.#departedParticipants.has(frame.participantId))
+                return;
+            this.#departedParticipants.add(frame.participantId);
+            this.#participants.delete(frame.participantId);
+            this.emit("participantLeft", frame.participantId, frame.reason);
+            return;
+        }
+        const participant = frame.participant;
+        if (participant.state === "left") {
+            this.#applyParticipant({
+                type: "participant_left",
+                participantId: participant.id,
+            });
+            return;
+        }
+        this.#departedParticipants.delete(participant.id);
+        const previous = this.#participants.get(participant.id);
+        if (previous !== undefined && sameParticipant(previous, participant))
+            return;
+        this.#participants.set(participant.id, participant);
+        if (previous === undefined)
+            this.emit("participantJoined", participant);
+        else
+            this.emit("participantState", participant);
+    }
+    #mediaFailed(cause) {
+        if (this.ended)
+            return;
+        // The platform accepted; only our media failed. End this client's view
+        // of the call and say why.
+        this.emit("error", cause instanceof CallsError
+            ? cause
+            : new CallsError("media_failed", cause instanceof Error ? cause.message : "Media could not attach.", { cause }));
+        this.#end(cause instanceof CallClaimedError ? "claimed" : "connection_failed");
+    }
+    async #bridge() {
+        if (this.#externalMedia) {
+            if (this.#mediaReady)
+                this.mediaConnected();
+            return;
+        }
+        const ready = await this.#attach(false);
+        if (ready === undefined)
+            return;
+        this.#connectedAt = this.#now();
+        this.#transition("connected");
+        this.emit("connected");
+    }
+    /** Open one media socket with this call's connection id. */
+    async #attach(refreshToken) {
+        if (this.ended)
+            throw new CallsError("call_ended", "Call ended before media attached.");
+        const media = new MediaSocket({
+            ...this.#mediaOptions,
+            api: this.#api,
+            callId: this.id,
+            connectionId: this.connectionId,
+            ...(this.#participant === undefined
+                ? {}
+                : { participant: this.#participant }),
+            refreshToken,
+        });
+        this.#media = media;
+        media.on("audio", (pcm) => this.audio._push(pcm));
+        media.on("video", (frame) => this.video._frame(frame));
+        media.on("videoSource", (source) => this.video._source(source));
+        media.on("videoSourceRemoved", (handle) => this.video._sourceRemoved(handle));
+        media.on("keyframeRequest", () => this.video._keyframeRequest());
+        media.on("participantJoined", (participant) => this._remoteParticipant({ type: "participant_joined", participant }));
+        media.on("participantState", (participant) => this._remoteParticipant({ type: "participant_state", participant }));
+        media.on("participantLeft", (participantId, reason) => this._remoteParticipant({
+            type: "participant_left",
+            participantId,
+            ...(reason === undefined ? {} : { reason }),
+        }));
+        media.on("error", (error) => this.emit("error", error));
+        let ready;
+        const readyListener = (value) => {
+            ready = value;
+        };
+        media.once("ready", readyListener);
+        let attached = false;
+        media.on("close", (close) => {
+            if (attached)
+                this.#mediaClosed(media, close);
+        });
+        try {
+            await media.connect();
+        }
+        catch (cause) {
+            if (this.#media === media)
+                this.#media = undefined;
+            media.close();
+            throw cause;
+        }
+        if (this.ended || this.#media !== media) {
+            media.close();
+            return undefined;
+        }
+        if (!media.connected) {
+            // Closed between `ready` and this continuation.
+            this.#media = undefined;
+            throw new CallsError("media_closed", "Media connection closed.");
+        }
+        attached = true;
+        this.#mediaAttached = true;
+        this.audio._attach(media, ready?.sampleRate ?? media.sampleRate);
+        this.video._attach(media);
+        return ready;
+    }
+    #mediaClosed(media, close) {
+        if (this.#media !== media || this.ended)
+            return;
+        this.#media = undefined;
+        this.audio._attach(undefined);
+        this.video._attach(undefined);
+        this.video._clearSources();
+        switch (close.reason) {
+            case "local":
+                return;
+            case "left":
+                this.#end("left");
+                return;
+            case "ended":
+                this.#end("remote_hangup");
+                return;
+            case "claimed":
+                this.#end("claimed");
+                return;
+            case "refused":
+                this.#reporter?.error("other");
+                void this.#failAfterRelease(new CallsError("media_refused", "The platform refused the media connection."));
+                return;
+            case "unauthorized":
+            case "lost":
+                this.#reconnect(close.reason === "unauthorized", 0);
+                return;
+        }
+    }
+    #reconnect(refreshToken, attempt) {
+        if (this.ended)
+            return;
+        if (attempt >= this.#reconnectAttempts) {
+            this.#reporter?.error(refreshToken ? "token_refresh_failed" : "reconnect_exhausted");
+            void this.#failAfterRelease(refreshToken
+                ? new CallsAuthError()
+                : new CallsError("media_lost", "Media connection lost."));
+            return;
+        }
+        this.#transition("reconnecting");
+        const delay = Math.min(8_000, 1_000 * 2 ** attempt);
+        this.#reconnectTimer = (this.#mediaOptions.setTimeout ?? setTimeout)(() => {
+            this.#reconnectTimer = undefined;
+            void this.#attach(refreshToken).then((ready) => {
+                if (ready === undefined || this.ended)
+                    return;
+                this.#reconnects += 1;
+                this.#transition("connected");
+            }, (cause) => {
+                if (this.ended)
+                    return;
+                if (cause instanceof CallClaimedError) {
+                    this.#end("claimed");
+                    return;
+                }
+                if (!retryable(cause)) {
+                    // Refused or no longer available: reattaching cannot help.
+                    this.#reportFailure(cause);
+                    void this.#failAfterRelease(cause instanceof CallsError
+                        ? cause
+                        : new CallsError("media_failed", "Media could not attach."));
+                    return;
+                }
+                this.#reconnect(cause instanceof CallsAuthError || refreshToken, attempt + 1);
+            });
+        }, delay);
+    }
+    /**
+     * The platform still counts this client as on the call after its media
+     * failed. Release it before the call becomes terminal here, so the remote
+     * party is not left on a call nobody controls: end a call this client
+     * claimed (nobody else can take it over), otherwise leave with this
+     * connection. A claim by someone else needs nothing. Bounded by
+     * RELEASE_TIMEOUT_MS; failures are swallowed so the media error stays the
+     * one reported. External media adapters release the call themselves.
+     */
+    async #release(cause) {
+        if (this.ended || !this.#accepted || this.#externalMedia)
+            return;
+        if (cause instanceof CallClaimedError)
+            return;
+        const abort = new AbortController();
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = (this.#mediaOptions.setTimeout ?? setTimeout)(() => {
+                abort.abort();
+                resolve();
+            }, RELEASE_TIMEOUT_MS);
+        });
+        const request = this.#claimedByUs
+            ? this.#api.end(this.id, abort.signal)
+            : this.#api.leave(this.id, this.connectionId, abort.signal, this.#participant);
+        try {
+            await Promise.race([request.catch(() => undefined), timeout]);
+        }
+        finally {
+            (this.#mediaOptions.clearTimeout ?? clearTimeout)(timer);
+        }
+    }
+    /**
+     * Report why media failed. Claims by another participant are not a media
+     * failure; causes without a closer code are `other`.
+     */
+    #reportFailure(cause) {
+        if (this.#reporter === undefined || cause instanceof CallClaimedError)
+            return;
+        this.#reporter.error(cause instanceof CallsAuthError ||
+            (cause instanceof CallsError && cause.code === "token_failed")
+            ? "token_refresh_failed"
+            : cause instanceof CallsError && cause.code === "media_timeout"
+                ? "media_timeout"
+                : "other");
+    }
+    /** Release the call on the platform, then report `error` and end here. */
+    async #failAfterRelease(error) {
+        await this.#release();
+        if (this.ended)
+            return;
+        this.emit("error", error);
+        this.#end("connection_failed");
+    }
+    #transition(next) {
+        const previous = this.#state;
+        if (previous === next)
+            return;
+        this.#state = next;
+        this.emit("state", next, previous);
+    }
+    #end(reason) {
+        if (this.#state === "ended")
+            return;
+        this.#endReason = reason;
+        this.#endedAt = this.#now();
+        if (this.#reconnectTimer !== undefined) {
+            (this.#mediaOptions.clearTimeout ?? clearTimeout)(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+        this.#transition("ended");
+        // The connection's final figure: how often it reconnected. Only real
+        // measurements are sent, and socket media measures nothing else.
+        if (this.#mediaAttached)
+            this.#reporter?.quality({ reconnects: this.#reconnects }, true);
+        this.#reporter?.stop();
+        const media = this.#media;
+        this.#media = undefined;
+        media?.close();
+        this.audio._detach();
+        this.video._detach();
+        this.emit("ended", reason);
+        this.removeAllListeners();
+    }
+}
+/** Whether a failed reattach is worth another attempt. */
+function retryable(cause) {
+    if (cause instanceof CallsAuthError)
+        return true;
+    if (!(cause instanceof CallsError))
+        return true;
+    return ["media_closed", "media_timeout", "token_failed"].includes(cause.code);
+}
+function participantStateRank(state) {
+    switch (state) {
+        case "invited":
+            return 0;
+        case "ringing":
+            return 1;
+        case "connected":
+            return 2;
+        case "left":
+            return 3;
+    }
+}
+function sameParticipant(a, b) {
+    return (a.id === b.id &&
+        a.phoneNumber === b.phoneNumber &&
+        a.bsuid === b.bsuid &&
+        a.username === b.username &&
+        a.audioMuted === b.audioMuted &&
+        a.video === b.video &&
+        a.state === b.state);
+}
+//# sourceMappingURL=call.js.map