@fonoster/voice 0.30.0 → 0.31.0

package/README.md

@@ -26,7 +26,7 @@ $ npm install --save @fonoster/voice
 ```typescript
 import { VoiceServer } from "@fonoster/voice";
 
-// The gateway signs every connection with the app's signing secret.
+// AppBridge signs every connection with the app's signing secret.
 new VoiceServer({ port: 3000, signingSecret: process.env.APP_SIGNING_SECRET }).listen(
   async (session) => {
     await session.say("Hi there! What's your name?");

package/dist/Session.d.ts

@@ -37,13 +37,15 @@ export declare class Session {
     readonly from: string;
     readonly to: string;
     readonly metadata: Record<string, unknown>;
+    /** The W3C traceparent of the call's span (session.start `traceparent`), when sent. */
+    readonly traceparent?: string;
     /** The payload of the handoff that started this session (session.start `handoff`), or null. */
     readonly handoffPayload: Record<string, unknown> | null;
     readonly speech: SessionStart["speech"];
     readonly audioFormat: SessionStart["audio"];
     readonly tracks: SessionStart["tracks"];
     /**
-     * The app and workspace the gateway's app-bound signature named, when the server verified one
+     * The app and workspace AppBridge's app-bound signature named, when the server verified one
      * (VoiceServer); undefined otherwise.
      */
     readonly signedFor?: {
@@ -69,6 +71,8 @@ export declare class Session {
     private gatherState?;
     private buffered;
     private lastWarmTransfer?;
+    /** A pending completeTransfer(), rejected when AppBridge refuses it. */
+    private completing?;
     private endedReason?;
     private listening;
     constructor(start: SessionStart, transport: SessionTransport, signedFor?: {
@@ -84,7 +88,7 @@ export declare class Session {
     /** Waits for speech (turn.ended) or digits (dtmf), whichever comes first. */
     gather(options?: GatherOptions): Promise<GatherResult>;
     /**
-     * Starts listening or changes how the gateway listens (`listen.update`): recognition language,
+     * Starts listening or changes how AppBridge listens (`listen.update`): recognition language,
      * hints, and the turn-taking patience knob (`low`, `normal` or `high`).
      */
     listen(options?: {
@@ -97,9 +101,14 @@ export declare class Session {
     on<E extends SessionEventName>(event: E, cb: (data: SessionEventMap[E]) => void): this;
     off<E extends SessionEventName>(event: E, cb: (data: SessionEventMap[E]) => void): this;
     playDtmf(digits: string): Promise<void>;
-    /** Transfers the call; resolves when the gateway ends the session with reason transfer. */
+    /** Transfers the call; resolves when AppBridge ends the session with reason transfer. */
     transfer(to: string, options?: TransferOptions): Promise<void>;
-    /** Completes the pending warm transfer: the agent leaves, caller and new party stay. */
+    /**
+     * 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(): Promise<void>;
     hold(options?: {
         music?: string;
@@ -115,7 +124,13 @@ export declare class Session {
      * @internal Reserved for Fonoster's own apps (Autopilot); not part of the public SDK and may change.
      */
     note(data: Record<string, unknown>): Promise<void>;
-    /** Resolves at once: the gateway answers the call on connect (voice-sdk S2). */
+    /**
+     * 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: Record<string, unknown>[]): Promise<void>;
+    /** Resolves at once: AppBridge answers the call on connect (voice-sdk S2). */
     answer(): Promise<void>;
     /** Feeds one frame from the socket. */
     receive(data: Buffer, isBinary: boolean): void;
@@ -133,7 +148,7 @@ export declare class Session {
     private command;
     private awaitOutput;
     /**
-     * The app owns interruption (gateway B22): when the caller starts talking over an 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.
      */
     private bargeIn;

package/dist/Session.js

@@ -30,7 +30,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Session = void 0;
 const errors_1 = require("./errors");
 const DEFAULT_GATHER_TIMEOUT_MS = 4000;
-/** Commands that make the gateway start listening (speech recognition and turn events). */
+/** Commands that make AppBridge start listening (speech recognition and turn events). */
 const SPEECH_COMMANDS = new Set([
     "speak",
     "play",
@@ -63,6 +63,7 @@ class Session {
         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;
@@ -125,7 +126,7 @@ class Session {
                 }
             }
             catch (e) {
-                // End the utterance so the gateway does not wait for more pieces.
+                // 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);
@@ -162,7 +163,7 @@ class Session {
         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";
-        // The gateway listens only after a Speech-layer command; a gather may be the first one.
+        // 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) => {
@@ -190,7 +191,7 @@ class Session {
         });
     }
     /**
-     * Starts listening or changes how the gateway listens (`listen.update`): recognition language,
+     * Starts listening or changes how AppBridge listens (`listen.update`): recognition language,
      * hints, and the turn-taking patience knob (`low`, `normal` or `high`).
      */
     listen() {
@@ -222,7 +223,7 @@ class Session {
             this.command({ type: "dtmf.send", digits });
         });
     }
-    /** Transfers the call; resolves when the gateway ends the session with reason transfer. */
+    /** Transfers the call; resolves when AppBridge ends the session with reason transfer. */
     transfer(to, options = {}) {
         const id = this.nextId("transfer");
         if (options.mode === "warm")
@@ -230,12 +231,32 @@ class Session {
         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. */
+    /**
+     * 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() {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.lastWarmTransfer)
-                throw new Error("no warm transfer is pending");
-            this.send({ type: "transfer.complete", id: this.lastWarmTransfer });
+        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() {
@@ -269,7 +290,17 @@ class Session {
             this.command({ type: "record.note", data });
         });
     }
-    /** Resolves at once: the gateway answers the call on connect (voice-sdk S2). */
+    /**
+     * 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* () { });
     }
@@ -352,6 +383,7 @@ class Session {
             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).
@@ -361,6 +393,13 @@ class Session {
         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)
@@ -450,7 +489,7 @@ class Session {
         });
     }
     /**
-     * The app owns interruption (gateway B22): when the caller starts talking over an 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() {
@@ -487,6 +526,7 @@ class Session {
         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))

package/dist/VoiceServer.d.ts

@@ -46,8 +46,8 @@ export type VoiceServerOptions = {
     startTimeoutMs?: number;
 };
 /**
- * Accepts VoiceSessionGateway sessions over WebSocket and runs the handler once per session
- * (voice-sdk, "VoiceServer accepts gateway sessions over WebSocket").
+ * 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;

package/dist/VoiceServer.js

@@ -71,8 +71,8 @@ const Session_1 = require("./Session");
 const signature_1 = require("./signature");
 const logger = (0, logger_1.getLogger)({ service: "voice", filePath: __filename });
 /**
- * Accepts VoiceSessionGateway sessions over WebSocket and runs the handler once per session
- * (voice-sdk, "VoiceServer accepts gateway sessions over WebSocket").
+ * Accepts AppBridge sessions over WebSocket and runs the handler once per session
+ * (voice-sdk, "VoiceServer accepts AppBridge sessions over WebSocket").
  */
 class VoiceServer {
     constructor(options = {}) {
@@ -133,7 +133,7 @@ class VoiceServer {
         let binding;
         if (this.verify) {
             const urls = this.candidateUrls(req);
-            // The app-bound signature when the gateway sent one (or it is required); a bad one is
+            // The app-bound signature when AppBridge sent one (or it is required); a bad one is
             // refused even if the URL-only signature matches.
             const bound = this.options.requireAppBinding || (0, signature_1.hasAppSignature)(req.headers)
                 ? (0, signature_1.verifyAppSignature)(urls, req.headers, this.secret)

package/dist/errors.d.ts

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/** A command failed: the gateway sent `error` with `relatesTo` set to the command's id. */
+/** A command failed: AppBridge sent `error` with `relatesTo` set to the command's id. */
 export declare class SessionError extends Error {
     readonly code: string;
     readonly fatal: boolean;

package/dist/errors.js

@@ -19,7 +19,7 @@ exports.SessionEndedError = exports.SessionError = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/** A command failed: the gateway sent `error` with `relatesTo` set to the command's id. */
+/** A command failed: AppBridge sent `error` with `relatesTo` set to the command's id. */
 class SessionError extends Error {
     constructor(code, message, fatal = false) {
         super(message);

package/dist/signature.d.ts

@@ -10,7 +10,7 @@ export type Verification = {
     reason?: "missing" | "stale" | "mismatch";
 };
 export declare function sign(url: string, timestamp: number, secret: string): string;
-/** Checks the gateway's signature against each candidate URL (the URL as configured on the app). */
+/** Checks AppBridge's signature against each candidate URL (the URL as configured on the app). */
 export declare function verifySignature(urls: string[], headers: IncomingHttpHeaders, secret: string, nowSeconds?: number): Verification;
 /** The app and workspace a bound signature was made for. */
 export type AppBinding = {
@@ -25,7 +25,7 @@ export declare function signApp(url: string, timestamp: number, binding: AppBind
 /** Whether the request carries the app-bound signature headers at all. */
 export declare function hasAppSignature(headers: IncomingHttpHeaders): boolean;
 /**
- * Checks the gateway's app-bound signature against each candidate URL and returns the app and
+ * Checks AppBridge's app-bound signature against each candidate URL and returns the app and
  * workspace it was made for; the session must then be for that app.
  */
 export declare function verifyAppSignature(urls: string[], headers: IncomingHttpHeaders, secret: string, nowSeconds?: number): AppVerification;

package/dist/signature.js

@@ -38,7 +38,7 @@ function sign(url, timestamp, secret) {
         .update(`${timestamp}.${url}`)
         .digest("hex");
 }
-/** Checks the gateway's signature against each candidate URL (the URL as configured on the app). */
+/** Checks AppBridge's signature against each candidate URL (the URL as configured on the app). */
 function verifySignature(urls, headers, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
     const signature = headers[exports.SIGNATURE_HEADER];
     const timestamp = Number(headers[exports.TIMESTAMP_HEADER]);
@@ -69,7 +69,7 @@ function hasAppSignature(headers) {
     return header(headers, exports.APP_SIGNATURE_HEADER) !== undefined;
 }
 /**
- * Checks the gateway's app-bound signature against each candidate URL and returns the app and
+ * Checks AppBridge's app-bound signature against each candidate URL and returns the app and
  * workspace it was made for; the session must then be for that app.
  */
 function verifyAppSignature(urls, headers, secret, nowSeconds = Math.floor(Date.now() / 1000)) {

package/dist/types.d.ts

@@ -78,7 +78,7 @@ export type SessionEventMap = {
         speaking: boolean;
         kind: string;
     };
-    /** Answering-machine detection, once per call, for apps with `amd` (add-media-node 4.3). */
+    /** Answering-machine detection, once per call, for apps with `amd` (add-roomr 4.3). */
     "amd.result": {
         status: "human" | "voicemail" | "ivr" | "machine" | "unknown";
         confidence: number;
@@ -89,6 +89,10 @@ export type SessionEventMap = {
     dtmf: {
         digit: string;
     };
+    /** A warm transfer's new party answered: completeTransfer() may follow. */
+    "transfer.answered": {
+        relatesTo: string;
+    };
     error: {
         code: string;
         message: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/voice",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Session SDK for Fonoster voice applications",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -14,12 +14,11 @@
   "scripts": {
     "prebuild": "rimraf ./dist tsconfig.tsbuildinfo",
     "build": "tsc -b tsconfig.json",
-    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo",
-    "generate:readme": "node ../../.scripts/gen-readme.cjs"
+    "generate:readme": "fonoster-readme"
   },
   "dependencies": {
-    "@fonoster/common": "^0.30.0",
-    "@fonoster/logger": "^0.30.0",
+    "@fonoster/common": "^0.31.0",
+    "@fonoster/logger": "^0.31.0",
     "ws": "^8.18.0"
   },
   "files": [
@@ -37,8 +36,8 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "gitHead": "b59b06a3ef325abe3f188c0fb87cc22d50ed5471",
+  "gitHead": "f0a5102dddeea0f70f659234108805bc10690f2e",
   "devDependencies": {
-    "@fonoster/conformance": "^0.30.0"
+    "@fonoster/conformance": "^0.31.0"
   }
 }