@fonoster/voice 0.27.0 → 0.31.0

package/dist/Session.js

@@ -0,0 +1,576 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_GATHER_TIMEOUT_MS = 4000;
+/** Commands that make AppBridge start listening (speech recognition and turn events). */
+const SPEECH_COMMANDS = new Set([
+    "speak",
+    "play",
+    "subscribe",
+    "listen.update"
+]);
+const MAX_BUFFERED_INPUTS = 32;
+/**
+ * One call's session, built on the fonoster.session.v1 messages (voice-sdk S8). Verbs are
+ * conveniences: each sends one command and resolves on the event that answers it.
+ */
+class Session {
+    constructor(start, transport, signedFor) {
+        var _a, _b;
+        this.transport = transport;
+        this.seq = 0;
+        this.outputs = new Map();
+        this.commands = new Map();
+        this.marks = new Map();
+        this.endWaiters = [];
+        this.listeners = new Map();
+        this.frameListeners = new Set();
+        this.buffered = [];
+        this.listening = false;
+        this.signedFor = signedFor;
+        this.sessionRef = start.sessionRef;
+        this.callRef = start.callRef;
+        this.appRef = start.appRef;
+        this.direction = start.direction;
+        this.from = start.from;
+        this.to = start.to;
+        this.metadata = ((_a = start.metadata) !== null && _a !== void 0 ? _a : {});
+        this.traceparent = start.traceparent;
+        this.handoffPayload = ((_b = start.handoff) !== null && _b !== void 0 ? _b : null);
+        this.speech = start.speech;
+        this.audioFormat = start.audio;
+        this.tracks = start.tracks;
+        this.audio = {
+            onFrame: (cb) => void this.frameListeners.add(cb),
+            send: (frame) => this.transport.sendBinary(frame),
+            mark: (name) => new Promise((resolve, reject) => {
+                var _a;
+                if (this.endedReason)
+                    return reject(new errors_1.SessionEndedError(this.endedReason));
+                const list = (_a = this.marks.get(name)) !== null && _a !== void 0 ? _a : [];
+                list.push(resolve);
+                this.marks.set(name, list);
+                this.send({ type: "mark", name });
+            }),
+            clear: () => this.send({ type: "clear" })
+        };
+    }
+    get ended() {
+        return this.endedReason !== undefined;
+    }
+    // ---- speech -----------------------------------------------------------------------
+    /** Speaks text, or a stream of text pieces as one utterance, and reports what was heard. */
+    say(input_1) {
+        return __awaiter(this, arguments, void 0, function* (input, options = {}) {
+            var _a, input_2, input_2_1;
+            var _b, e_1, _c, _d;
+            var _e, _f;
+            const id = this.nextId("say");
+            const fields = this.compact({
+                voice: options.voice,
+                language: options.language,
+                interruptible: options.interruptible,
+                preempt: options.preempt
+            });
+            if (typeof input === "string") {
+                const done = this.awaitOutput(id, input, (_e = options.interruptible) !== null && _e !== void 0 ? _e : true);
+                this.send(Object.assign({ type: "speak", id, text: input, last: true }, fields));
+                return done;
+            }
+            let text = "";
+            const done = this.awaitOutput(id, "", (_f = options.interruptible) !== null && _f !== void 0 ? _f : true);
+            try {
+                try {
+                    for (_a = true, input_2 = __asyncValues(input); input_2_1 = yield input_2.next(), _b = input_2_1.done, !_b; _a = true) {
+                        _d = input_2_1.value;
+                        _a = false;
+                        const piece = _d;
+                        text += piece;
+                        this.send(Object.assign({ type: "speak", id, text: piece, last: false }, fields));
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_a && !_b && (_c = input_2.return)) yield _c.call(input_2);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+            }
+            catch (e) {
+                // End the utterance so AppBridge does not wait for more pieces.
+                this.send(Object.assign({ type: "speak", id, text: "", last: true }, fields));
+                this.outputs.delete(id);
+                done.catch(() => undefined);
+                throw e;
+            }
+            const output = this.outputs.get(id);
+            if (output)
+                output.text = text;
+            this.send(Object.assign({ type: "speak", id, text: "", last: true }, fields));
+            return done;
+        });
+    }
+    /** Cuts the agent off: every pending say and play resolves as interrupted. */
+    stopSay() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.send({ type: "clear" });
+        });
+    }
+    play(url_1) {
+        return __awaiter(this, arguments, void 0, function* (url, options = {}) {
+            var _a;
+            const id = this.nextId("play");
+            const done = this.awaitOutput(id, "", (_a = options.interruptible) !== null && _a !== void 0 ? _a : true);
+            this.send(Object.assign({ type: "play", id, url }, this.compact(options)));
+            const r = yield done;
+            return { interrupted: r.interrupted, heardMs: r.heardMs };
+        });
+    }
+    /** Waits for speech (turn.ended) or digits (dtmf), whichever comes first. */
+    gather(options = {}) {
+        var _a;
+        if (this.endedReason)
+            return Promise.reject(new errors_1.SessionEndedError(this.endedReason));
+        if (this.gatherState)
+            return Promise.reject(new Error("a gather is already pending"));
+        const source = (_a = options.source) !== null && _a !== void 0 ? _a : "speech_and_dtmf";
+        // AppBridge listens only after a Speech-layer command; a gather may be the first one.
+        if (source !== "dtmf" && !this.listening)
+            this.send({ type: "listen.update" });
+        return new Promise((resolve, reject) => {
+            var _a;
+            const g = {
+                speech: source !== "dtmf",
+                dtmf: source !== "speech",
+                maxDigits: options.maxDigits,
+                finishOnKey: options.finishOnKey,
+                timeoutMs: (_a = options.timeout) !== null && _a !== void 0 ? _a : DEFAULT_GATHER_TIMEOUT_MS,
+                digits: "",
+                resolve,
+                reject
+            };
+            this.gatherState = g;
+            this.armGatherTimer(g);
+            // Inputs that arrived before the gather (type-ahead) count, in order.
+            const backlog = this.buffered;
+            this.buffered = [];
+            for (const input of backlog) {
+                if (this.gatherState !== g)
+                    break;
+                this.feedGather(input);
+            }
+        });
+    }
+    /**
+     * Starts listening or changes how AppBridge listens (`listen.update`): recognition language,
+     * hints, and the turn-taking patience knob (`low`, `normal` or `high`).
+     */
+    listen() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            this.send(Object.assign({ type: "listen.update" }, this.compact(options)));
+        });
+    }
+    /** Requests opt-in events: "turn.estimate", "transcript.partial". */
+    subscribe(events) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.send({ type: "subscribe", events });
+        });
+    }
+    on(event, cb) {
+        var _a;
+        const set = (_a = this.listeners.get(event)) !== null && _a !== void 0 ? _a : new Set();
+        set.add(cb);
+        this.listeners.set(event, set);
+        return this;
+    }
+    off(event, cb) {
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(cb);
+        return this;
+    }
+    // ---- control ----------------------------------------------------------------------
+    playDtmf(digits) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.command({ type: "dtmf.send", digits });
+        });
+    }
+    /** Transfers the call; resolves when AppBridge ends the session with reason transfer. */
+    transfer(to, options = {}) {
+        const id = this.nextId("transfer");
+        if (options.mode === "warm")
+            this.lastWarmTransfer = id;
+        return this.untilEnd(["transfer"], id, () => this.send(Object.assign({ type: "transfer", id,
+            to }, this.compact({ mode: options.mode, headers: options.headers }))));
+    }
+    /**
+     * Completes the pending warm transfer: the agent leaves, caller and new party stay. Resolves
+     * when the session ends with reason transfer; rejects with a SessionError
+     * (`transfer_not_answered`) when the new party has not answered yet, which leaves the transfer
+     * pending: wait for the `transfer.answered` event and call it again.
+     */
+    completeTransfer() {
+        const id = this.lastWarmTransfer;
+        if (!id)
+            return Promise.reject(new Error("no warm transfer is pending"));
+        return new Promise((resolve, reject) => {
+            if (this.endedReason)
+                return reject(new errors_1.SessionEndedError(this.endedReason));
+            const waiter = { reasons: ["transfer"], resolve, reject };
+            this.endWaiters.push(waiter);
+            this.completing = (e) => {
+                this.endWaiters = this.endWaiters.filter((w) => w !== waiter);
+                reject(e);
+            };
+            try {
+                this.send({ type: "transfer.complete", id });
+            }
+            catch (e) {
+                this.completing = undefined;
+                reject(e);
+            }
+        });
+    }
+    hold() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            this.command(Object.assign({ type: "hold" }, this.compact(options)));
+        });
+    }
+    resume() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.command({ type: "resume" });
+        });
+    }
+    /** Hands the call to another app with a payload; resolves when this session ends. */
+    handoff(app, payload = {}) {
+        const id = this.nextId("handoff");
+        return this.untilEnd(["handoff"], id, () => this.send({ type: "handoff", id, app, payload }));
+    }
+    /** Hangs up; resolves when the session ends. */
+    hangup() {
+        if (this.endedReason)
+            return Promise.resolve();
+        return this.untilEnd(["app_hangup", "caller_hangup", "closed"], undefined, () => this.send({ type: "hangup" }));
+    }
+    /**
+     * Adds a note to the call record (record.note).
+     *
+     * @internal Reserved for Fonoster's own apps (Autopilot); not part of the public SDK and may change.
+     */
+    note(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.command({ type: "record.note", data });
+        });
+    }
+    /**
+     * Adds model token usage to the call (usage.report, add-usage-metering).
+     *
+     * @internal Reserved for Fonoster's own Autopilot; AppBridge refuses it from other apps.
+     */
+    reportUsage(lines) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.command({ type: "usage.report", lines });
+        });
+    }
+    /** Resolves at once: AppBridge answers the call on connect (voice-sdk S2). */
+    answer() {
+        return __awaiter(this, void 0, void 0, function* () { });
+    }
+    // ---- incoming ---------------------------------------------------------------------
+    /** Feeds one frame from the socket. */
+    receive(data, isBinary) {
+        if (isBinary) {
+            const trackId = data[0];
+            const frame = data.subarray(1);
+            for (const cb of this.frameListeners)
+                cb(frame, trackId);
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(data.toString());
+        }
+        catch (_a) {
+            return;
+        }
+        this.onMessage(msg);
+    }
+    /** The socket closed. */
+    closed() {
+        this.finish("closed");
+    }
+    onMessage(msg) {
+        var _a, _b, _c, _d;
+        const type = msg.type;
+        switch (type) {
+            case "output.started": {
+                const o = this.outputs.get(msg.id);
+                if (o)
+                    o.startedAt = Date.now();
+                return;
+            }
+            case "output.done": {
+                const o = this.take(msg.id);
+                o === null || o === void 0 ? void 0 : o.resolve({
+                    interrupted: false,
+                    heardText: o.text,
+                    heardMs: o.startedAt ? Date.now() - o.startedAt : 0
+                });
+                return;
+            }
+            case "output.interrupted": {
+                const o = this.take(msg.id);
+                o === null || o === void 0 ? void 0 : o.resolve({
+                    interrupted: true,
+                    heardText: String((_a = msg.heardText) !== null && _a !== void 0 ? _a : ""),
+                    heardMs: Number((_b = msg.heardMs) !== null && _b !== void 0 ? _b : 0)
+                });
+                return;
+            }
+            case "mark": {
+                const list = this.marks.get(msg.name);
+                const resolve = list === null || list === void 0 ? void 0 : list.shift();
+                if (list && !list.length)
+                    this.marks.delete(msg.name);
+                resolve === null || resolve === void 0 ? void 0 : resolve({ cleared: msg.cleared === true });
+                return;
+            }
+            case "error":
+                return this.onError(msg);
+            case "session.end":
+                return this.finish(String((_c = msg.reason) !== null && _c !== void 0 ? _c : "closed"));
+            case "dtmf":
+                this.emit("dtmf", { digit: msg.digit });
+                return this.input({ type: "dtmf", digit: String(msg.digit) });
+            case "turn.ended":
+                this.emit(type, this.without(msg, "type"));
+                return this.input({ type: "turn.ended", text: String((_d = msg.text) !== null && _d !== void 0 ? _d : "") });
+            case "turn.user_started":
+                this.bargeIn();
+                this.emit(type, {});
+                return this.input({ type: "turn.user_started" });
+            case "turn.likely_ended":
+            case "turn.resumed":
+            case "turn.backchannel":
+            case "transcript.partial":
+            case "turn.estimate":
+            case "amd.result":
+            case "transfer.answered":
+                return this.emit(type, this.without(msg, "type"));
+            default:
+            // Unknown types are ignored (additive-only protocol).
+        }
+    }
+    onError(msg) {
+        var _a;
+        const error = new errors_1.SessionError(String(msg.code), String((_a = msg.message) !== null && _a !== void 0 ? _a : msg.code), msg.fatal === true);
+        const id = msg.relatesTo;
+        // A refused completeTransfer() fails that call, not the pending transfer.
+        if (error.code === "transfer_not_answered" && this.completing) {
+            const completing = this.completing;
+            this.completing = undefined;
+            completing(error);
+            return;
+        }
+        const output = id ? this.take(id) : undefined;
+        const command = id ? this.commands.get(id) : undefined;
+        if (output)
+            output.reject(error);
+        else if (command) {
+            this.commands.delete(id);
+            command(error);
+        }
+        else {
+            this.emit("error", {
+                code: error.code,
+                message: error.message,
+                fatal: error.fatal
+            });
+        }
+        if (error.fatal)
+            this.finish("error");
+    }
+    // ---- gather -----------------------------------------------------------------------
+    input(input) {
+        if (this.gatherState)
+            return this.feedGather(input);
+        if (input.type === "turn.user_started")
+            return;
+        this.buffered.push(input);
+        if (this.buffered.length > MAX_BUFFERED_INPUTS)
+            this.buffered.shift();
+    }
+    feedGather(input) {
+        const g = this.gatherState;
+        if (input.type === "turn.user_started") {
+            // The caller is talking: wait for the end of the turn instead of timing out mid-sentence.
+            if (g.speech && !g.digits && g.timer)
+                clearTimeout(g.timer);
+            return;
+        }
+        if (input.type === "turn.ended") {
+            // First input wins: once digits started, speech is ignored.
+            if (g.speech && !g.digits)
+                this.endGather({ speech: input.text });
+            return;
+        }
+        if (!g.dtmf)
+            return;
+        if (g.finishOnKey && input.digit === g.finishOnKey)
+            return this.endGather({ digits: g.digits });
+        g.digits += input.digit;
+        if (g.maxDigits && g.digits.length >= g.maxDigits)
+            return this.endGather({ digits: g.digits });
+        this.armGatherTimer(g);
+    }
+    armGatherTimer(g) {
+        if (g.timer)
+            clearTimeout(g.timer);
+        g.timer = setTimeout(() => this.endGather(g.digits ? { digits: g.digits } : {}), g.timeoutMs);
+    }
+    endGather(result) {
+        const g = this.gatherState;
+        if (!g)
+            return;
+        if (g.timer)
+            clearTimeout(g.timer);
+        this.gatherState = undefined;
+        g.resolve(result);
+    }
+    // ---- internals --------------------------------------------------------------------
+    nextId(kind) {
+        return `${kind}-${++this.seq}`;
+    }
+    send(message) {
+        if (this.endedReason)
+            throw new errors_1.SessionEndedError(this.endedReason);
+        if (SPEECH_COMMANDS.has(message.type))
+            this.listening = true;
+        this.transport.sendJson(message);
+    }
+    /** Sends a command whose only answer is a possible error (logged as a session error). */
+    command(message) {
+        const id = this.nextId(String(message.type).replace(".", "-"));
+        this.send(Object.assign(Object.assign({}, message), { id }));
+    }
+    awaitOutput(id, text, interruptible = true) {
+        return new Promise((resolve, reject) => {
+            if (this.endedReason)
+                return reject(new errors_1.SessionEndedError(this.endedReason));
+            this.outputs.set(id, { text, resolve, reject, interruptible });
+        });
+    }
+    /**
+     * The app owns interruption (appbridge B22): when the caller starts talking over an interruptible
+     * say or play, the SDK cuts it off with clear; a non-interruptible one keeps playing.
+     */
+    bargeIn() {
+        const playing = [...this.outputs.values()].filter((o) => o.startedAt !== undefined);
+        if (playing.length && playing.every((o) => o.interruptible))
+            this.send({ type: "clear" });
+    }
+    take(id) {
+        const o = this.outputs.get(id);
+        this.outputs.delete(id);
+        return o;
+    }
+    untilEnd(reasons, id, sendIt) {
+        return new Promise((resolve, reject) => {
+            if (this.endedReason)
+                return reject(new errors_1.SessionEndedError(this.endedReason));
+            const waiter = { reasons, resolve, reject };
+            this.endWaiters.push(waiter);
+            if (id) {
+                this.commands.set(id, (e) => {
+                    this.endWaiters = this.endWaiters.filter((w) => w !== waiter);
+                    reject(e);
+                });
+            }
+            try {
+                sendIt();
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }
+    finish(reason) {
+        if (this.endedReason)
+            return;
+        this.endedReason = reason;
+        this.completing = undefined;
+        const ended = new errors_1.SessionEndedError(reason);
+        for (const w of this.endWaiters) {
+            if (w.reasons.includes(reason))
+                w.resolve();
+            else
+                w.reject(ended);
+        }
+        this.endWaiters = [];
+        for (const o of this.outputs.values())
+            o.reject(ended);
+        this.outputs.clear();
+        this.commands.clear();
+        for (const list of this.marks.values())
+            for (const r of list)
+                r({ cleared: true });
+        this.marks.clear();
+        if (this.gatherState) {
+            const g = this.gatherState;
+            if (g.timer)
+                clearTimeout(g.timer);
+            this.gatherState = undefined;
+            g.reject(ended);
+        }
+        this.emit("end", { reason });
+        this.transport.close();
+    }
+    emit(event, data) {
+        var _a;
+        for (const cb of (_a = this.listeners.get(event)) !== null && _a !== void 0 ? _a : []) {
+            try {
+                cb(data);
+            }
+            catch (_b) {
+                // A listener's failure must not break the session.
+            }
+        }
+    }
+    compact(o) {
+        return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+    }
+    without(msg, key) {
+        const _a = msg, _b = key, _ = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+        void _;
+        return rest;
+    }
+}
+exports.Session = Session;

package/dist/VoiceServer.d.ts

@@ -1,6 +1,71 @@
-import { ServerConfig, VoiceHandler } from "./types";
-export default class VoiceServer {
-    config: ServerConfig;
-    constructor(config?: ServerConfig);
-    listen(handler: VoiceHandler): Promise<void>;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as http from "http";
+import { Duplex } from "stream";
+import { Session } from "./Session";
+export type SessionHandler = (session: Session) => Promise<void> | void;
+export type Handler = SessionHandler;
+export type VoiceServerOptions = {
+    port?: number;
+    host?: string;
+    /** Path to accept sessions on (default: any). */
+    path?: string;
+    /** The app's signing secret (default: APP_SIGNING_SECRET). */
+    signingSecret?: string;
+    /** Turn verification off for local development only; every connection then logs a warning. */
+    verifySignature?: boolean;
+    /**
+     * The app's URL as configured in Fonoster (one or more). When set, signatures are checked
+     * against it only, never against a URL built from the request's Host header. Set it whenever
+     * a proxy changes the host or scheme, and always for a server several apps share.
+     */
+    publicUrl?: string | string[];
+    /**
+     * Require the app-bound signature (X-Fonoster-App-Signature): a connection without it is
+     * refused, and session.start must be for the app it was signed for. For a server several apps
+     * share one secret with, such as the hosted Autopilot.
+     */
+    requireAppBinding?: boolean;
+    /** How long to wait for session.start after the socket opens (default 5 s). */
+    startTimeoutMs?: number;
+};
+/**
+ * Accepts AppBridge sessions over WebSocket and runs the handler once per session
+ * (voice-sdk, "VoiceServer accepts AppBridge sessions over WebSocket").
+ */
+export declare class VoiceServer {
+    private readonly options;
+    private wss;
+    private server?;
+    private handler?;
+    private readonly secret?;
+    private readonly verify;
+    constructor(options?: VoiceServerOptions);
+    /** Starts a standalone server. Resolves once it is listening. */
+    listen(handler: Handler): Promise<this>;
+    /** Mounts on an existing HTTP server (Express included): sessions arrive on `path`. */
+    attach(server: http.Server, handler: Handler): this;
+    get port(): number | undefined;
+    close(): Promise<void>;
+    /** Handles one upgrade request: verifies the signature, then runs a session. */
+    handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): void;
+    private candidateUrls;
+    private run;
+    private invoke;
 }