@polymorfa/sdk 0.1.0-dev.20260922093854

package/dist/calls/media.js

@@ -0,0 +1,414 @@
+import { CallClaimedError, CallsAuthError, CallsDisabledError, CallsError, } from "./errors.js";
+import { Emitter } from "./events.js";
+import { AUTH_FAILED_CLOSE_CODE, DEFAULT_SAMPLE_RATE, MEDIA_SUBPROTOCOL, decodeMediaFrame, encodeAudioFrame, encodeVideoFrame, mediaSocketPath, parseMediaControl, } from "./protocol.js";
+import { isClientToken } from "./token.js";
+/**
+ * Close code for a call-state refusal. With the reason "call claimed" (or a
+ * preceding `call_claimed` error frame) another participant claimed the call;
+ * otherwise the call is not available (ended or not ready).
+ */
+export const CALL_CLAIMED_CLOSE_CODE = 4409;
+/** Close code for a connection refused because calling is turned off. */
+export const CALLS_DISABLED_CLOSE_CODE = 4403;
+/** Close codes after which reattaching can succeed. */
+const RETRYABLE_CLOSE_CODES = new Set([1001, 1006, 1011, 1012, 1013, 4429]);
+/**
+ * One media connection to a call: tagged binary frames for audio and video,
+ * JSON text frames for control. The first frame authenticates the
+ * connection. A socket does not reconnect by itself; the call opens a new one
+ * with the same connection id.
+ */
+export class MediaSocket extends Emitter {
+    #o;
+    #WS;
+    #socket;
+    #beat;
+    #awaitingPong = false;
+    #sampleRate = DEFAULT_SAMPLE_RATE;
+    #closed = false;
+    #ready = false;
+    #intent;
+    #claimed = false;
+    /** The last error frame before `ready`; the close that follows explains it. */
+    #refusal;
+    #pending;
+    #connecting;
+    constructor(options) {
+        super();
+        this.#o = options;
+        const WS = options.WebSocket ?? globalThis.WebSocket;
+        if (WS === undefined)
+            throw new Error("No WebSocket implementation: pass `WebSocket` (Node < 22) or run on Node 22+.");
+        this.#WS = WS;
+    }
+    get connectionId() {
+        return this.#o.connectionId;
+    }
+    /** The PCM rate in force; updated from the platform's `ready` frame. */
+    get sampleRate() {
+        return this.#sampleRate;
+    }
+    get connected() {
+        return (this.#ready &&
+            this.#socket !== undefined &&
+            this.#socket.readyState === this.#WS.OPEN);
+    }
+    /**
+     * Authenticate and attach; resolves when the platform reports `ready`.
+     * Rejects with {@link CallClaimedError} or {@link CallsAuthError} when the
+     * platform refuses the connection for those reasons.
+     */
+    connect() {
+        if (this.#closed)
+            return Promise.reject(new Error("Media socket is closed."));
+        if (this.#connecting !== undefined)
+            return this.#connecting;
+        if (this.#socket !== undefined)
+            return Promise.resolve();
+        const attempt = new Promise((resolve, reject) => {
+            const readyMs = this.#o.readyTimeoutMs ?? 10_000;
+            let readyTimer;
+            let settled = false;
+            const done = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (readyTimer !== undefined) {
+                    (this.#o.clearTimeout ?? clearTimeout)(readyTimer);
+                    readyTimer = undefined;
+                }
+                if (this.#pending === done)
+                    this.#pending = undefined;
+                this.#connecting = undefined;
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            this.#pending = done;
+            if (readyMs > 0)
+                readyTimer = (this.#o.setTimeout ?? setTimeout)(() => {
+                    readyTimer = undefined;
+                    done(new CallsError("media_timeout", "The platform did not report media ready in time."));
+                    this.close();
+                }, readyMs);
+            void this.#open(done);
+        });
+        this.#connecting = attempt;
+        return attempt;
+    }
+    async #open(done) {
+        let token;
+        try {
+            token = (await this.#o.api.token(this.#o.refreshToken === true ? { refresh: true } : {})).value;
+        }
+        catch (cause) {
+            done(new CallsError("token_failed", cause instanceof Error
+                ? cause.message
+                : "Could not obtain a token for the media socket.", { cause }));
+            return;
+        }
+        if (this.#closed)
+            return;
+        let socket;
+        try {
+            socket = new this.#WS(this.#o.api.socketUrl(mediaSocketPath(this.#o.callId)), [MEDIA_SUBPROTOCOL]);
+        }
+        catch (cause) {
+            done(cause instanceof Error
+                ? cause
+                : new Error("WebSocket construction failed."));
+            return;
+        }
+        socket.binaryType = "arraybuffer";
+        this.#socket = socket;
+        let opened = false;
+        socket.onopen = () => {
+            opened = true;
+            const auth = {
+                type: "auth",
+                token,
+                connectionId: this.#o.connectionId,
+                ...(this.#o.participant === undefined || isClientToken(token)
+                    ? {}
+                    : { participant: this.#o.participant }),
+            };
+            socket.send(JSON.stringify(auth));
+        };
+        socket.onmessage = (event) => {
+            const data = event.data;
+            if (typeof data === "string") {
+                const control = parseMediaControl(data);
+                if (control === undefined)
+                    return;
+                if (control.type === "ready") {
+                    this.#sampleRate = control.sampleRate;
+                    this.#ready = true;
+                    this.#startHeartbeat(socket);
+                    try {
+                        this.emit("ready", {
+                            sampleRate: control.sampleRate,
+                            video: control.video,
+                            ...(control.callId === undefined
+                                ? {}
+                                : { callId: control.callId }),
+                            ...(control.connectionId === undefined
+                                ? {}
+                                : { connectionId: control.connectionId }),
+                        });
+                    }
+                    finally {
+                        done();
+                    }
+                    return;
+                }
+                if (control.type === "error" && control.code === "call_claimed")
+                    this.#claimed = true;
+                if (!this.#ready) {
+                    // The platform sends an error frame and then closes; settle on the
+                    // close so the close code decides the error type.
+                    if (control.type === "error")
+                        this.#refusal = errorFrom(control);
+                    return;
+                }
+                this.#control(control);
+                return;
+            }
+            if (!this.#ready)
+                return;
+            const bytes = data instanceof ArrayBuffer
+                ? new Uint8Array(data)
+                : ArrayBuffer.isView(data)
+                    ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+                    : undefined;
+            if (bytes === undefined)
+                return;
+            const frame = decodeMediaFrame(bytes);
+            if (frame === undefined)
+                return;
+            if (frame.kind === "audio")
+                this.emit("audio", frame.pcm);
+            else
+                this.emit("video", frame.frame);
+        };
+        // Node 22's WebSocket reports a failed handshake (refused, reset, or a
+        // non-101 reply) with an error event and never fires close, so treat an
+        // error before open as the close that other runtimes deliver.
+        socket.onerror = () => {
+            if (opened || this.#socket !== socket)
+                return;
+            const onclose = socket.onclose;
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close();
+            }
+            catch {
+                // never opened
+            }
+            onclose?.call(socket, { code: 1006 });
+        };
+        socket.onclose = (event) => {
+            this.#stopHeartbeat();
+            if (this.#socket === socket)
+                this.#socket = undefined;
+            this.#closed = true;
+            this.#ready = false;
+            const close = this.#classify(event);
+            done(closeError(close, this.#refusal));
+            this.emit("close", close);
+        };
+    }
+    /** Push s16le mono PCM at {@link sampleRate}. Returns false when not connected. */
+    writeAudio(pcm) {
+        if (!this.connected)
+            return false;
+        this.#socket.send(encodeAudioFrame(pcm));
+        return true;
+    }
+    /** Push one H.264 Annex-B access unit. Send decoder configuration with keyframes. */
+    writeVideo(frame) {
+        if (!this.connected)
+            return false;
+        this.#socket.send(encodeVideoFrame({ ...frame, source: 0 }));
+        return true;
+    }
+    send(frame) {
+        if (!this.connected)
+            return false;
+        this.#socket.send(JSON.stringify(frame));
+        return true;
+    }
+    /** Close this connection only; the call continues. False when not connected. */
+    leave() {
+        if (!this.send({ type: "leave" }))
+            return false;
+        this.#intent = "left";
+        this.#finish("left");
+        return true;
+    }
+    /** End the call for every participant. False when not connected. */
+    endCall() {
+        if (!this.send({ type: "end_call" }))
+            return false;
+        this.#intent = "ended";
+        this.#finish("ended");
+        return true;
+    }
+    close() {
+        this.#finish("local");
+    }
+    #finish(reason) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#stopHeartbeat();
+        this.#pending?.(new Error("Media socket closed before media was bridged."));
+        const socket = this.#socket;
+        this.#socket = undefined;
+        this.#ready = false;
+        if (socket === undefined)
+            return;
+        socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+        try {
+            socket.close(1000, reason === "local" ? "closed" : reason);
+        }
+        catch {
+            // already closed
+        }
+        this.emit("close", { reason });
+    }
+    #classify(event) {
+        const code = event?.code;
+        const text = (event?.reason ?? "").toLowerCase();
+        const withCode = code === undefined ? {} : { code };
+        if (this.#intent !== undefined)
+            return { reason: this.#intent, ...withCode };
+        if (code === AUTH_FAILED_CLOSE_CODE)
+            return { reason: "unauthorized", ...withCode };
+        if (this.#claimed ||
+            text === "call claimed" ||
+            (code === CALL_CLAIMED_CLOSE_CODE && this.#refusal === undefined))
+            return {
+                reason: this.#claimed || text === "call claimed" ? "claimed" : "ended",
+                ...withCode,
+            };
+        // 4409 for another reason: the call is ended or not available.
+        if (code === CALL_CLAIMED_CLOSE_CODE)
+            return { reason: "ended", ...withCode };
+        // The platform closes a connection normally when it leaves or the call
+        // ends; the lifecycle stream reports which.
+        if (code === 1000)
+            return { reason: "ended", ...withCode };
+        if (code === 4400 ||
+            code === CALLS_DISABLED_CLOSE_CODE ||
+            code === 1008 ||
+            code === 1009)
+            return { reason: "refused", ...withCode };
+        if (code === undefined || RETRYABLE_CLOSE_CODES.has(code))
+            return { reason: "lost", ...withCode };
+        return { reason: "lost", ...withCode };
+    }
+    #control(frame) {
+        switch (frame.type) {
+            case "pong":
+                this.#awaitingPong = false;
+                return;
+            case "participant_joined":
+                this.emit("participantJoined", frame.participant);
+                return;
+            case "participant_left":
+                this.emit("participantLeft", frame.participantId, frame.reason);
+                return;
+            case "participant_state":
+                this.emit("participantState", frame.participant);
+                return;
+            case "video_source":
+                this.emit("videoSource", frame.connectionId !== undefined
+                    ? {
+                        source: frame.source,
+                        connectionId: frame.connectionId,
+                        ...(frame.connectionParticipant === undefined
+                            ? {}
+                            : { connectionParticipant: frame.connectionParticipant }),
+                    }
+                    : { source: frame.source, participant: frame.participant });
+                return;
+            case "video_source_removed":
+                this.emit("videoSourceRemoved", frame.source);
+                return;
+            case "keyframe_request":
+                this.emit("keyframeRequest");
+                return;
+            case "error":
+                this.emit("error", errorFrom(frame));
+                return;
+            default:
+                return;
+        }
+    }
+    #startHeartbeat(socket) {
+        this.#stopHeartbeat();
+        const every = this.#o.heartbeatMs ?? 5_000;
+        if (every <= 0)
+            return;
+        this.#beat = (this.#o.setInterval ?? setInterval)(() => {
+            if (this.#socket !== socket)
+                return;
+            if (this.#awaitingPong) {
+                // Treat a silent socket as lost so the call can reconnect it.
+                this.#stopHeartbeat();
+                this.#closed = true;
+                this.#socket = undefined;
+                this.#ready = false;
+                socket.onopen =
+                    socket.onmessage =
+                        socket.onclose =
+                            socket.onerror =
+                                null;
+                try {
+                    socket.close();
+                }
+                catch {
+                    // already gone
+                }
+                this.emit("close", { reason: "lost" });
+                return;
+            }
+            this.#awaitingPong = this.send({ type: "ping" });
+        }, every);
+    }
+    #stopHeartbeat() {
+        if (this.#beat !== undefined) {
+            (this.#o.clearInterval ?? clearInterval)(this.#beat);
+            this.#beat = undefined;
+        }
+        this.#awaitingPong = false;
+    }
+}
+function errorFrom(frame) {
+    if (frame.code === "call_claimed")
+        return new CallClaimedError(frame.message);
+    if (frame.code === "unauthorized")
+        return new CallsAuthError(frame.message);
+    if (frame.code === "calls_disabled")
+        return new CallsDisabledError(frame.message);
+    return new CallsError(frame.code, frame.message ??
+        `The platform refused the media connection (${frame.code}).`);
+}
+function closeError(close, refusal) {
+    switch (close.reason) {
+        case "claimed":
+            return new CallClaimedError();
+        case "unauthorized":
+            return new CallsAuthError(refusal?.message);
+        case "ended":
+            return (refusal ?? new CallsError("call_ended", "The call is not available."));
+        case "refused":
+            return (refusal ??
+                new CallsError("media_refused", "The platform refused the media connection."));
+        default:
+            return (refusal ??
+                new CallsError("media_closed", "Media socket closed before media was bridged."));
+    }
+}
+//# sourceMappingURL=media.js.map

package/dist/calls/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../../calls/src/media.ts"],"names":[],"mappings":"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"}

package/dist/calls/protocol.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The wire contract between this client and the platform (Calls contract
+ * revision 1). Two sockets carry a call:
+ *
+ * 1. The **lifecycle socket** (`GET /voip/ws`) — one per client. No credential
+ *    travels in the URL: the first frame is `{ type: "auth", token }` and the
+ *    platform answers `ready`. Server credentials name the session with
+ *    `?session=` (and optionally `&participant=`); client tokens send no query
+ *    parameters. A later `auth` frame replaces an expiring token and must
+ *    resolve to the same organization, project, session and participant. The
+ *    platform closes the socket with 4401 once the token stops authorizing
+ *    the session.
+ *
+ * 2. The **media socket** (`GET /voip/calls/{callId}/media`, subprotocol
+ *    `pmfa.calls.v2`) — one per media connection. The first frame is
+ *    `{ type: "auth", token, connectionId, participant? }`; the URL carries no
+ *    query parameters. Replacement auth frames cannot change the connection
+ *    or participant. Binary frames
+ *    carry media, text frames carry JSON control. Every binary frame starts
+ *    with a one-byte kind tag so audio and video share the socket.
+ */
+/** Lifecycle socket path on the API host. */
+export declare const LIFECYCLE_SOCKET_PATH = "/voip/ws";
+/** Close code for a token that no longer authorizes the socket. */
+export declare const AUTH_FAILED_CLOSE_CODE = 4401;
+/** Media socket subprotocol. */
+export declare const MEDIA_SUBPROTOCOL = "pmfa.calls.v2";
+export declare function mediaSocketPath(callId: string): string;
+/** A media connection id: 8–64 characters of `[A-Za-z0-9_-]`. */
+export declare function isConnectionId(value: unknown): value is string;
+/** A server-credential participant name: 1–128 characters of `[A-Za-z0-9._:@-]`. */
+export declare function isParticipantName(value: unknown): value is string;
+/**
+ * A new connection id: 18 crypto-random bytes as base64url (24 characters).
+ * Reuse the same id to reconnect the same connection.
+ */
+export declare function createConnectionId(random?: (bytes: Uint8Array<ArrayBuffer>) => Uint8Array): string;
+export interface TrickleCandidate {
+    readonly candidate: string;
+    readonly sdpMid?: string;
+    readonly sdpMLineIndex?: number;
+}
+export type LifecycleFrame = {
+    readonly type: "ready";
+    readonly session?: string;
+    /** Participant reference of the authenticated credential, when sent. */
+    readonly participant?: string;
+} | {
+    readonly type: "event";
+    readonly event: string;
+    readonly callId: string;
+    readonly payload: unknown;
+    readonly timestamp: string;
+} | {
+    readonly type: "candidate";
+    readonly callId: string;
+    readonly connectionId?: string;
+    readonly candidate: TrickleCandidate;
+} | {
+    readonly type: "error";
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly type: "pong";
+};
+export type LifecycleClientFrame = {
+    readonly type: "auth";
+    readonly token: string;
+} | {
+    readonly type: "ping";
+} | {
+    readonly type: "candidate";
+    readonly callId: string;
+    readonly connectionId: string;
+    readonly candidate: TrickleCandidate;
+};
+/** Parse one lifecycle frame; unknown or malformed frames yield `undefined`. */
+export declare function parseLifecycleFrame(data: unknown): LifecycleFrame | undefined;
+/** First byte of every binary media frame. */
+export declare const MediaFrameKind: {
+    /** s16le mono PCM at the `ready` frame's sample rate. */
+    readonly Audio: 1;
+    /** One encoded access unit; payload is {@link VIDEO_HEADER_BYTES} of header then the bytes. */
+    readonly Video: 2;
+};
+export type MediaFrameKind = (typeof MediaFrameKind)[keyof typeof MediaFrameKind];
+/** Default PCM rate until the `ready` frame names one. */
+export declare const DEFAULT_SAMPLE_RATE = 16000;
+/**
+ * Header that follows the {@link MediaFrameKind.Video} tag. Fixed 14 bytes,
+ * big-endian: codec (1) · flags (1) · source (4) · timestamp µs (8), then one
+ * Annex-B access unit.
+ */
+export declare const VIDEO_HEADER_BYTES = 14;
+export declare const VideoCodec: {
+    readonly H264: 1;
+};
+export type VideoCodec = (typeof VideoCodec)[keyof typeof VideoCodec];
+export declare const VideoFlags: {
+    readonly Keyframe: 1;
+};
+export interface VideoFrameHeader {
+    readonly codec: VideoCodec;
+    readonly keyframe: boolean;
+    /**
+     * Source handle. Inbound frames carry the producing source announced by a
+     * `video_source` frame. Clients send 0; the platform assigns the handle.
+     */
+    readonly source: number;
+    /** Capture timestamp in microseconds. */
+    readonly timestampUs: number;
+}
+export interface VideoFrame extends VideoFrameHeader {
+    readonly data: Uint8Array;
+}
+/** An outbound frame; `source` defaults to 0 and `codec` to H.264. */
+export type OutboundVideoFrame = Omit<VideoFrame, "source" | "codec"> & {
+    readonly source?: number;
+    readonly codec?: VideoCodec;
+};
+export declare function encodeAudioFrame(pcm: Int16Array): Uint8Array<ArrayBuffer>;
+export declare function encodeVideoFrame(frame: OutboundVideoFrame): Uint8Array<ArrayBuffer>;
+export type DecodedMediaFrame = {
+    readonly kind: "audio";
+    readonly pcm: Int16Array;
+} | {
+    readonly kind: "video";
+    readonly frame: VideoFrame;
+};
+/** Decode one binary media frame; malformed frames yield `undefined`. */
+export declare function decodeMediaFrame(bytes: Uint8Array): DecodedMediaFrame | undefined;
+export interface Participant {
+    readonly id: string;
+    readonly phoneNumber?: string;
+    readonly bsuid?: string;
+    readonly username?: string;
+    readonly audioMuted: boolean;
+    readonly video: boolean;
+    readonly state: "invited" | "ringing" | "connected" | "left";
+}
+/**
+ * Who sends a video source: another media connection of this call, or a
+ * WhatsApp participant.
+ */
+export type VideoSourceOwner = {
+    readonly connectionId: string;
+    /** Participant reference (`client:<id>` or `server:<name>`) of that connection, when known. */
+    readonly connectionParticipant?: string;
+    readonly participant?: undefined;
+} | {
+    readonly participant: Participant;
+    readonly connectionId?: undefined;
+    readonly connectionParticipant?: undefined;
+};
+export type VideoSourceFrame = {
+    readonly type: "video_source";
+    readonly source: number;
+} & VideoSourceOwner;
+/** Text frames the platform sends on the media socket. */
+export type MediaControlFrame = {
+    readonly type: "ready";
+    readonly callId?: string;
+    readonly connectionId?: string;
+    /** PCM rate both directions use. */
+    readonly sampleRate: number;
+    readonly video: boolean;
+} | {
+    readonly type: "pong";
+} | {
+    readonly type: "participant_joined";
+    readonly participant: Participant;
+} | {
+    readonly type: "participant_left";
+    readonly participantId: string;
+    readonly reason?: string;
+} | {
+    readonly type: "participant_state";
+    readonly participant: Participant;
+} | VideoSourceFrame | {
+    readonly type: "video_source_removed";
+    readonly source: number;
+}
+/** Send a keyframe (with decoder configuration) on the next video frame. */
+ | {
+    readonly type: "keyframe_request";
+}
+/** `message` is absent on authentication refusals. */
+ | {
+    readonly type: "error";
+    readonly code: string;
+    readonly message?: string;
+};
+/** Text frames the client sends on the media socket. */
+export type MediaClientFrame = {
+    readonly type: "auth";
+    readonly token: string;
+    readonly connectionId: string;
+    readonly participant?: string;
+} | {
+    readonly type: "ping";
+}
+/** Close this connection only. */
+ | {
+    readonly type: "leave";
+}
+/** End the call for every participant. */
+ | {
+    readonly type: "end_call";
+};
+export declare function parseMediaControl(data: unknown): MediaControlFrame | undefined;
+/** Validate an already-decoded media control value. @internal */
+export declare function parseMediaControlValue(parsed: unknown): MediaControlFrame | undefined;
+/** A positive uint32 source handle. */
+export declare function isSourceHandle(value: unknown): value is number;
+export declare function isParticipant(value: unknown): value is Participant;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/calls/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../calls/src/protocol.ts"],"names":[],"mappings":"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"}