@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.
Files changed (75) hide show
  1. package/package.json +1 -1
  2. package/src/AgentBase.ts +113 -4
  3. package/src/AgentServer.ts +31 -4
  4. package/src/ContextBuilder.ts +33 -2
  5. package/src/DataMap.ts +30 -2
  6. package/src/FunctionResult.ts +40 -3
  7. package/src/PomBuilder.ts +29 -1
  8. package/src/SWMLService.ts +38 -6
  9. package/src/ServerlessAdapter.ts +20 -1
  10. package/src/SwmlBuilder.ts +26 -1
  11. package/src/TypeInference.ts +27 -9
  12. package/src/WebService.ts +27 -5
  13. package/src/index.ts +73 -7
  14. package/src/livewire/index.ts +343 -41
  15. package/src/prefabs/ConciergeAgent.ts +22 -0
  16. package/src/prefabs/FAQBotAgent.ts +32 -1
  17. package/src/prefabs/InfoGathererAgent.ts +41 -1
  18. package/src/prefabs/ReceptionistAgent.ts +30 -1
  19. package/src/prefabs/SurveyAgent.ts +26 -1
  20. package/src/relay/Action.ts +174 -6
  21. package/src/relay/Call.ts +459 -43
  22. package/src/relay/Deferred.ts +27 -4
  23. package/src/relay/Message.ts +54 -3
  24. package/src/relay/RelayClient.ts +167 -18
  25. package/src/relay/RelayError.ts +7 -1
  26. package/src/relay/RelayEvent.ts +52 -0
  27. package/src/rest/HttpClient.ts +61 -0
  28. package/src/rest/RestError.ts +14 -0
  29. package/src/rest/base/BaseResource.ts +16 -3
  30. package/src/rest/base/CrudResource.ts +52 -5
  31. package/src/rest/base/CrudWithAddresses.ts +12 -1
  32. package/src/rest/index.ts +30 -0
  33. package/src/rest/namespaces/addresses.ts +33 -1
  34. package/src/rest/namespaces/calling.ts +348 -1
  35. package/src/rest/namespaces/chat.ts +13 -2
  36. package/src/rest/namespaces/compat.ts +469 -9
  37. package/src/rest/namespaces/datasphere.ts +48 -5
  38. package/src/rest/namespaces/fabric.ts +197 -2
  39. package/src/rest/namespaces/imported-numbers.ts +13 -2
  40. package/src/rest/namespaces/logs.ts +68 -1
  41. package/src/rest/namespaces/lookup.ts +19 -2
  42. package/src/rest/namespaces/mfa.ts +35 -4
  43. package/src/rest/namespaces/number-groups.ts +35 -5
  44. package/src/rest/namespaces/phone-numbers.ts +35 -3
  45. package/src/rest/namespaces/project.ts +30 -1
  46. package/src/rest/namespaces/pubsub.ts +13 -2
  47. package/src/rest/namespaces/queues.ts +29 -4
  48. package/src/rest/namespaces/recordings.ts +26 -1
  49. package/src/rest/namespaces/registry.ts +100 -1
  50. package/src/rest/namespaces/short-codes.ts +27 -1
  51. package/src/rest/namespaces/sip-profile.ts +18 -3
  52. package/src/rest/namespaces/verified-callers.ts +22 -3
  53. package/src/rest/namespaces/video.ts +168 -1
  54. package/src/rest/pagination.ts +22 -8
  55. package/src/skills/SkillBase.ts +37 -2
  56. package/src/skills/SkillManager.ts +8 -4
  57. package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
  58. package/src/skills/builtin/ask_claude.ts +5 -0
  59. package/src/skills/builtin/claude_skills.ts +5 -0
  60. package/src/skills/builtin/custom_skills.ts +15 -0
  61. package/src/skills/builtin/datasphere.ts +9 -0
  62. package/src/skills/builtin/datasphere_serverless.ts +8 -0
  63. package/src/skills/builtin/datetime.ts +7 -0
  64. package/src/skills/builtin/google_maps.ts +5 -0
  65. package/src/skills/builtin/info_gatherer.ts +10 -0
  66. package/src/skills/builtin/joke.ts +5 -0
  67. package/src/skills/builtin/math.ts +7 -0
  68. package/src/skills/builtin/mcp_gateway.ts +8 -0
  69. package/src/skills/builtin/native_vector_search.ts +9 -0
  70. package/src/skills/builtin/play_background_file.ts +9 -0
  71. package/src/skills/builtin/spider.ts +5 -0
  72. package/src/skills/builtin/swml_transfer.ts +10 -0
  73. package/src/skills/builtin/weather_api.ts +7 -0
  74. package/src/skills/builtin/web_search.ts +9 -0
  75. package/src/skills/builtin/wikipedia_search.ts +5 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalwire/sdk",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
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
- * @param cb - The dynamic configuration callback.
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
- * @param _summary - Parsed summary object, or null if extraction failed.
1671
- * @param _rawData - The full raw post-prompt payload.
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
- * @returns A promise that resolves once the server is running.
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.
@@ -44,7 +44,29 @@ const MIME_TYPES: Record<string, string> = {
44
44
  '.gz': 'application/gzip',
45
45
  };
46
46
 
47
- /** Multi-agent HTTP server that hosts multiple AgentBase instances on distinct route prefixes. */
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
- * @param port - Override the configured port.
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.
@@ -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
- * @param name - The unique context name.
961
- * @returns The newly created Context for further configuration.
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 endpoints.
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. */
@@ -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 actions (connect, hangup, SMS, etc.).
40
- * Every mutating method returns `this` for fluent chaining.
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
- * @param opts - SMS parameters including to/from numbers and body or media.
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
- /** Builds a structured prompt by composing named POM sections, with Markdown and dict export. */
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();
@@ -174,7 +174,29 @@ export interface SWMLServiceOptions {
174
174
 
175
175
  // ── SWMLService class ──────────────────────────────────────────────────
176
176
 
177
- /** HTTP service that serves non-AI SWML documents built from verb methods. */
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
- * @param host - Hostname (default: this.host or '0.0.0.0').
650
- * @param port - Port (default: this.port or 3000).
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 `run()` provided for cross-SDK
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
- * All parameters are forwarded unchanged to `run()`.
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);
@@ -42,7 +42,26 @@ export interface ServerlessResponse {
42
42
  body: string;
43
43
  }
44
44
 
45
- /** Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI. */
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
 
@@ -29,7 +29,32 @@ export interface SwmlBuilderOptions {
29
29
  schemaPath?: string;
30
30
  }
31
31
 
32
- /** Builds SWML documents composed of verb instructions organized into named sections. */
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;
@@ -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
- * Returns an array of { name, defaultValue? } objects.
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
- * Returns null if the function appears to be an old-style `(args, rawData)` handler.
95
- * Otherwise, extracts parameter names and infers types from default values:
96
- * - Number literals → "integer" (for integers) or "number" (for floats)
97
- * - String literals → "string"
98
- * - Boolean literals → "boolean"
99
- * - No default → "string" (and marked required)
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
- * them as positional arguments to the original function.
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
- * @param host - Bind address. Default: '0.0.0.0'.
224
- * @param port - Port override. Default: this.port.
225
- * @param sslCert - Path to SSL certificate file (overrides SslConfig).
226
- * @param sslKey - Path to SSL key file (overrides SslConfig).
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,