@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
package/package.json
CHANGED
package/src/AgentBase.ts
CHANGED
|
@@ -46,6 +46,63 @@ export type RoutingCallback = (
|
|
|
46
46
|
/**
|
|
47
47
|
* Core agent class that composes an HTTP server, prompt management, session handling,
|
|
48
48
|
* SWAIG tool registry, and 5-phase SWML rendering into a single deployable unit.
|
|
49
|
+
*
|
|
50
|
+
* A single `AgentBase` is one HTTP-servable voice agent:
|
|
51
|
+
*
|
|
52
|
+
* - `GET /` returns the SWML call-flow document
|
|
53
|
+
* - `POST /swaig` dispatches SWAIG function calls to registered tool handlers
|
|
54
|
+
* - `POST /post_prompt` receives the end-of-call summary and invokes {@link onSummary}
|
|
55
|
+
*
|
|
56
|
+
* Most user agents either (a) subclass `AgentBase` and override `defineTools()` / `onSummary()`
|
|
57
|
+
* or (b) use one of the {@link ./prefabs/index.js | prefab agents} (e.g. `ReceptionistAgent`).
|
|
58
|
+
*
|
|
59
|
+
* @example Subclass with a custom tool
|
|
60
|
+
* ```ts
|
|
61
|
+
* import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
62
|
+
*
|
|
63
|
+
* class WeatherAgent extends AgentBase {
|
|
64
|
+
* static override PROMPT_SECTIONS = [
|
|
65
|
+
* { title: 'Role', body: 'You are a weather assistant.' },
|
|
66
|
+
* ];
|
|
67
|
+
*
|
|
68
|
+
* protected override defineTools(): void {
|
|
69
|
+
* this.defineTool({
|
|
70
|
+
* name: 'get_forecast',
|
|
71
|
+
* description: 'Return the forecast for a city.',
|
|
72
|
+
* parameters: {
|
|
73
|
+
* type: 'object',
|
|
74
|
+
* properties: { city: { type: 'string' } },
|
|
75
|
+
* required: ['city'],
|
|
76
|
+
* },
|
|
77
|
+
* handler: async ({ city }) => {
|
|
78
|
+
* const forecast = await fetchForecast(city as string);
|
|
79
|
+
* return new FunctionResult(forecast);
|
|
80
|
+
* },
|
|
81
|
+
* });
|
|
82
|
+
* }
|
|
83
|
+
* }
|
|
84
|
+
*
|
|
85
|
+
* const agent = new WeatherAgent({ name: 'weather', route: '/' });
|
|
86
|
+
* await agent.serve({ port: 3000 });
|
|
87
|
+
* ```
|
|
88
|
+
*
|
|
89
|
+
* @example Imperative usage (no subclass)
|
|
90
|
+
* ```ts
|
|
91
|
+
* const agent = new AgentBase({ name: 'hello', route: '/' });
|
|
92
|
+
* agent.setPromptText('You are a friendly greeter.');
|
|
93
|
+
* agent.defineTool({
|
|
94
|
+
* name: 'say_hi',
|
|
95
|
+
* description: 'Respond with a greeting.',
|
|
96
|
+
* parameters: { type: 'object', properties: {} },
|
|
97
|
+
* handler: () => new FunctionResult('Hello from SignalWire!'),
|
|
98
|
+
* });
|
|
99
|
+
* await agent.serve();
|
|
100
|
+
* ```
|
|
101
|
+
*
|
|
102
|
+
* @see {@link FunctionResult} — builder for tool handler responses
|
|
103
|
+
* @see {@link ContextBuilder} — multi-step conversation state machines
|
|
104
|
+
* @see {@link DataMap} — server-side tools without webhooks
|
|
105
|
+
* @see {@link AgentServer} — host multiple agents on one HTTP server
|
|
49
106
|
*/
|
|
50
107
|
export class AgentBase {
|
|
51
108
|
/** Display name of this agent. */
|
|
@@ -1495,8 +1552,24 @@ export class AgentBase {
|
|
|
1495
1552
|
|
|
1496
1553
|
/**
|
|
1497
1554
|
* Set a callback invoked on each SWML request to dynamically modify an ephemeral agent copy.
|
|
1498
|
-
*
|
|
1555
|
+
*
|
|
1556
|
+
* The callback receives a clone of this agent — mutations apply only to the current
|
|
1557
|
+
* request, so you can vary prompt, tools, languages, params, or global data per call
|
|
1558
|
+
* without affecting the long-lived agent instance.
|
|
1559
|
+
*
|
|
1560
|
+
* @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)` where
|
|
1561
|
+
* `agent` is the ephemeral `AgentBase` copy to mutate. May be async.
|
|
1499
1562
|
* @returns This agent instance for chaining.
|
|
1563
|
+
*
|
|
1564
|
+
* @example
|
|
1565
|
+
* ```ts
|
|
1566
|
+
* agent.setDynamicConfigCallback((query, body, headers, agent) => {
|
|
1567
|
+
* const lang = query.lang ?? 'en';
|
|
1568
|
+
* if (lang === 'es') {
|
|
1569
|
+
* (agent as AgentBase).setPromptText('Eres un asistente útil.');
|
|
1570
|
+
* }
|
|
1571
|
+
* });
|
|
1572
|
+
* ```
|
|
1500
1573
|
*/
|
|
1501
1574
|
setDynamicConfigCallback(cb: DynamicConfigCallback): this {
|
|
1502
1575
|
this.dynamicConfigCallback = cb;
|
|
@@ -1667,8 +1740,29 @@ export class AgentBase {
|
|
|
1667
1740
|
|
|
1668
1741
|
/**
|
|
1669
1742
|
* Lifecycle hook called when a post-prompt summary is received. Override in subclasses.
|
|
1670
|
-
*
|
|
1671
|
-
*
|
|
1743
|
+
*
|
|
1744
|
+
* Invoked once at the end of a call when the AI has produced a structured summary
|
|
1745
|
+
* (configured via `setPostPrompt()` / `setPostPromptJson()`). Use this hook to persist
|
|
1746
|
+
* call data, notify other systems, or trigger follow-up workflows.
|
|
1747
|
+
*
|
|
1748
|
+
* @param _summary - Parsed summary object (JSON when the post-prompt requests
|
|
1749
|
+
* structured output), or `null` if extraction/parsing failed.
|
|
1750
|
+
* @param _rawData - Full raw post-prompt payload received from the platform,
|
|
1751
|
+
* including call metadata, conversation history, and the summary text.
|
|
1752
|
+
*
|
|
1753
|
+
* @example
|
|
1754
|
+
* ```ts
|
|
1755
|
+
* class MyAgent extends AgentBase {
|
|
1756
|
+
* async onSummary(summary, rawData) {
|
|
1757
|
+
* if (!summary) return;
|
|
1758
|
+
* await db.calls.insert({
|
|
1759
|
+
* callSid: rawData.call_id,
|
|
1760
|
+
* summary,
|
|
1761
|
+
* endedAt: new Date(),
|
|
1762
|
+
* });
|
|
1763
|
+
* }
|
|
1764
|
+
* }
|
|
1765
|
+
* ```
|
|
1672
1766
|
*/
|
|
1673
1767
|
onSummary(_summary: Record<string, unknown> | null, _rawData: Record<string, unknown>): void | Promise<void> {
|
|
1674
1768
|
// Default no-op
|
|
@@ -2363,7 +2457,22 @@ export class AgentBase {
|
|
|
2363
2457
|
|
|
2364
2458
|
/**
|
|
2365
2459
|
* Start the HTTP server and begin listening for requests.
|
|
2366
|
-
*
|
|
2460
|
+
*
|
|
2461
|
+
* Uses `@hono/node-server` under the hood. When run in CLI mode
|
|
2462
|
+
* (`SWAIG_CLI_MODE=true`, set automatically by `npx swaig-test`), this is a
|
|
2463
|
+
* no-op so agent config can be inspected without starting a server.
|
|
2464
|
+
*
|
|
2465
|
+
* @param opts - Optional host/port overrides. Defaults to the values provided
|
|
2466
|
+
* in the constructor options or the `PORT` environment variable.
|
|
2467
|
+
* @returns A promise that resolves once the server has begun listening.
|
|
2468
|
+
*
|
|
2469
|
+
* @example
|
|
2470
|
+
* ```ts
|
|
2471
|
+
* const agent = new AgentBase({ name: 'demo', port: 3000 });
|
|
2472
|
+
* await agent.serve();
|
|
2473
|
+
* // Or override at runtime:
|
|
2474
|
+
* await agent.serve({ port: 8080, host: '127.0.0.1' });
|
|
2475
|
+
* ```
|
|
2367
2476
|
*/
|
|
2368
2477
|
async serve(opts?: { host?: string; port?: number }): Promise<void> {
|
|
2369
2478
|
// When loaded by the CLI tool, skip server startup — only the agent config is needed.
|
package/src/AgentServer.ts
CHANGED
|
@@ -44,7 +44,29 @@ const MIME_TYPES: Record<string, string> = {
|
|
|
44
44
|
'.gz': 'application/gzip',
|
|
45
45
|
};
|
|
46
46
|
|
|
47
|
-
/**
|
|
47
|
+
/**
|
|
48
|
+
* Multi-agent HTTP server that hosts multiple AgentBase instances on distinct route prefixes.
|
|
49
|
+
*
|
|
50
|
+
* Use `AgentServer` when one process should serve more than one agent — each with its own
|
|
51
|
+
* prompt, tools, and route. Internally, each agent's Hono router is mounted under its own
|
|
52
|
+
* path. Static assets can also be served from a configured directory.
|
|
53
|
+
*
|
|
54
|
+
* @example Host two agents on one port
|
|
55
|
+
* ```ts
|
|
56
|
+
* import { AgentServer, AgentBase } from '@signalwire/sdk';
|
|
57
|
+
*
|
|
58
|
+
* const salesAgent = new AgentBase({ name: 'sales', route: '/sales' });
|
|
59
|
+
* const supportAgent = new AgentBase({ name: 'support', route: '/support' });
|
|
60
|
+
*
|
|
61
|
+
* const server = new AgentServer({ host: '0.0.0.0', port: 3000 });
|
|
62
|
+
* server.register(salesAgent);
|
|
63
|
+
* server.register(supportAgent);
|
|
64
|
+
*
|
|
65
|
+
* await server.run();
|
|
66
|
+
* ```
|
|
67
|
+
*
|
|
68
|
+
* @see {@link AgentBase}
|
|
69
|
+
*/
|
|
48
70
|
export class AgentServer {
|
|
49
71
|
/** Hostname the server binds to. */
|
|
50
72
|
host: string;
|
|
@@ -385,10 +407,15 @@ export class AgentServer {
|
|
|
385
407
|
*
|
|
386
408
|
* This method handles server mode only. For serverless deployments
|
|
387
409
|
* (AWS Lambda, Google Cloud Functions, Azure Functions), use
|
|
388
|
-
* {@link ServerlessAdapter} instead.
|
|
410
|
+
* {@link ServerlessAdapter} instead. When `SWAIG_CLI_MODE=true` is set in
|
|
411
|
+
* the environment, the call is a no-op so agent config can be inspected
|
|
412
|
+
* without starting a server.
|
|
389
413
|
*
|
|
390
|
-
* @param host - Override the configured hostname.
|
|
391
|
-
*
|
|
414
|
+
* @param host - Override the configured hostname. Defaults to the
|
|
415
|
+
* constructor value.
|
|
416
|
+
* @param port - Override the configured port. Defaults to the constructor
|
|
417
|
+
* value.
|
|
418
|
+
* @returns Resolves once the underlying Hono server has begun listening.
|
|
392
419
|
*/
|
|
393
420
|
async run(host?: string, port?: number): Promise<void> {
|
|
394
421
|
// When loaded by the CLI tool, skip server startup — only the agent config is needed.
|
package/src/ContextBuilder.ts
CHANGED
|
@@ -926,6 +926,33 @@ export class Context {
|
|
|
926
926
|
* - gather_info questions are non-empty and have unique keys
|
|
927
927
|
* - gather_info completion_action targets a reachable step
|
|
928
928
|
* - No user-defined SWAIG tool collides with a reserved native name
|
|
929
|
+
*
|
|
930
|
+
* @example Two-step support bot
|
|
931
|
+
* ```ts
|
|
932
|
+
* import { AgentBase, ContextBuilder } from '@signalwire/sdk';
|
|
933
|
+
*
|
|
934
|
+
* const agent = new AgentBase({ name: 'support', route: '/' });
|
|
935
|
+
*
|
|
936
|
+
* const contexts = new ContextBuilder();
|
|
937
|
+
* const flow = contexts.addContext('default');
|
|
938
|
+
*
|
|
939
|
+
* flow.addStep('greeting')
|
|
940
|
+
* .setText("Greet the caller and ask if they're an existing customer.")
|
|
941
|
+
* .setValidSteps(['existing', 'new']);
|
|
942
|
+
*
|
|
943
|
+
* flow.addStep('existing')
|
|
944
|
+
* .setText('Ask for the account number and read it back to confirm.');
|
|
945
|
+
*
|
|
946
|
+
* flow.addStep('new')
|
|
947
|
+
* .setText('Collect name, email, and reason for calling.');
|
|
948
|
+
*
|
|
949
|
+
* agent.defineContexts(contexts);
|
|
950
|
+
* ```
|
|
951
|
+
*
|
|
952
|
+
* @see {@link Context}
|
|
953
|
+
* @see {@link Step}
|
|
954
|
+
* @see {@link GatherInfo}
|
|
955
|
+
* @see {@link AgentBase.defineContexts}
|
|
929
956
|
*/
|
|
930
957
|
export class ContextBuilder {
|
|
931
958
|
private contexts: Map<string, Context> = new Map();
|
|
@@ -957,8 +984,12 @@ export class ContextBuilder {
|
|
|
957
984
|
|
|
958
985
|
/**
|
|
959
986
|
* Adds a new named context to the builder.
|
|
960
|
-
*
|
|
961
|
-
* @
|
|
987
|
+
*
|
|
988
|
+
* @param name - The unique context name. A single-context flow must name
|
|
989
|
+
* its only context `"default"`.
|
|
990
|
+
* @returns The newly created {@link Context} for further configuration.
|
|
991
|
+
* @throws {Error} When the max-context limit is exceeded or a context with
|
|
992
|
+
* the same name already exists.
|
|
962
993
|
*/
|
|
963
994
|
addContext(name: string): Context {
|
|
964
995
|
if (this.contexts.size >= MAX_CONTEXTS) {
|
package/src/DataMap.ts
CHANGED
|
@@ -60,8 +60,36 @@ function expandEnvInObject(obj: unknown, allowedPrefixes: string[]): unknown {
|
|
|
60
60
|
/**
|
|
61
61
|
* Fluent builder for SWAIG data_map configurations.
|
|
62
62
|
*
|
|
63
|
-
* Creates server-side tool definitions that execute on SignalWire
|
|
64
|
-
* without requiring webhook
|
|
63
|
+
* Creates server-side tool definitions that execute on SignalWire's infrastructure
|
|
64
|
+
* **without** requiring a webhook endpoint in your application. Ideal for simple
|
|
65
|
+
* third-party API integrations (REST calls + pattern-matched response shaping).
|
|
66
|
+
*
|
|
67
|
+
* @example Simple webhook-driven tool (no handler needed)
|
|
68
|
+
* ```ts
|
|
69
|
+
* import { DataMap, FunctionResult } from '@signalwire/sdk';
|
|
70
|
+
*
|
|
71
|
+
* const weather = new DataMap('get_weather')
|
|
72
|
+
* .purpose('Look up the current weather for a city')
|
|
73
|
+
* .parameter('city', 'string', 'The city name', true)
|
|
74
|
+
* .webhook('GET', 'https://api.example.com/weather?city=${args.city}')
|
|
75
|
+
* .output(new FunctionResult('In ${city} it is ${response.temp}°F and ${response.condition}.'));
|
|
76
|
+
*
|
|
77
|
+
* // Register onto an agent:
|
|
78
|
+
* agent.registerSwaigFunction(weather.toSwaigFunction());
|
|
79
|
+
* ```
|
|
80
|
+
*
|
|
81
|
+
* @example Expression-based tool (no webhook, pattern matching only)
|
|
82
|
+
* ```ts
|
|
83
|
+
* new DataMap('classify_intent')
|
|
84
|
+
* .purpose('Route callers to the right department.')
|
|
85
|
+
* .parameter('utterance', 'string', 'What the caller said', true)
|
|
86
|
+
* .expression('${args.utterance}', /billing|invoice|charge/i, new FunctionResult('billing'))
|
|
87
|
+
* .expression('${args.utterance}', /tech|broken|error/i, new FunctionResult('support'));
|
|
88
|
+
* ```
|
|
89
|
+
*
|
|
90
|
+
* @see {@link FunctionResult} — response shape used in `.output()` / `.expression()`
|
|
91
|
+
* @see {@link createSimpleApiTool} — one-liner helper for REST API tools
|
|
92
|
+
* @see {@link AgentBase.defineTool} — alternative for tools that run in your process
|
|
65
93
|
*/
|
|
66
94
|
export class DataMap {
|
|
67
95
|
/** The name of the SWAIG function this data map defines. */
|
package/src/FunctionResult.ts
CHANGED
|
@@ -36,8 +36,42 @@ export interface PaymentParameter {
|
|
|
36
36
|
/**
|
|
37
37
|
* Builder for SWAIG function responses.
|
|
38
38
|
*
|
|
39
|
-
* Carries response text and a list of structured
|
|
40
|
-
*
|
|
39
|
+
* Carries response text (what the AI says to the caller) and a list of structured
|
|
40
|
+
* actions (connect, hangup, SMS, record, transfer, etc.) that the SignalWire platform
|
|
41
|
+
* executes after the AI speaks. Every mutating method returns `this` for fluent chaining.
|
|
42
|
+
*
|
|
43
|
+
* Return an instance (or a promise that resolves to one) from any SWAIG tool handler.
|
|
44
|
+
*
|
|
45
|
+
* @example Simple text response
|
|
46
|
+
* ```ts
|
|
47
|
+
* agent.defineTool({
|
|
48
|
+
* name: 'say_hi',
|
|
49
|
+
* description: 'Say hello.',
|
|
50
|
+
* parameters: { type: 'object', properties: {} },
|
|
51
|
+
* handler: () => new FunctionResult('Hello there!'),
|
|
52
|
+
* });
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* @example Response plus a call-control action
|
|
56
|
+
* ```ts
|
|
57
|
+
* agent.defineTool({
|
|
58
|
+
* name: 'transfer_to_sales',
|
|
59
|
+
* description: 'Forward the caller to sales.',
|
|
60
|
+
* parameters: { type: 'object', properties: {} },
|
|
61
|
+
* handler: () =>
|
|
62
|
+
* new FunctionResult('Connecting you to sales now.').connect('+15551112222'),
|
|
63
|
+
* });
|
|
64
|
+
* ```
|
|
65
|
+
*
|
|
66
|
+
* @example Chained actions
|
|
67
|
+
* ```ts
|
|
68
|
+
* new FunctionResult("Thanks, you're all set.")
|
|
69
|
+
* .sendSms({ toNumber: '+15551234567', fromNumber: '+15559998888', body: 'Confirmation!' })
|
|
70
|
+
* .hangup();
|
|
71
|
+
* ```
|
|
72
|
+
*
|
|
73
|
+
* @see {@link AgentBase.defineTool} — where handlers return a `FunctionResult`
|
|
74
|
+
* @see {@link DataMap} — alternative for purely data-driven (no handler) tools
|
|
41
75
|
*/
|
|
42
76
|
export class FunctionResult {
|
|
43
77
|
/** The text response returned to the AI agent. */
|
|
@@ -443,8 +477,11 @@ export class FunctionResult {
|
|
|
443
477
|
|
|
444
478
|
/**
|
|
445
479
|
* Send an SMS or MMS message from within the call flow.
|
|
446
|
-
*
|
|
480
|
+
*
|
|
481
|
+
* @param opts - SMS parameters. Must include either `body` (text SMS) or
|
|
482
|
+
* `media` (MMS) — supplying neither throws.
|
|
447
483
|
* @returns This instance for chaining.
|
|
484
|
+
* @throws {Error} When neither `body` nor `media` is provided.
|
|
448
485
|
*/
|
|
449
486
|
sendSms(opts: {
|
|
450
487
|
toNumber: string;
|
package/src/PomBuilder.ts
CHANGED
|
@@ -201,7 +201,35 @@ export class PomSection {
|
|
|
201
201
|
}
|
|
202
202
|
}
|
|
203
203
|
|
|
204
|
-
/**
|
|
204
|
+
/**
|
|
205
|
+
* Builds a structured prompt by composing named POM sections, with Markdown and dict export.
|
|
206
|
+
*
|
|
207
|
+
* The Prompt Object Model lets you assemble a large system prompt from reusable,
|
|
208
|
+
* named sections (Role, Objective, Constraints, etc.) instead of a single string.
|
|
209
|
+
* This plays well with {@link AgentBase} methods like `promptAddSection()` and
|
|
210
|
+
* `promptAddToSection()` that let user code and skills add prompt content
|
|
211
|
+
* incrementally.
|
|
212
|
+
*
|
|
213
|
+
* @example Build a structured prompt
|
|
214
|
+
* ```ts
|
|
215
|
+
* import { PomBuilder } from '@signalwire/sdk';
|
|
216
|
+
*
|
|
217
|
+
* const pom = new PomBuilder()
|
|
218
|
+
* .addSection('Role', { body: 'You are a friendly customer service agent.' })
|
|
219
|
+
* .addSection('Objectives', { bullets: [
|
|
220
|
+
* 'Identify the customer politely',
|
|
221
|
+
* 'Resolve their issue in under 3 turns if possible',
|
|
222
|
+
* ]})
|
|
223
|
+
* .addSection('Constraints', { bullets: [
|
|
224
|
+
* 'Never reveal internal tool names',
|
|
225
|
+
* ]});
|
|
226
|
+
*
|
|
227
|
+
* const systemPrompt = pom.renderMarkdown();
|
|
228
|
+
* ```
|
|
229
|
+
*
|
|
230
|
+
* @see {@link PomSection}
|
|
231
|
+
* @see {@link AgentBase.promptAddSection}
|
|
232
|
+
*/
|
|
205
233
|
export class PomBuilder {
|
|
206
234
|
private sections: PomSection[] = [];
|
|
207
235
|
private sectionMap: Map<string, PomSection> = new Map();
|
package/src/SWMLService.ts
CHANGED
|
@@ -174,7 +174,29 @@ export interface SWMLServiceOptions {
|
|
|
174
174
|
|
|
175
175
|
// ── SWMLService class ──────────────────────────────────────────────────
|
|
176
176
|
|
|
177
|
-
/**
|
|
177
|
+
/**
|
|
178
|
+
* HTTP service that serves non-AI SWML documents built from verb methods.
|
|
179
|
+
*
|
|
180
|
+
* Use `SWMLService` when you need a SignalWire call flow but don't need AI —
|
|
181
|
+
* plain call routing, IVR-style trees, recording workflows, static playback, etc.
|
|
182
|
+
* For AI-powered voice agents, use {@link AgentBase} instead.
|
|
183
|
+
*
|
|
184
|
+
* @example Static greeting that plays a file and hangs up
|
|
185
|
+
* ```ts
|
|
186
|
+
* import { SWMLService } from '@signalwire/sdk';
|
|
187
|
+
*
|
|
188
|
+
* const service = new SWMLService({ name: 'greeter', route: '/', port: 3000 });
|
|
189
|
+
* service.builder
|
|
190
|
+
* .answer()
|
|
191
|
+
* .play({ url: 'https://cdn.example.com/welcome.mp3' })
|
|
192
|
+
* .hangup();
|
|
193
|
+
*
|
|
194
|
+
* await service.serve();
|
|
195
|
+
* ```
|
|
196
|
+
*
|
|
197
|
+
* @see {@link SwmlBuilder} — the underlying SWML document builder
|
|
198
|
+
* @see {@link AgentBase} — AI-powered alternative
|
|
199
|
+
*/
|
|
178
200
|
export class SWMLService {
|
|
179
201
|
/** Service display name. */
|
|
180
202
|
readonly name: string;
|
|
@@ -644,11 +666,20 @@ export class SWMLService {
|
|
|
644
666
|
|
|
645
667
|
/**
|
|
646
668
|
* Start the HTTP server.
|
|
647
|
-
* Matches Python's `serve()` parameters including SSL options.
|
|
648
669
|
*
|
|
649
|
-
*
|
|
650
|
-
*
|
|
670
|
+
* Matches Python's `serve()` parameters including SSL options. When
|
|
671
|
+
* `SWAIG_CLI_MODE=true` is set in the environment (e.g. while running the
|
|
672
|
+
* `swaig-test` CLI) the call is a no-op.
|
|
673
|
+
*
|
|
674
|
+
* @param host - Hostname. Defaults to `this.host` (constructor value) or
|
|
675
|
+
* `'0.0.0.0'`.
|
|
676
|
+
* @param port - Port. Defaults to `this.port` (constructor value) or `3000`.
|
|
651
677
|
* @param opts - Optional SSL/TLS configuration overrides.
|
|
678
|
+
* @param opts.sslCert - Path to the PEM certificate file.
|
|
679
|
+
* @param opts.sslKey - Path to the PEM private key file.
|
|
680
|
+
* @param opts.sslEnabled - When `true`, serve over HTTPS.
|
|
681
|
+
* @param opts.domain - Domain used for HSTS header configuration.
|
|
682
|
+
* @returns Resolves once the server has begun listening.
|
|
652
683
|
*/
|
|
653
684
|
async run(
|
|
654
685
|
host?: string,
|
|
@@ -694,11 +725,12 @@ export class SWMLService {
|
|
|
694
725
|
}
|
|
695
726
|
|
|
696
727
|
/**
|
|
697
|
-
* Start the HTTP server. Alias for
|
|
728
|
+
* Start the HTTP server. Alias for {@link run} provided for cross-SDK
|
|
698
729
|
* consistency with Python's `serve()` method — callers porting from
|
|
699
730
|
* Python can use this name without changes.
|
|
700
731
|
*
|
|
701
|
-
*
|
|
732
|
+
* @param args - Forwarded unchanged to {@link run}.
|
|
733
|
+
* @returns Resolves once the server has begun listening.
|
|
702
734
|
*/
|
|
703
735
|
async serve(...args: Parameters<SWMLService['run']>): Promise<void> {
|
|
704
736
|
return this.run(...args);
|
package/src/ServerlessAdapter.ts
CHANGED
|
@@ -42,7 +42,26 @@ export interface ServerlessResponse {
|
|
|
42
42
|
body: string;
|
|
43
43
|
}
|
|
44
44
|
|
|
45
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI.
|
|
47
|
+
*
|
|
48
|
+
* Accepts the provider's native event shape (`APIGatewayProxyEvent`, Google Functions `Request`,
|
|
49
|
+
* Azure function arguments, CGI env + stdin) and returns a provider-native response.
|
|
50
|
+
*
|
|
51
|
+
* @example AWS Lambda handler
|
|
52
|
+
* ```ts
|
|
53
|
+
* import { AgentBase, ServerlessAdapter } from '@signalwire/sdk';
|
|
54
|
+
*
|
|
55
|
+
* const agent = new AgentBase({ name: 'lambda', route: '/' });
|
|
56
|
+
* agent.setPromptText('You are a helpful assistant.');
|
|
57
|
+
*
|
|
58
|
+
* const adapter = new ServerlessAdapter('aws');
|
|
59
|
+
*
|
|
60
|
+
* export const handler = async (event: any) => {
|
|
61
|
+
* return adapter.handleRequest(agent.asRouter(), event);
|
|
62
|
+
* };
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
46
65
|
export class ServerlessAdapter {
|
|
47
66
|
private platform: ServerlessPlatform;
|
|
48
67
|
|
package/src/SwmlBuilder.ts
CHANGED
|
@@ -29,7 +29,32 @@ export interface SwmlBuilderOptions {
|
|
|
29
29
|
schemaPath?: string;
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
-
/**
|
|
32
|
+
/**
|
|
33
|
+
* Builds SWML documents composed of verb instructions organized into named sections.
|
|
34
|
+
*
|
|
35
|
+
* Verb methods (`.answer()`, `.play()`, `.hangup()`, `.transfer()`, etc.) are
|
|
36
|
+
* auto-installed from the bundled SWML schema and all return `this` for fluent chaining.
|
|
37
|
+
*
|
|
38
|
+
* Most users don't instantiate `SwmlBuilder` directly — `AgentBase` uses it internally
|
|
39
|
+
* and exposes higher-level helpers. Use this class directly for `SWMLService` (non-AI
|
|
40
|
+
* call flows) or to hand-craft SWML returned from a route handler.
|
|
41
|
+
*
|
|
42
|
+
* @example Simple SWML document
|
|
43
|
+
* ```ts
|
|
44
|
+
* import { SwmlBuilder } from '@signalwire/sdk';
|
|
45
|
+
*
|
|
46
|
+
* const swml = new SwmlBuilder()
|
|
47
|
+
* .answer()
|
|
48
|
+
* .play({ url: 'https://cdn.example.com/greeting.mp3' })
|
|
49
|
+
* .hangup()
|
|
50
|
+
* .build();
|
|
51
|
+
*
|
|
52
|
+
* // swml is JSON ready to return from a SignalWire webhook.
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* @see {@link SWMLService} — HTTP service that serves a built SWML document
|
|
56
|
+
* @see {@link AgentBase} — for AI-driven call flows
|
|
57
|
+
*/
|
|
33
58
|
export class SwmlBuilder {
|
|
34
59
|
private _document: { version: string; sections: Record<string, unknown[]> };
|
|
35
60
|
private static _schemaUtils: SchemaUtils | null = null;
|
package/src/TypeInference.ts
CHANGED
|
@@ -30,7 +30,10 @@ export interface InferredSchema {
|
|
|
30
30
|
* Parse function parameter names and default values from source code.
|
|
31
31
|
*
|
|
32
32
|
* Handles arrow functions, regular functions, and method shorthand.
|
|
33
|
-
*
|
|
33
|
+
*
|
|
34
|
+
* @param source - The function source text, typically from `fn.toString()`.
|
|
35
|
+
* @returns An array of `{ name, defaultValue? }` records in declaration order.
|
|
36
|
+
* Returns an empty array if no parameter list is present.
|
|
34
37
|
*/
|
|
35
38
|
export function parseFunctionParams(source: string): ParsedParam[] {
|
|
36
39
|
// Extract the parameter list between the first set of parens
|
|
@@ -91,12 +94,19 @@ function extractParamName(expr: string): string {
|
|
|
91
94
|
/**
|
|
92
95
|
* Infer a JSON Schema from a function's parameters.
|
|
93
96
|
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
* -
|
|
98
|
-
* -
|
|
99
|
-
* -
|
|
97
|
+
* Extracts parameter names and infers JSON Schema types from default-value
|
|
98
|
+
* literals:
|
|
99
|
+
*
|
|
100
|
+
* - Number literals → `"integer"` (whole numbers) or `"number"` (decimals)
|
|
101
|
+
* - String literals → `"string"`
|
|
102
|
+
* - Boolean literals → `"boolean"`
|
|
103
|
+
* - No default → `"string"` (and the parameter is marked required)
|
|
104
|
+
*
|
|
105
|
+
* @param fn - The function to inspect. Arrow functions, regular functions, and
|
|
106
|
+
* method shorthand all work.
|
|
107
|
+
* @returns An {@link InferredSchema} describing the parameters, or `null` when
|
|
108
|
+
* the function looks like an old-style `(args, rawData)` SWAIG handler (in
|
|
109
|
+
* which case no inference is attempted).
|
|
100
110
|
*/
|
|
101
111
|
export function inferSchema(fn: Function): InferredSchema | null {
|
|
102
112
|
const source = fn.toString();
|
|
@@ -163,8 +173,16 @@ function inferTypeFromDefault(defaultValue?: string): string {
|
|
|
163
173
|
* Create a wrapper function that adapts a typed handler to the standard
|
|
164
174
|
* `(args, rawData) => result` SWAIG handler signature.
|
|
165
175
|
*
|
|
166
|
-
* The wrapper extracts named parameters from the args dict and passes
|
|
167
|
-
*
|
|
176
|
+
* The wrapper extracts named parameters from the args dict and passes them
|
|
177
|
+
* as positional arguments to the original function.
|
|
178
|
+
*
|
|
179
|
+
* @param fn - The typed handler whose parameters match `paramNames` in order.
|
|
180
|
+
* @param paramNames - Ordered list of parameter names extracted from `fn`,
|
|
181
|
+
* produced by {@link inferSchema}.
|
|
182
|
+
* @param hasRawData - When `true`, the raw-data record is appended as the
|
|
183
|
+
* final positional argument to mirror the old-style handler shape.
|
|
184
|
+
* @returns A {@link SwaigHandler} suitable for registration with
|
|
185
|
+
* {@link AgentBase.defineTool}.
|
|
168
186
|
*/
|
|
169
187
|
export function createTypedHandlerWrapper(
|
|
170
188
|
fn: Function,
|
package/src/WebService.ts
CHANGED
|
@@ -98,7 +98,24 @@ function formatSize(bytes: number): string {
|
|
|
98
98
|
*
|
|
99
99
|
* Provides configurable static file hosting with per-route directory mounting,
|
|
100
100
|
* extension filtering, file size limits, HTTP Basic Auth, CORS, directory
|
|
101
|
-
* browsing, and optional SSL/TLS. Mirrors the Python SDK's WebService class.
|
|
101
|
+
* browsing, and optional SSL/TLS. Mirrors the Python SDK's `WebService` class.
|
|
102
|
+
*
|
|
103
|
+
* Useful when an agent or prefab needs to serve supporting assets — prompts, audio
|
|
104
|
+
* files, images — from the same process without running a separate nginx / CDN.
|
|
105
|
+
*
|
|
106
|
+
* @example Serve a directory of audio files
|
|
107
|
+
* ```ts
|
|
108
|
+
* import { WebService } from '@signalwire/sdk';
|
|
109
|
+
*
|
|
110
|
+
* const web = new WebService({
|
|
111
|
+
* port: 8080,
|
|
112
|
+
* directories: { '/audio': './public/audio' },
|
|
113
|
+
* allowedExtensions: ['.mp3', '.wav'],
|
|
114
|
+
* });
|
|
115
|
+
*
|
|
116
|
+
* await web.serve();
|
|
117
|
+
* // GET http://host:8080/audio/greeting.mp3
|
|
118
|
+
* ```
|
|
102
119
|
*/
|
|
103
120
|
export class WebService {
|
|
104
121
|
/** Port the service binds to. */
|
|
@@ -220,10 +237,15 @@ export class WebService {
|
|
|
220
237
|
|
|
221
238
|
/**
|
|
222
239
|
* Start the HTTP(S) service.
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
240
|
+
*
|
|
241
|
+
* When `SWAIG_CLI_MODE=true` is set in the environment, the call is a
|
|
242
|
+
* no-op so config can be inspected without binding a port.
|
|
243
|
+
*
|
|
244
|
+
* @param host - Bind address. Defaults to `'0.0.0.0'`.
|
|
245
|
+
* @param port - Port override. Defaults to `this.port`.
|
|
246
|
+
* @param sslCert - Path to SSL certificate file (overrides `SslConfig`).
|
|
247
|
+
* @param sslKey - Path to SSL key file (overrides `SslConfig`).
|
|
248
|
+
* @returns Resolves once the server has begun listening.
|
|
227
249
|
*/
|
|
228
250
|
async start(
|
|
229
251
|
host?: string,
|