@fonoster/voice 0.5.5 → 0.6.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Fonoster Inc
+Copyright (c) 2024 Fonoster Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+<a href="https://gitpod.io/#https://github.com/fonoster/fonoster"> <img src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod" alt="Contribute with Gitpod" />
+
+This module is part of the [Fonoster](https://fonoster.com) project. By itself, it does not do much. It is intended to be used as a dependency for other modules. For more information about the project, please visit [https://github.com/fonoster/fonoster](https://github.com/fonoster/fonoster).

package/dist/VoiceResponse.d.ts

@@ -0,0 +1,218 @@
+import { DialOptions, GatherOptions, GatherResponse, MuteOptions, PlayOptions, PlayResponse, PlaybackControlAction, RecordOptions, RecordResponse, SayOptions, SayResponse, StreamOptions, VerbResponse, VoiceRequest, VoiceSessionStreamServer } from "@fonoster/common";
+import { DialStatusStream, Stream } from "./verbs";
+/**
+ * @classdesc Use the VoiceResponse object, to construct advance Interactive
+ * Voice Response (IVR) applications.
+ *
+ * @extends Verb
+ * @example
+ *
+ * import { VoiceServer } from "@fonoster/voice";
+ *
+ * async function handler (request, response) {
+ *   await response.answer();
+ *   await response.play("sound:hello-world");
+ * }
+ *
+ * const voiceServer = new VoiceServer({base: '/voiceapp'})
+ * voiceServer.listen(handler, { port: 3000 })
+ */
+declare class VoiceResponse {
+    voice: VoiceSessionStreamServer;
+    request: VoiceRequest;
+    /**
+     * Constructs a new VoiceResponse object.
+     *
+     * @param {VoiceRequest} request - Options to indicate the objects endpoint
+     * @param {VoiceSessionStream} voice - The voice session stream
+     * @see module:core:APIClient
+     */
+    constructor(request: VoiceRequest, voice: VoiceSessionStreamServer);
+    /**
+     * Answer the call. Before running any other verb you
+     * must run the anwer command.
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     * }
+     */
+    answer(): Promise<VerbResponse>;
+    /**
+     * Hangup the call.
+     * @example
+     *
+     * async function handler (request, response) {
+     *  await response.hangup();
+     * }
+     */
+    hangup(): Promise<VerbResponse>;
+    /**
+     * Play an audio in the call.
+     *
+     * @param {string} url - The URL of the media to play
+     * @param {PlayOptions} options - Options to control the playback
+     * @param {string} options.playbackRef - Playback identifier to use in Playback operations
+     * @see Playback
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.play("https://soundsserver:9000/sounds/hello-world.wav");
+     * }
+     */
+    play(url: string, options?: PlayOptions): Promise<PlayResponse>;
+    /**
+     * Play a series of DTMF digits in a call.
+     *
+     * @param {string} digits -The DTMF digits to play (0-9, #, or *)
+     * @example
+     *
+     * async function handler (request, response) {
+     *  await response.answer();
+     *  await response.playDtmf("1234");
+     * }
+     */
+    playDtmf(digits: string): Promise<void>;
+    /**
+     * Control the playback of the currently playing media.
+     *
+     * @param {string} playbackRef - The playback identifier
+     * @param {PlaybackControlAction} action - The action to perform (STOP, RESTART, PAUSE, UNPAUSE, FORWARD)
+     * @see play
+     * @example
+     *
+     * async function handler (request, response) {
+     *    await response.answer();
+     *    await response.play("https://s3.fonoster.io/uuid/hello-world.wav", { playbackRef: "playback-01" });
+     *
+     *    // Pause the media
+     *    await response.playbackControl("playback-01", PlaybackControlAction.PAUSE);
+     * }
+     */
+    playbackControl(playbackRef: string, action: PlaybackControlAction): Promise<VerbResponse>;
+    /**
+     * Waits for data entry from the user's keypad or from a speech provider.
+     *
+     * @param {GatherOptions} options - Options to select the maximum number of digits, final character, and timeout
+     * @param {number} options.maxDigits - Maximum number of digits to collect. Defaults to 1
+     * @param {number} options.timeout - Milliseconds to wait before timeout. Defaults to 4000. Use zero for no timeout.
+     * @param {string} options.finishOnKey - Optional last character to wait for. Defaults to '#'. It will not be included in the returned digits
+     * @param {GatherSource} options.source - Where to listen as input source. This option accepts `DTMF` and `SPEECH`. A speech provider must be configure
+     * when including the `SPEECH` source. You might inclue both with `SPEECH_AND_DTMF`. Defaults to `SPEECH_AND_DTMF`
+     * @note When including `SPEECH` the default timeout is 10000 (10s).
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const speech = await response.gather({ source: GatherSource.SPEECH, numDigits: 3 });
+     *   console.log("speech: " + speech);
+     *   await response.hangup();
+     * }
+     */
+    gather(options?: GatherOptions): Promise<GatherResponse>;
+    /**
+     * Send a text for a TTS engine to convert to speech.
+     *
+     * @param {string} text - The text to convert to speech
+     * @param {SayOptions} options - Options to control the TTS engine
+     * @param {string} options.playbackRef - Playback identifier to use in Playback operations
+     * @param {TTSOptions} options.ttsOptions - Options to control the TTS engine (specific to the TTS engine)
+     * @see Say
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const playbackRef = await response.say("Hello World");
+     *
+     *   // Like the play verb, you can control the playback
+     *   await response.playbackControl(playbackRef, PlaybackControlAction.STOP);
+     * }
+     */
+    say(text: string, options?: SayOptions): Promise<SayResponse>;
+    /**
+     * Record the audio of the call.
+     *
+     * @param {RecordOptions} options - Options to control the record operation
+     * @param {number} options.maxDuration - The maximum duration of the recording in seconds. Default is 60
+     * @param {number} options.maxSilence - The maximum duration of silence in seconds. Default is 5
+     * @param {boolean} options.beep - Play a beep before recording. Default is true
+     * @param {string} options.finishOnKey - Stop recording when a DTMF digit is received. Default is '#'
+     * @return {RecordResponse} The record response
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const record = await response.record();
+     *   console.log("Recording: %s", record.name);
+     * }
+     */
+    record(options?: RecordOptions): Promise<RecordResponse>;
+    /**
+     * Dials a destination and returns a stream of status.
+     *
+     * @param {string} destination - The destination to dial
+     * @param {DialOptions} options - Options to control the dial operation
+     * @param {number} options.timeout - The timeout in seconds. Default is 60
+     * @param {RecordDirection} options.recordDirection - The direction to record the call (IN, OUT, BOTH). Default is BOTH
+     * @return {Promise<DialStatusStream>} The dial status stream
+     */
+    dial(destination: string, options?: DialOptions): Promise<DialStatusStream>;
+    /**
+     * Starts a bidirectional audio stream between the call and the application.
+     *
+     * @param {StreamOptions} options - Options to control the stream operation
+     * @param {StreamDirection} options.direction - The direction to stream the audio (IN, OUT, BOTH). Default is BOTH
+     * @param {StreamAudioFormat} options.format - The audio format to stream (WAV). Default is WAV
+     * @param {boolean} options.enableVad - Enable voice activity detection. Default is false
+     * @return {Promise<Stream>} The stream object
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *
+     *   const stream = await response.stream({
+     *     direction: StreamDirection.BOTH,
+     *     format: StreamAudioFormat.WAV,
+     *     enableVad: true
+     *   });
+     *
+     *   stream.onPayload((payload) => {
+     *     // Use the payload
+     *   });
+     *
+     *   // Or write to the stream
+     *   // stream.write({ type: StreamMessageType.AUDIO_OUT, payload: "\x00\x01\x02" });
+     * }
+     */
+    stream(options: StreamOptions): Promise<Stream>;
+    /**
+     * Mutes a call.
+     *
+     * @param {MuteOptions} options - Options to control the mute operation
+     * @param {MuteDirection} options.direction - The direction to mute the channel (IN, OUT, BOTH). Default is BOTH
+     * @see unmute
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.mute();       // Will mute both directions
+     * }
+     */
+    mute(options?: MuteOptions): Promise<void>;
+    /**
+     * Unmutes a call.
+     *
+     * @param {MuteOptions} options - Options to control the unmute operation
+     * @param {MuteDirection} options.direction - The direction to unmute the call (IN, OUT, BOTH). Default is BOTH
+     * @see mute
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.unmute();     // Will unmute both directions
+     * }
+     */
+    unmute(options?: MuteOptions): Promise<void>;
+}
+export { VoiceResponse };

package/dist/VoiceResponse.js

@@ -0,0 +1,352 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceResponse = void 0;
+/*
+ * Copyright (C) 2024 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.
+ */
+const common_1 = require("@fonoster/common");
+const pb_util_1 = require("pb-util");
+const verbs_1 = require("./verbs");
+/**
+ * @classdesc Use the VoiceResponse object, to construct advance Interactive
+ * Voice Response (IVR) applications.
+ *
+ * @extends Verb
+ * @example
+ *
+ * import { VoiceServer } from "@fonoster/voice";
+ *
+ * async function handler (request, response) {
+ *   await response.answer();
+ *   await response.play("sound:hello-world");
+ * }
+ *
+ * const voiceServer = new VoiceServer({base: '/voiceapp'})
+ * voiceServer.listen(handler, { port: 3000 })
+ */
+class VoiceResponse {
+    /**
+     * Constructs a new VoiceResponse object.
+     *
+     * @param {VoiceRequest} request - Options to indicate the objects endpoint
+     * @param {VoiceSessionStream} voice - The voice session stream
+     * @see module:core:APIClient
+     */
+    constructor(request, voice) {
+        this.voice = voice;
+        this.request = request;
+    }
+    /**
+     * Answer the call. Before running any other verb you
+     * must run the anwer command.
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     * }
+     */
+    answer() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield new verbs_1.Answer(this.request, this.voice).run();
+            return { sessionRef: this.request.sessionRef };
+        });
+    }
+    /**
+     * Hangup the call.
+     * @example
+     *
+     * async function handler (request, response) {
+     *  await response.hangup();
+     * }
+     */
+    hangup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield new verbs_1.Hangup(this.request, this.voice).run();
+            return { sessionRef: this.request.sessionRef };
+        });
+    }
+    /**
+     * Play an audio in the call.
+     *
+     * @param {string} url - The URL of the media to play
+     * @param {PlayOptions} options - Options to control the playback
+     * @param {string} options.playbackRef - Playback identifier to use in Playback operations
+     * @see Playback
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.play("https://soundsserver:9000/sounds/hello-world.wav");
+     * }
+     */
+    play(url, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield new verbs_1.Play(this.request, this.voice).run(Object.assign(Object.assign({}, options), { sessionRef: this.request.sessionRef, url }));
+            return response.playResponse;
+        });
+    }
+    /**
+     * Play a series of DTMF digits in a call.
+     *
+     * @param {string} digits -The DTMF digits to play (0-9, #, or *)
+     * @example
+     *
+     * async function handler (request, response) {
+     *  await response.answer();
+     *  await response.playDtmf("1234");
+     * }
+     */
+    playDtmf(digits) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield new verbs_1.PlayDtmf(this.request, this.voice).run({
+                sessionRef: this.request.sessionRef,
+                digits
+            });
+        });
+    }
+    /**
+     * Control the playback of the currently playing media.
+     *
+     * @param {string} playbackRef - The playback identifier
+     * @param {PlaybackControlAction} action - The action to perform (STOP, RESTART, PAUSE, UNPAUSE, FORWARD)
+     * @see play
+     * @example
+     *
+     * async function handler (request, response) {
+     *    await response.answer();
+     *    await response.play("https://s3.fonoster.io/uuid/hello-world.wav", { playbackRef: "playback-01" });
+     *
+     *    // Pause the media
+     *    await response.playbackControl("playback-01", PlaybackControlAction.PAUSE);
+     * }
+     */
+    playbackControl(playbackRef, action) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield new verbs_1.PlaybackControl(this.request, this.voice).run({
+                sessionRef: this.request.sessionRef,
+                playbackRef,
+                action
+            });
+            return { sessionRef: this.request.sessionRef };
+        });
+    }
+    /**
+     * Waits for data entry from the user's keypad or from a speech provider.
+     *
+     * @param {GatherOptions} options - Options to select the maximum number of digits, final character, and timeout
+     * @param {number} options.maxDigits - Maximum number of digits to collect. Defaults to 1
+     * @param {number} options.timeout - Milliseconds to wait before timeout. Defaults to 4000. Use zero for no timeout.
+     * @param {string} options.finishOnKey - Optional last character to wait for. Defaults to '#'. It will not be included in the returned digits
+     * @param {GatherSource} options.source - Where to listen as input source. This option accepts `DTMF` and `SPEECH`. A speech provider must be configure
+     * when including the `SPEECH` source. You might inclue both with `SPEECH_AND_DTMF`. Defaults to `SPEECH_AND_DTMF`
+     * @note When including `SPEECH` the default timeout is 10000 (10s).
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const speech = await response.gather({ source: GatherSource.SPEECH, numDigits: 3 });
+     *   console.log("speech: " + speech);
+     *   await response.hangup();
+     * }
+     */
+    gather() {
+        return __awaiter(this, arguments, void 0, function* (options = { source: common_1.GatherSource.SPEECH_AND_DTMF }) {
+            const response = yield new verbs_1.Gather(this.request, this.voice).run(Object.assign({ sessionRef: this.request.sessionRef }, options));
+            return response.gatherResponse;
+        });
+    }
+    /**
+     * Send a text for a TTS engine to convert to speech.
+     *
+     * @param {string} text - The text to convert to speech
+     * @param {SayOptions} options - Options to control the TTS engine
+     * @param {string} options.playbackRef - Playback identifier to use in Playback operations
+     * @param {TTSOptions} options.ttsOptions - Options to control the TTS engine (specific to the TTS engine)
+     * @see Say
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const playbackRef = await response.say("Hello World");
+     *
+     *   // Like the play verb, you can control the playback
+     *   await response.playbackControl(playbackRef, PlaybackControlAction.STOP);
+     * }
+     */
+    say(text, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield new verbs_1.Say(this.request, this.voice).run({
+                playbackRef: options === null || options === void 0 ? void 0 : options.playbackRef,
+                options: options ? pb_util_1.struct.encode(options) : undefined,
+                sessionRef: this.request.sessionRef,
+                text
+            });
+            return { playbackRef: response.sayResponse.playbackRef };
+        });
+    }
+    /**
+     * Record the audio of the call.
+     *
+     * @param {RecordOptions} options - Options to control the record operation
+     * @param {number} options.maxDuration - The maximum duration of the recording in seconds. Default is 60
+     * @param {number} options.maxSilence - The maximum duration of silence in seconds. Default is 5
+     * @param {boolean} options.beep - Play a beep before recording. Default is true
+     * @param {string} options.finishOnKey - Stop recording when a DTMF digit is received. Default is '#'
+     * @return {RecordResponse} The record response
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   const record = await response.record();
+     *   console.log("Recording: %s", record.name);
+     * }
+     */
+    record(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield new verbs_1.Record(this.request, this.voice).run(Object.assign({ sessionRef: this.request.sessionRef }, options));
+            return response.recordResponse;
+        });
+    }
+    /**
+     * Dials a destination and returns a stream of status.
+     *
+     * @param {string} destination - The destination to dial
+     * @param {DialOptions} options - Options to control the dial operation
+     * @param {number} options.timeout - The timeout in seconds. Default is 60
+     * @param {RecordDirection} options.recordDirection - The direction to record the call (IN, OUT, BOTH). Default is BOTH
+     * @return {Promise<DialStatusStream>} The dial status stream
+     */
+    dial(destination, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stream = new verbs_1.DialStatusStream();
+            yield new verbs_1.Dial(this.request, this.voice).run(Object.assign({ sessionRef: this.request.sessionRef, destination }, options));
+            this.voice.on(common_1.StreamEvent.DATA, (result) => {
+                if (result.dialResponse) {
+                    stream.emit(result.dialResponse.status);
+                }
+            });
+            return stream;
+        });
+    }
+    /**
+     * Starts a bidirectional audio stream between the call and the application.
+     *
+     * @param {StreamOptions} options - Options to control the stream operation
+     * @param {StreamDirection} options.direction - The direction to stream the audio (IN, OUT, BOTH). Default is BOTH
+     * @param {StreamAudioFormat} options.format - The audio format to stream (WAV). Default is WAV
+     * @param {boolean} options.enableVad - Enable voice activity detection. Default is false
+     * @return {Promise<Stream>} The stream object
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *
+     *   const stream = await response.stream({
+     *     direction: StreamDirection.BOTH,
+     *     format: StreamAudioFormat.WAV,
+     *     enableVad: true
+     *   });
+     *
+     *   stream.onPayload((payload) => {
+     *     // Use the payload
+     *   });
+     *
+     *   // Or write to the stream
+     *   // stream.write({ type: StreamMessageType.AUDIO_OUT, payload: "\x00\x01\x02" });
+     * }
+     */
+    stream(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stream = new verbs_1.Stream();
+            const startStream = new verbs_1.StartStream(this.request, this.voice);
+            const stopStream = new verbs_1.StopStream(this.request, this.voice);
+            const { startStreamResponse } = yield startStream.run(Object.assign({ sessionRef: this.request.sessionRef }, options));
+            this.voice.on(common_1.StreamEvent.DATA, (result) => {
+                if (result.streamPayload) {
+                    stream.emit("payloadOut", result.streamPayload);
+                }
+            });
+            stream.onPayloadIn((payload) => {
+                this.voice.write({
+                    streamPayload: payload
+                });
+            });
+            stream.cleanup(() => {
+                stopStream.run({
+                    sessionRef: this.request.sessionRef,
+                    streamRef: startStreamResponse === null || startStreamResponse === void 0 ? void 0 : startStreamResponse.streamRef
+                });
+            });
+            return stream;
+        });
+    }
+    /**
+     * Mutes a call.
+     *
+     * @param {MuteOptions} options - Options to control the mute operation
+     * @param {MuteDirection} options.direction - The direction to mute the channel (IN, OUT, BOTH). Default is BOTH
+     * @see unmute
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.mute();       // Will mute both directions
+     * }
+     */
+    mute() {
+        return __awaiter(this, arguments, void 0, function* (options = { direction: common_1.MuteDirection.BOTH }) {
+            const { direction } = options;
+            yield new verbs_1.Mute(this.request, this.voice).run({
+                sessionRef: this.request.sessionRef,
+                direction
+            });
+        });
+    }
+    /**
+     * Unmutes a call.
+     *
+     * @param {MuteOptions} options - Options to control the unmute operation
+     * @param {MuteDirection} options.direction - The direction to unmute the call (IN, OUT, BOTH). Default is BOTH
+     * @see mute
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.answer();
+     *   await response.unmute();     // Will unmute both directions
+     * }
+     */
+    unmute() {
+        return __awaiter(this, arguments, void 0, function* (options = { direction: common_1.MuteDirection.BOTH }) {
+            const { direction } = options;
+            yield new verbs_1.Unmute(this.request, this.voice).run({
+                sessionRef: this.request.sessionRef,
+                direction
+            });
+        });
+    }
+}
+exports.VoiceResponse = VoiceResponse;

package/dist/VoiceServer.d.ts

@@ -0,0 +1,6 @@
+import { ServerConfig, VoiceHandler } from "./types";
+export default class VoiceServer {
+    config: ServerConfig;
+    constructor(config?: ServerConfig);
+    listen(handler: VoiceHandler): Promise<void>;
+}