@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/src/index.ts CHANGED
@@ -1,8 +1,60 @@
1
1
  /**
2
- * SignalWire AI Agents SDK for TypeScript
2
+ * SignalWire AI Agents SDK for TypeScript / Node.js.
3
3
  *
4
- * Build AI voice agents as HTTP microservices that serve SWML documents
5
- * and handle SWAIG function callbacks.
4
+ * Build AI voice agents as HTTP microservices that serve
5
+ * [SWML](https://developer.signalwire.com/sdks/reference/swml/) documents
6
+ * and handle SWAIG function callbacks from the SignalWire platform.
7
+ *
8
+ * @example Minimal agent
9
+ * ```ts
10
+ * import { AgentBase, FunctionResult } from '@signalwire/sdk';
11
+ *
12
+ * const agent = new AgentBase({ name: 'simple', route: '/' });
13
+ *
14
+ * agent.setPromptText("You are a helpful assistant.");
15
+ *
16
+ * agent.defineTool({
17
+ * name: 'get_time',
18
+ * description: 'Return the current server time.',
19
+ * parameters: { type: 'object', properties: {} },
20
+ * handler: () => new FunctionResult(`Time is ${new Date().toISOString()}`),
21
+ * });
22
+ *
23
+ * await agent.serve({ port: 3000 });
24
+ * ```
25
+ *
26
+ * @example Pre-built agent (prefab)
27
+ * ```ts
28
+ * import { ReceptionistAgent } from '@signalwire/sdk';
29
+ *
30
+ * const receptionist = new ReceptionistAgent({
31
+ * name: 'front-desk',
32
+ * departments: [
33
+ * { name: 'sales', description: 'New customers', number: '+15551112222' },
34
+ * { name: 'support', description: 'Existing customers', number: '+15553334444' },
35
+ * ],
36
+ * });
37
+ *
38
+ * await receptionist.serve({ port: 3000 });
39
+ * ```
40
+ *
41
+ * @example REST API client
42
+ * ```ts
43
+ * import { RestClient } from '@signalwire/sdk';
44
+ *
45
+ * const client = new RestClient(); // reads SIGNALWIRE_* env vars
46
+ * const calls = await client.compat.calls.list();
47
+ * ```
48
+ *
49
+ * @see {@link AgentBase} — core agent class
50
+ * @see {@link FunctionResult} — fluent builder for SWAIG tool responses
51
+ * @see {@link ContextBuilder} — multi-step conversation workflows
52
+ * @see {@link DataMap} — server-side tools (no webhook infrastructure required)
53
+ * @see {@link SkillBase} — base class for writing custom skills
54
+ * @see {@link RelayClient} — real-time WebSocket call/message control
55
+ * @see {@link RestClient} — typed HTTP access to SignalWire platform APIs
56
+ *
57
+ * @packageDocumentation
6
58
  */
7
59
 
8
60
  // Core agent
@@ -140,8 +192,18 @@ import type { AgentBase as _AgentBase } from './AgentBase.js';
140
192
  *
141
193
  * Equivalent to Python's `start_agent(agent)`. Delegates to `agent.serve(options)`.
142
194
  *
143
- * @param agent The AgentBase instance to start.
144
- * @param options Optional host/port overrides.
195
+ * @param agent - The {@link AgentBase} instance to start.
196
+ * @param options - Optional host / port overrides. When omitted, values come
197
+ * from the agent's constructor options or the `PORT` environment variable.
198
+ * @returns Resolves once the HTTP server has begun listening.
199
+ *
200
+ * @example
201
+ * ```ts
202
+ * import { AgentBase, startAgent } from '@signalwire/sdk';
203
+ *
204
+ * const agent = new AgentBase({ name: 'demo' });
205
+ * await startAgent(agent, { port: 3000 });
206
+ * ```
145
207
  */
146
208
  export async function startAgent(
147
209
  agent: _AgentBase,
@@ -156,8 +218,12 @@ export async function startAgent(
156
218
  * Alias for {@link startAgent} — equivalent to Python's `run_agent(agent)`.
157
219
  * Delegates to `agent.serve(options)`.
158
220
  *
159
- * @param agent The AgentBase instance to run.
160
- * @param options Optional host/port overrides.
221
+ * @param agent - The {@link AgentBase} instance to run.
222
+ * @param options - Optional host / port overrides. When omitted, values come
223
+ * from the agent's constructor options or the `PORT` environment variable.
224
+ * @returns Resolves once the HTTP server has begun listening.
225
+ *
226
+ * @see {@link startAgent}
161
227
  */
162
228
  export async function runAgent(
163
229
  agent: _AgentBase,