@signalwire/sdk 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/AgentBase.ts +113 -4
- package/src/AgentServer.ts +31 -4
- package/src/ContextBuilder.ts +33 -2
- package/src/DataMap.ts +30 -2
- package/src/FunctionResult.ts +40 -3
- package/src/PomBuilder.ts +29 -1
- package/src/SWMLService.ts +38 -6
- package/src/ServerlessAdapter.ts +20 -1
- package/src/SwmlBuilder.ts +26 -1
- package/src/TypeInference.ts +27 -9
- package/src/WebService.ts +27 -5
- package/src/index.ts +73 -7
- package/src/livewire/index.ts +343 -41
- package/src/prefabs/ConciergeAgent.ts +22 -0
- package/src/prefabs/FAQBotAgent.ts +32 -1
- package/src/prefabs/InfoGathererAgent.ts +41 -1
- package/src/prefabs/ReceptionistAgent.ts +30 -1
- package/src/prefabs/SurveyAgent.ts +26 -1
- package/src/relay/Action.ts +174 -6
- package/src/relay/Call.ts +459 -43
- package/src/relay/Deferred.ts +27 -4
- package/src/relay/Message.ts +54 -3
- package/src/relay/RelayClient.ts +167 -18
- package/src/relay/RelayError.ts +7 -1
- package/src/relay/RelayEvent.ts +52 -0
- package/src/rest/HttpClient.ts +61 -0
- package/src/rest/RestError.ts +14 -0
- package/src/rest/base/BaseResource.ts +16 -3
- package/src/rest/base/CrudResource.ts +52 -5
- package/src/rest/base/CrudWithAddresses.ts +12 -1
- package/src/rest/index.ts +30 -0
- package/src/rest/namespaces/addresses.ts +33 -1
- package/src/rest/namespaces/calling.ts +348 -1
- package/src/rest/namespaces/chat.ts +13 -2
- package/src/rest/namespaces/compat.ts +469 -9
- package/src/rest/namespaces/datasphere.ts +48 -5
- package/src/rest/namespaces/fabric.ts +197 -2
- package/src/rest/namespaces/imported-numbers.ts +13 -2
- package/src/rest/namespaces/logs.ts +68 -1
- package/src/rest/namespaces/lookup.ts +19 -2
- package/src/rest/namespaces/mfa.ts +35 -4
- package/src/rest/namespaces/number-groups.ts +35 -5
- package/src/rest/namespaces/phone-numbers.ts +35 -3
- package/src/rest/namespaces/project.ts +30 -1
- package/src/rest/namespaces/pubsub.ts +13 -2
- package/src/rest/namespaces/queues.ts +29 -4
- package/src/rest/namespaces/recordings.ts +26 -1
- package/src/rest/namespaces/registry.ts +100 -1
- package/src/rest/namespaces/short-codes.ts +27 -1
- package/src/rest/namespaces/sip-profile.ts +18 -3
- package/src/rest/namespaces/verified-callers.ts +22 -3
- package/src/rest/namespaces/video.ts +168 -1
- package/src/rest/pagination.ts +22 -8
- package/src/skills/SkillBase.ts +37 -2
- package/src/skills/SkillManager.ts +8 -4
- package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
- package/src/skills/builtin/ask_claude.ts +5 -0
- package/src/skills/builtin/claude_skills.ts +5 -0
- package/src/skills/builtin/custom_skills.ts +15 -0
- package/src/skills/builtin/datasphere.ts +9 -0
- package/src/skills/builtin/datasphere_serverless.ts +8 -0
- package/src/skills/builtin/datetime.ts +7 -0
- package/src/skills/builtin/google_maps.ts +5 -0
- package/src/skills/builtin/info_gatherer.ts +10 -0
- package/src/skills/builtin/joke.ts +5 -0
- package/src/skills/builtin/math.ts +7 -0
- package/src/skills/builtin/mcp_gateway.ts +8 -0
- package/src/skills/builtin/native_vector_search.ts +9 -0
- package/src/skills/builtin/play_background_file.ts +9 -0
- package/src/skills/builtin/spider.ts +5 -0
- package/src/skills/builtin/swml_transfer.ts +10 -0
- package/src/skills/builtin/weather_api.ts +7 -0
- package/src/skills/builtin/web_search.ts +9 -0
- package/src/skills/builtin/wikipedia_search.ts +5 -0
|
@@ -12,6 +12,7 @@ import type { AgentOptions } from '../types.js';
|
|
|
12
12
|
|
|
13
13
|
// ── Config types ────────────────────────────────────────────────────────────
|
|
14
14
|
|
|
15
|
+
/** Configuration for the {@link ConciergeAgent}. */
|
|
15
16
|
export interface ConciergeConfig {
|
|
16
17
|
/** Name of the venue or business (required). */
|
|
17
18
|
venueName: string;
|
|
@@ -38,6 +39,27 @@ export interface ConciergeConfig {
|
|
|
38
39
|
/**
|
|
39
40
|
* Prefab agent that acts as a virtual concierge for a venue, providing information
|
|
40
41
|
* about services, amenities, hours of operation, availability, and directions.
|
|
42
|
+
*
|
|
43
|
+
* @example Hotel concierge
|
|
44
|
+
* ```ts
|
|
45
|
+
* import { ConciergeAgent } from '@signalwire/sdk';
|
|
46
|
+
*
|
|
47
|
+
* const agent = new ConciergeAgent({
|
|
48
|
+
* venueName: 'The Park Hotel',
|
|
49
|
+
* services: ['Room service', 'Valet parking', 'Spa', 'Restaurant'],
|
|
50
|
+
* hoursOfOperation: {
|
|
51
|
+
* restaurant: '7 AM - 10 PM daily',
|
|
52
|
+
* spa: '9 AM - 9 PM daily',
|
|
53
|
+
* default: '24 hours',
|
|
54
|
+
* },
|
|
55
|
+
* amenities: {
|
|
56
|
+
* pool: { location: 'Rooftop', hours: '6 AM - 10 PM' },
|
|
57
|
+
* gym: { location: 'Floor 2', hours: '24 hours' },
|
|
58
|
+
* },
|
|
59
|
+
* });
|
|
60
|
+
*
|
|
61
|
+
* await agent.serve({ port: 3000 });
|
|
62
|
+
* ```
|
|
41
63
|
*/
|
|
42
64
|
export class ConciergeAgent extends AgentBase {
|
|
43
65
|
/** Name of the venue or business. */
|
|
@@ -14,6 +14,7 @@ import type { AgentOptions } from '../types.js';
|
|
|
14
14
|
|
|
15
15
|
// ── Config types ────────────────────────────────────────────────────────────
|
|
16
16
|
|
|
17
|
+
/** A single frequently-asked-question entry consumed by {@link FAQBotAgent}. */
|
|
17
18
|
export interface FAQEntry {
|
|
18
19
|
/** The representative question text. */
|
|
19
20
|
question: string;
|
|
@@ -25,6 +26,7 @@ export interface FAQEntry {
|
|
|
25
26
|
categories?: string[];
|
|
26
27
|
}
|
|
27
28
|
|
|
29
|
+
/** Configuration for the {@link FAQBotAgent}. */
|
|
28
30
|
export interface FAQBotConfig {
|
|
29
31
|
/** Agent display name (defaults to `"faq_bot"`). */
|
|
30
32
|
name?: string;
|
|
@@ -48,7 +50,36 @@ export interface FAQBotConfig {
|
|
|
48
50
|
|
|
49
51
|
// ── Agent ───────────────────────────────────────────────────────────────────
|
|
50
52
|
|
|
51
|
-
/**
|
|
53
|
+
/**
|
|
54
|
+
* Prefab agent that answers frequently asked questions using keyword matching with optional escalation to a live agent.
|
|
55
|
+
*
|
|
56
|
+
* Pass an array of `{ question, answer, keywords }` entries and the agent will
|
|
57
|
+
* fuzzy-match inbound utterances against them. If no match crosses the confidence
|
|
58
|
+
* threshold, the call can optionally escalate to a configured phone number.
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* ```ts
|
|
62
|
+
* import { FAQBotAgent } from '@signalwire/sdk';
|
|
63
|
+
*
|
|
64
|
+
* const agent = new FAQBotAgent({
|
|
65
|
+
* faqs: [
|
|
66
|
+
* {
|
|
67
|
+
* question: 'What are your business hours?',
|
|
68
|
+
* answer: "We're open 9 AM to 5 PM Pacific, Monday through Friday.",
|
|
69
|
+
* keywords: ['hours', 'open', 'closed', 'time'],
|
|
70
|
+
* },
|
|
71
|
+
* {
|
|
72
|
+
* question: 'Where are you located?',
|
|
73
|
+
* answer: 'Our headquarters are in San Francisco, California.',
|
|
74
|
+
* keywords: ['location', 'address', 'office'],
|
|
75
|
+
* },
|
|
76
|
+
* ],
|
|
77
|
+
* escalationNumber: '+15551234567',
|
|
78
|
+
* });
|
|
79
|
+
*
|
|
80
|
+
* await agent.serve({ port: 3000 });
|
|
81
|
+
* ```
|
|
82
|
+
*/
|
|
52
83
|
export class FAQBotAgent extends AgentBase {
|
|
53
84
|
/** The configured FAQ entries. */
|
|
54
85
|
public faqs: FAQEntry[];
|
|
@@ -63,7 +63,47 @@ const FALLBACK_QUESTIONS: InfoGathererQuestion[] = [
|
|
|
63
63
|
{ key_name: 'message', question_text: 'How can I help you today?' },
|
|
64
64
|
];
|
|
65
65
|
|
|
66
|
-
/**
|
|
66
|
+
/**
|
|
67
|
+
* Prefab agent that gathers caller information one question at a time.
|
|
68
|
+
*
|
|
69
|
+
* Supports two modes:
|
|
70
|
+
*
|
|
71
|
+
* - **Static** — provide `questions` at construction; the same questions are
|
|
72
|
+
* asked on every call.
|
|
73
|
+
* - **Dynamic** — leave `questions` unset and register a callback via
|
|
74
|
+
* `questionCallback` (or `setQuestionCallback()`); the callback decides which
|
|
75
|
+
* questions to ask per incoming call based on query params, body, or headers.
|
|
76
|
+
*
|
|
77
|
+
* @example Static questions
|
|
78
|
+
* ```ts
|
|
79
|
+
* import { InfoGathererAgent } from '@signalwire/sdk';
|
|
80
|
+
*
|
|
81
|
+
* const agent = new InfoGathererAgent({
|
|
82
|
+
* questions: [
|
|
83
|
+
* { key_name: 'name', question_text: 'What is your name?' },
|
|
84
|
+
* { key_name: 'email', question_text: 'What is your email address?', confirm: true },
|
|
85
|
+
* { key_name: 'issue', question_text: 'How can we help?' },
|
|
86
|
+
* ],
|
|
87
|
+
* });
|
|
88
|
+
*
|
|
89
|
+
* await agent.serve({ port: 3000 });
|
|
90
|
+
* ```
|
|
91
|
+
*
|
|
92
|
+
* @example Dynamic questions per request
|
|
93
|
+
* ```ts
|
|
94
|
+
* const agent = new InfoGathererAgent({
|
|
95
|
+
* questionCallback: async (query) => {
|
|
96
|
+
* if (query.intake === 'medical') {
|
|
97
|
+
* return [
|
|
98
|
+
* { key_name: 'dob', question_text: 'Date of birth?' },
|
|
99
|
+
* { key_name: 'insurance_id', question_text: 'Insurance member ID?' },
|
|
100
|
+
* ];
|
|
101
|
+
* }
|
|
102
|
+
* return [{ key_name: 'message', question_text: 'How can I help?' }];
|
|
103
|
+
* },
|
|
104
|
+
* });
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
67
107
|
export class InfoGathererAgent extends AgentBase {
|
|
68
108
|
private staticQuestions: InfoGathererQuestion[] | null;
|
|
69
109
|
private questionCallback: InfoGathererQuestionCallback | null = null;
|
|
@@ -13,6 +13,7 @@ import type { AgentOptions } from '../types.js';
|
|
|
13
13
|
|
|
14
14
|
// ── Config types ────────────────────────────────────────────────────────────
|
|
15
15
|
|
|
16
|
+
/** A department the receptionist can route callers to. */
|
|
16
17
|
export interface ReceptionistDepartment {
|
|
17
18
|
/** Department identifier (e.g. `"sales"`, `"support"`). */
|
|
18
19
|
name: string;
|
|
@@ -22,6 +23,7 @@ export interface ReceptionistDepartment {
|
|
|
22
23
|
number: string;
|
|
23
24
|
}
|
|
24
25
|
|
|
26
|
+
/** Configuration for the {@link ReceptionistAgent}. */
|
|
25
27
|
export interface ReceptionistConfig {
|
|
26
28
|
/** Departments the agent can transfer callers to. */
|
|
27
29
|
departments: ReceptionistDepartment[];
|
|
@@ -51,7 +53,34 @@ interface CheckInSession {
|
|
|
51
53
|
|
|
52
54
|
// ── Agent ───────────────────────────────────────────────────────────────────
|
|
53
55
|
|
|
54
|
-
/**
|
|
56
|
+
/**
|
|
57
|
+
* Prefab agent that greets callers, collects basic information, and transfers them to the correct department.
|
|
58
|
+
*
|
|
59
|
+
* Optionally supports visitor check-in — when enabled, the agent can collect a visitor's name
|
|
60
|
+
* and purpose-of-visit and invoke a callback (e.g., notify reception via Slack, write to a
|
|
61
|
+
* database). If not transferring, the call ends after check-in.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* ```ts
|
|
65
|
+
* import { ReceptionistAgent } from '@signalwire/sdk';
|
|
66
|
+
*
|
|
67
|
+
* const agent = new ReceptionistAgent({
|
|
68
|
+
* companyName: 'Acme Co',
|
|
69
|
+
* greeting: 'Thanks for calling Acme! How can I direct your call?',
|
|
70
|
+
* departments: [
|
|
71
|
+
* { name: 'sales', description: 'New customer inquiries', number: '+15551112222' },
|
|
72
|
+
* { name: 'support', description: 'Existing customer help', number: '+15553334444' },
|
|
73
|
+
* { name: 'billing', description: 'Billing and payments', number: '+15555556666' },
|
|
74
|
+
* ],
|
|
75
|
+
* checkInEnabled: true,
|
|
76
|
+
* onVisitorCheckIn: async (visitor) => {
|
|
77
|
+
* await notifyFrontDesk(visitor);
|
|
78
|
+
* },
|
|
79
|
+
* });
|
|
80
|
+
*
|
|
81
|
+
* await agent.serve({ port: 3000 });
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
55
84
|
export class ReceptionistAgent extends AgentBase {
|
|
56
85
|
private readonly greeting: string;
|
|
57
86
|
private readonly departments: ReceptionistDepartment[];
|
|
@@ -13,6 +13,7 @@ import type { AgentOptions } from '../types.js';
|
|
|
13
13
|
|
|
14
14
|
// ── Config types ────────────────────────────────────────────────────────────
|
|
15
15
|
|
|
16
|
+
/** A single survey question consumed by {@link SurveyAgent}. */
|
|
16
17
|
export interface SurveyQuestion {
|
|
17
18
|
/** Unique question identifier. */
|
|
18
19
|
id: string;
|
|
@@ -47,6 +48,7 @@ export interface SurveyQuestion {
|
|
|
47
48
|
points?: number | Record<string, number>;
|
|
48
49
|
}
|
|
49
50
|
|
|
51
|
+
/** Configuration for the {@link SurveyAgent}. */
|
|
50
52
|
export interface SurveyConfig {
|
|
51
53
|
/** Human-readable survey name, used in prompts and global data. */
|
|
52
54
|
surveyName: string;
|
|
@@ -82,7 +84,30 @@ interface SurveySession {
|
|
|
82
84
|
|
|
83
85
|
// ── Agent ───────────────────────────────────────────────────────────────────
|
|
84
86
|
|
|
85
|
-
/**
|
|
87
|
+
/**
|
|
88
|
+
* Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow.
|
|
89
|
+
*
|
|
90
|
+
* Each survey question declares its response type (rating, yes/no, open text, etc.), an optional
|
|
91
|
+
* set of conditional follow-ups, and a scoring map. The agent walks the question tree, tallies a
|
|
92
|
+
* total score, and exposes the full response map at call end via `onSummary()`.
|
|
93
|
+
*
|
|
94
|
+
* @example Customer satisfaction survey
|
|
95
|
+
* ```ts
|
|
96
|
+
* import { SurveyAgent } from '@signalwire/sdk';
|
|
97
|
+
*
|
|
98
|
+
* const agent = new SurveyAgent({
|
|
99
|
+
* surveyName: 'CSAT',
|
|
100
|
+
* brandName: 'Acme Co',
|
|
101
|
+
* questions: [
|
|
102
|
+
* { id: 'q1', text: 'How satisfied were you with our service?', type: 'rating', scale: 5 },
|
|
103
|
+
* { id: 'q2', text: 'Would you recommend us to a friend?', type: 'yesno' },
|
|
104
|
+
* { id: 'q3', text: 'Anything else you want to share?', type: 'open' },
|
|
105
|
+
* ],
|
|
106
|
+
* });
|
|
107
|
+
*
|
|
108
|
+
* await agent.serve({ port: 3000 });
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
86
111
|
export class SurveyAgent extends AgentBase {
|
|
87
112
|
/** Human-readable survey name. */
|
|
88
113
|
public surveyName: string;
|
package/src/relay/Action.ts
CHANGED
|
@@ -27,23 +27,51 @@ import type { CompletedCallback } from './types.js';
|
|
|
27
27
|
|
|
28
28
|
const logger = getLogger('relay_action');
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Structural subset of {@link Call} that an Action needs — avoids a circular
|
|
32
|
+
* import between `Call.ts` and `Action.ts`.
|
|
33
|
+
*/
|
|
31
34
|
export interface CallLike {
|
|
32
35
|
_execute(method: string, extraParams?: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
33
36
|
}
|
|
34
37
|
|
|
35
38
|
// ─── Base Action ─────────────────────────────────────────────────────
|
|
36
39
|
|
|
40
|
+
/**
|
|
41
|
+
* Async handle for a controllable call operation (play, record, tap, detect, etc.).
|
|
42
|
+
*
|
|
43
|
+
* An Action is returned from the async variants on {@link Call} (e.g. `call.playAsync`).
|
|
44
|
+
* It resolves when the server emits a terminal event for its `controlId`. Use
|
|
45
|
+
* {@link Action.wait} to await completion, or register an `onCompleted` callback.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```ts
|
|
49
|
+
* const play = await call.playAsync({ play: [{ type: 'tts', text: 'Hello!' }] });
|
|
50
|
+
* // do other work while the greeting plays...
|
|
51
|
+
* const event = await play.wait(10); // seconds
|
|
52
|
+
* console.log('Playback finished with state', event.params.state);
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
37
55
|
export class Action {
|
|
56
|
+
/** Reference to the owning call. */
|
|
38
57
|
readonly call: CallLike;
|
|
58
|
+
/** Unique control ID used by the server to route events back to this action. */
|
|
39
59
|
readonly controlId: string;
|
|
40
60
|
protected readonly _terminalEvent: string;
|
|
41
61
|
protected readonly _terminalStates: readonly string[];
|
|
42
62
|
/** @internal */ readonly _done: Deferred<RelayEvent>;
|
|
63
|
+
/** Final event once the action terminates, or `null` while still running. */
|
|
43
64
|
result: RelayEvent | null = null;
|
|
65
|
+
/** Whether the action has reached a terminal state. */
|
|
44
66
|
completed = false;
|
|
45
67
|
/** @internal */ _onCompleted: CompletedCallback | null = null;
|
|
46
68
|
|
|
69
|
+
/**
|
|
70
|
+
* @param call - Owning call (via the structural {@link CallLike} interface).
|
|
71
|
+
* @param controlId - Unique control ID the server will echo on events.
|
|
72
|
+
* @param terminalEvent - Event type that carries terminal state transitions.
|
|
73
|
+
* @param terminalStates - State values that mark this action as completed.
|
|
74
|
+
*/
|
|
47
75
|
constructor(
|
|
48
76
|
call: CallLike,
|
|
49
77
|
controlId: string,
|
|
@@ -87,8 +115,12 @@ export class Action {
|
|
|
87
115
|
}
|
|
88
116
|
|
|
89
117
|
/**
|
|
90
|
-
* Wait for the action to complete.
|
|
91
|
-
*
|
|
118
|
+
* Wait for the action to complete.
|
|
119
|
+
*
|
|
120
|
+
* @param timeout - Maximum time to wait in **seconds** (matches the Python
|
|
121
|
+
* SDK convention — not milliseconds).
|
|
122
|
+
* @returns The terminal {@link RelayEvent} for this action.
|
|
123
|
+
* @throws {Error} When the optional timeout elapses before the action ends.
|
|
92
124
|
*/
|
|
93
125
|
async wait(timeout?: number): Promise<RelayEvent> {
|
|
94
126
|
if (timeout != null) {
|
|
@@ -97,16 +129,22 @@ export class Action {
|
|
|
97
129
|
const timer = setTimeout(() => {
|
|
98
130
|
reject(new Error(`Action wait timed out after ${timeout}s`));
|
|
99
131
|
}, ms);
|
|
100
|
-
|
|
101
132
|
this._done.promise.then(
|
|
102
|
-
(v) => {
|
|
103
|
-
|
|
133
|
+
(v) => {
|
|
134
|
+
clearTimeout(timer);
|
|
135
|
+
resolve(v);
|
|
136
|
+
},
|
|
137
|
+
(e) => {
|
|
138
|
+
clearTimeout(timer);
|
|
139
|
+
reject(e);
|
|
140
|
+
},
|
|
104
141
|
);
|
|
105
142
|
});
|
|
106
143
|
}
|
|
107
144
|
return this._done.promise;
|
|
108
145
|
}
|
|
109
146
|
|
|
147
|
+
/** True once the action has reached a terminal state. */
|
|
110
148
|
get isDone(): boolean {
|
|
111
149
|
return this._done.settled;
|
|
112
150
|
}
|
|
@@ -114,23 +152,49 @@ export class Action {
|
|
|
114
152
|
|
|
115
153
|
// ─── PlayAction ──────────────────────────────────────────────────────
|
|
116
154
|
|
|
155
|
+
/** Async handle for a `calling.call.play` action — controls playback in progress. */
|
|
117
156
|
export class PlayAction extends Action {
|
|
118
157
|
constructor(call: CallLike, controlId: string) {
|
|
119
158
|
super(call, controlId, EVENT_CALL_PLAY, [PLAY_STATE_FINISHED, PLAY_STATE_ERROR]);
|
|
120
159
|
}
|
|
121
160
|
|
|
161
|
+
/**
|
|
162
|
+
* Stop the playback.
|
|
163
|
+
*
|
|
164
|
+
* @returns The platform's stop response.
|
|
165
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
166
|
+
*/
|
|
122
167
|
async stop(): Promise<Record<string, unknown>> {
|
|
123
168
|
return this.call._execute('play.stop', { control_id: this.controlId });
|
|
124
169
|
}
|
|
125
170
|
|
|
171
|
+
/**
|
|
172
|
+
* Pause active playback (resumable with {@link resume}).
|
|
173
|
+
*
|
|
174
|
+
* @returns The platform's pause response.
|
|
175
|
+
* @throws {RelayError} When the pause command is rejected.
|
|
176
|
+
*/
|
|
126
177
|
async pause(): Promise<Record<string, unknown>> {
|
|
127
178
|
return this.call._execute('play.pause', { control_id: this.controlId });
|
|
128
179
|
}
|
|
129
180
|
|
|
181
|
+
/**
|
|
182
|
+
* Resume playback paused by {@link pause}.
|
|
183
|
+
*
|
|
184
|
+
* @returns The platform's resume response.
|
|
185
|
+
* @throws {RelayError} When the resume command is rejected.
|
|
186
|
+
*/
|
|
130
187
|
async resume(): Promise<Record<string, unknown>> {
|
|
131
188
|
return this.call._execute('play.resume', { control_id: this.controlId });
|
|
132
189
|
}
|
|
133
190
|
|
|
191
|
+
/**
|
|
192
|
+
* Adjust playback volume.
|
|
193
|
+
*
|
|
194
|
+
* @param volume - Volume adjustment in dB.
|
|
195
|
+
* @returns The platform's volume response.
|
|
196
|
+
* @throws {RelayError} When the volume command is rejected.
|
|
197
|
+
*/
|
|
134
198
|
async volume(volume: number): Promise<Record<string, unknown>> {
|
|
135
199
|
return this.call._execute('play.volume', { control_id: this.controlId, volume });
|
|
136
200
|
}
|
|
@@ -138,21 +202,42 @@ export class PlayAction extends Action {
|
|
|
138
202
|
|
|
139
203
|
// ─── RecordAction ────────────────────────────────────────────────────
|
|
140
204
|
|
|
205
|
+
/** Async handle for a `calling.call.record` action — controls recording in progress. */
|
|
141
206
|
export class RecordAction extends Action {
|
|
142
207
|
constructor(call: CallLike, controlId: string) {
|
|
143
208
|
super(call, controlId, EVENT_CALL_RECORD, [RECORD_STATE_FINISHED, RECORD_STATE_NO_INPUT]);
|
|
144
209
|
}
|
|
145
210
|
|
|
211
|
+
/**
|
|
212
|
+
* Stop the recording and finalise the file.
|
|
213
|
+
*
|
|
214
|
+
* @returns The platform's stop response.
|
|
215
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
216
|
+
*/
|
|
146
217
|
async stop(): Promise<Record<string, unknown>> {
|
|
147
218
|
return this.call._execute('record.stop', { control_id: this.controlId });
|
|
148
219
|
}
|
|
149
220
|
|
|
221
|
+
/**
|
|
222
|
+
* Pause the recording (resumable with {@link resume}).
|
|
223
|
+
*
|
|
224
|
+
* @param behavior - Optional behaviour hint (e.g. `"silence"`) controlling
|
|
225
|
+
* what is recorded in place of paused audio.
|
|
226
|
+
* @returns The platform's pause response.
|
|
227
|
+
* @throws {RelayError} When the pause command is rejected.
|
|
228
|
+
*/
|
|
150
229
|
async pause(behavior?: string): Promise<Record<string, unknown>> {
|
|
151
230
|
const params: Record<string, unknown> = { control_id: this.controlId };
|
|
152
231
|
if (behavior) params.behavior = behavior;
|
|
153
232
|
return this.call._execute('record.pause', params);
|
|
154
233
|
}
|
|
155
234
|
|
|
235
|
+
/**
|
|
236
|
+
* Resume recording paused by {@link pause}.
|
|
237
|
+
*
|
|
238
|
+
* @returns The platform's resume response.
|
|
239
|
+
* @throws {RelayError} When the resume command is rejected.
|
|
240
|
+
*/
|
|
156
241
|
async resume(): Promise<Record<string, unknown>> {
|
|
157
242
|
return this.call._execute('record.resume', { control_id: this.controlId });
|
|
158
243
|
}
|
|
@@ -160,6 +245,7 @@ export class RecordAction extends Action {
|
|
|
160
245
|
|
|
161
246
|
// ─── DetectAction ────────────────────────────────────────────────────
|
|
162
247
|
|
|
248
|
+
/** Async handle for a `calling.call.detect` action (machine / fax / digit). */
|
|
163
249
|
export class DetectAction extends Action {
|
|
164
250
|
constructor(call: CallLike, controlId: string) {
|
|
165
251
|
super(call, controlId, EVENT_CALL_DETECT, ['finished', 'error']);
|
|
@@ -174,6 +260,12 @@ export class DetectAction extends Action {
|
|
|
174
260
|
}
|
|
175
261
|
}
|
|
176
262
|
|
|
263
|
+
/**
|
|
264
|
+
* Stop detection before the timeout elapses.
|
|
265
|
+
*
|
|
266
|
+
* @returns The platform's stop response.
|
|
267
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
268
|
+
*/
|
|
177
269
|
async stop(): Promise<Record<string, unknown>> {
|
|
178
270
|
return this.call._execute('detect.stop', { control_id: this.controlId });
|
|
179
271
|
}
|
|
@@ -181,6 +273,7 @@ export class DetectAction extends Action {
|
|
|
181
273
|
|
|
182
274
|
// ─── CollectAction ───────────────────────────────────────────────────
|
|
183
275
|
|
|
276
|
+
/** Async handle for a `play_and_collect` action (combined playback + input collection). */
|
|
184
277
|
export class CollectAction extends Action {
|
|
185
278
|
constructor(call: CallLike, controlId: string) {
|
|
186
279
|
super(call, controlId, EVENT_CALL_COLLECT, ['finished', 'error', 'no_input', 'no_match']);
|
|
@@ -200,14 +293,34 @@ export class CollectAction extends Action {
|
|
|
200
293
|
}
|
|
201
294
|
}
|
|
202
295
|
|
|
296
|
+
/**
|
|
297
|
+
* Stop the play_and_collect operation.
|
|
298
|
+
*
|
|
299
|
+
* @returns The platform's stop response.
|
|
300
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
301
|
+
*/
|
|
203
302
|
async stop(): Promise<Record<string, unknown>> {
|
|
204
303
|
return this.call._execute('play_and_collect.stop', { control_id: this.controlId });
|
|
205
304
|
}
|
|
206
305
|
|
|
306
|
+
/**
|
|
307
|
+
* Adjust playback volume of the prompt audio mid-collect.
|
|
308
|
+
*
|
|
309
|
+
* @param volume - Volume adjustment in dB.
|
|
310
|
+
* @returns The platform's volume response.
|
|
311
|
+
* @throws {RelayError} When the volume command is rejected.
|
|
312
|
+
*/
|
|
207
313
|
async volume(volume: number): Promise<Record<string, unknown>> {
|
|
208
314
|
return this.call._execute('play_and_collect.volume', { control_id: this.controlId, volume });
|
|
209
315
|
}
|
|
210
316
|
|
|
317
|
+
/**
|
|
318
|
+
* Start the collect input timers (useful when `initial_timeout` should be
|
|
319
|
+
* reset after an async side effect completes).
|
|
320
|
+
*
|
|
321
|
+
* @returns The platform's start_input_timers response.
|
|
322
|
+
* @throws {RelayError} When the command is rejected.
|
|
323
|
+
*/
|
|
211
324
|
async startInputTimers(): Promise<Record<string, unknown>> {
|
|
212
325
|
return this.call._execute('collect.start_input_timers', { control_id: this.controlId });
|
|
213
326
|
}
|
|
@@ -215,6 +328,7 @@ export class CollectAction extends Action {
|
|
|
215
328
|
|
|
216
329
|
// ─── StandaloneCollectAction ─────────────────────────────────────────
|
|
217
330
|
|
|
331
|
+
/** Async handle for a bare `calling.call.collect` action (no accompanying play). */
|
|
218
332
|
export class StandaloneCollectAction extends Action {
|
|
219
333
|
constructor(call: CallLike, controlId: string) {
|
|
220
334
|
super(call, controlId, EVENT_CALL_COLLECT, ['finished', 'error', 'no_input', 'no_match']);
|
|
@@ -229,10 +343,22 @@ export class StandaloneCollectAction extends Action {
|
|
|
229
343
|
}
|
|
230
344
|
}
|
|
231
345
|
|
|
346
|
+
/**
|
|
347
|
+
* Stop the collect operation before input is received.
|
|
348
|
+
*
|
|
349
|
+
* @returns The platform's stop response.
|
|
350
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
351
|
+
*/
|
|
232
352
|
async stop(): Promise<Record<string, unknown>> {
|
|
233
353
|
return this.call._execute('collect.stop', { control_id: this.controlId });
|
|
234
354
|
}
|
|
235
355
|
|
|
356
|
+
/**
|
|
357
|
+
* Start the collect input timers.
|
|
358
|
+
*
|
|
359
|
+
* @returns The platform's start_input_timers response.
|
|
360
|
+
* @throws {RelayError} When the command is rejected.
|
|
361
|
+
*/
|
|
236
362
|
async startInputTimers(): Promise<Record<string, unknown>> {
|
|
237
363
|
return this.call._execute('collect.start_input_timers', { control_id: this.controlId });
|
|
238
364
|
}
|
|
@@ -240,6 +366,7 @@ export class StandaloneCollectAction extends Action {
|
|
|
240
366
|
|
|
241
367
|
// ─── FaxAction ───────────────────────────────────────────────────────
|
|
242
368
|
|
|
369
|
+
/** Async handle for a `send_fax` or `receive_fax` action. */
|
|
243
370
|
export class FaxAction extends Action {
|
|
244
371
|
private _methodPrefix: string;
|
|
245
372
|
|
|
@@ -248,6 +375,12 @@ export class FaxAction extends Action {
|
|
|
248
375
|
this._methodPrefix = methodPrefix;
|
|
249
376
|
}
|
|
250
377
|
|
|
378
|
+
/**
|
|
379
|
+
* Stop the fax transfer mid-stream.
|
|
380
|
+
*
|
|
381
|
+
* @returns The platform's stop response.
|
|
382
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
383
|
+
*/
|
|
251
384
|
async stop(): Promise<Record<string, unknown>> {
|
|
252
385
|
return this.call._execute(`${this._methodPrefix}.stop`, { control_id: this.controlId });
|
|
253
386
|
}
|
|
@@ -255,11 +388,18 @@ export class FaxAction extends Action {
|
|
|
255
388
|
|
|
256
389
|
// ─── TapAction ───────────────────────────────────────────────────────
|
|
257
390
|
|
|
391
|
+
/** Async handle for a `calling.call.tap` action (media mirroring). */
|
|
258
392
|
export class TapAction extends Action {
|
|
259
393
|
constructor(call: CallLike, controlId: string) {
|
|
260
394
|
super(call, controlId, EVENT_CALL_TAP, ['finished']);
|
|
261
395
|
}
|
|
262
396
|
|
|
397
|
+
/**
|
|
398
|
+
* Stop the media tap.
|
|
399
|
+
*
|
|
400
|
+
* @returns The platform's stop response.
|
|
401
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
402
|
+
*/
|
|
263
403
|
async stop(): Promise<Record<string, unknown>> {
|
|
264
404
|
return this.call._execute('tap.stop', { control_id: this.controlId });
|
|
265
405
|
}
|
|
@@ -267,11 +407,18 @@ export class TapAction extends Action {
|
|
|
267
407
|
|
|
268
408
|
// ─── StreamAction ────────────────────────────────────────────────────
|
|
269
409
|
|
|
410
|
+
/** Async handle for a `calling.call.stream` action (outbound media stream). */
|
|
270
411
|
export class StreamAction extends Action {
|
|
271
412
|
constructor(call: CallLike, controlId: string) {
|
|
272
413
|
super(call, controlId, EVENT_CALL_STREAM, ['finished']);
|
|
273
414
|
}
|
|
274
415
|
|
|
416
|
+
/**
|
|
417
|
+
* Stop the outbound stream.
|
|
418
|
+
*
|
|
419
|
+
* @returns The platform's stop response.
|
|
420
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
421
|
+
*/
|
|
275
422
|
async stop(): Promise<Record<string, unknown>> {
|
|
276
423
|
return this.call._execute('stream.stop', { control_id: this.controlId });
|
|
277
424
|
}
|
|
@@ -279,11 +426,18 @@ export class StreamAction extends Action {
|
|
|
279
426
|
|
|
280
427
|
// ─── PayAction ───────────────────────────────────────────────────────
|
|
281
428
|
|
|
429
|
+
/** Async handle for a `calling.call.pay` action (PCI-compliant payment collection). */
|
|
282
430
|
export class PayAction extends Action {
|
|
283
431
|
constructor(call: CallLike, controlId: string) {
|
|
284
432
|
super(call, controlId, EVENT_CALL_PAY, ['finished', 'error']);
|
|
285
433
|
}
|
|
286
434
|
|
|
435
|
+
/**
|
|
436
|
+
* Cancel the payment collection before it completes.
|
|
437
|
+
*
|
|
438
|
+
* @returns The platform's stop response.
|
|
439
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
440
|
+
*/
|
|
287
441
|
async stop(): Promise<Record<string, unknown>> {
|
|
288
442
|
return this.call._execute('pay.stop', { control_id: this.controlId });
|
|
289
443
|
}
|
|
@@ -291,11 +445,18 @@ export class PayAction extends Action {
|
|
|
291
445
|
|
|
292
446
|
// ─── TranscribeAction ────────────────────────────────────────────────
|
|
293
447
|
|
|
448
|
+
/** Async handle for a `calling.call.transcribe` action (real-time transcription). */
|
|
294
449
|
export class TranscribeAction extends Action {
|
|
295
450
|
constructor(call: CallLike, controlId: string) {
|
|
296
451
|
super(call, controlId, EVENT_CALL_TRANSCRIBE, ['finished']);
|
|
297
452
|
}
|
|
298
453
|
|
|
454
|
+
/**
|
|
455
|
+
* Stop the transcription.
|
|
456
|
+
*
|
|
457
|
+
* @returns The platform's stop response.
|
|
458
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
459
|
+
*/
|
|
299
460
|
async stop(): Promise<Record<string, unknown>> {
|
|
300
461
|
return this.call._execute('transcribe.stop', { control_id: this.controlId });
|
|
301
462
|
}
|
|
@@ -303,11 +464,18 @@ export class TranscribeAction extends Action {
|
|
|
303
464
|
|
|
304
465
|
// ─── AIAction ────────────────────────────────────────────────────────
|
|
305
466
|
|
|
467
|
+
/** Async handle for a `calling.call.ai` action (on-call AI agent session). */
|
|
306
468
|
export class AIAction extends Action {
|
|
307
469
|
constructor(call: CallLike, controlId: string) {
|
|
308
470
|
super(call, controlId, 'calling.call.ai', ['finished', 'error']);
|
|
309
471
|
}
|
|
310
472
|
|
|
473
|
+
/**
|
|
474
|
+
* Stop the AI agent session.
|
|
475
|
+
*
|
|
476
|
+
* @returns The platform's stop response.
|
|
477
|
+
* @throws {RelayError} When the stop command is rejected.
|
|
478
|
+
*/
|
|
311
479
|
async stop(): Promise<Record<string, unknown>> {
|
|
312
480
|
return this.call._execute('ai.stop', { control_id: this.controlId });
|
|
313
481
|
}
|