@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
@@ -17,10 +17,26 @@ export class VideoRooms extends CrudResource {
17
17
  super(http, basePath);
18
18
  }
19
19
 
20
+ /**
21
+ * List outbound streams associated with a room.
22
+ *
23
+ * @param roomId - Unique identifier of the video room.
24
+ * @param params - Optional filter / pagination query parameters.
25
+ * @returns A paginated list of outbound streams.
26
+ * @throws {RestError} On any non-2xx HTTP response.
27
+ */
20
28
  async listStreams(roomId: string, params?: QueryParams): Promise<any> {
21
29
  return this._http.get(this._path(roomId, 'streams'), params);
22
30
  }
23
31
 
32
+ /**
33
+ * Start a new outbound stream from a room (e.g. RTMP to YouTube, Twitch).
34
+ *
35
+ * @param roomId - Unique identifier of the video room.
36
+ * @param body - Stream configuration (destination URL, credentials, etc.).
37
+ * @returns The newly-created stream record.
38
+ * @throws {RestError} On any non-2xx HTTP response.
39
+ */
24
40
  async createStream(roomId: string, body: any): Promise<any> {
25
41
  return this._http.post(this._path(roomId, 'streams'), body);
26
42
  }
@@ -32,6 +48,13 @@ export class VideoRoomTokens extends BaseResource {
32
48
  super(http, basePath);
33
49
  }
34
50
 
51
+ /**
52
+ * Issue a JWT token that grants a browser / mobile client access to a room.
53
+ *
54
+ * @param body - Token payload (`room_name`, `user_name`, `permissions`, etc.).
55
+ * @returns The token record, typically `{ token: "eyJ..." }`.
56
+ * @throws {RestError} On any non-2xx HTTP response.
57
+ */
35
58
  async create(body: any): Promise<any> {
36
59
  return this._http.post(this._basePath, body);
37
60
  }
@@ -43,22 +66,60 @@ export class VideoRoomSessions extends BaseResource {
43
66
  super(http, basePath);
44
67
  }
45
68
 
69
+ /**
70
+ * List past and active room sessions in the project.
71
+ *
72
+ * @param params - Optional filter / pagination query parameters.
73
+ * @returns A paginated list of room sessions.
74
+ * @throws {RestError} On any non-2xx HTTP response.
75
+ */
46
76
  async list(params?: QueryParams): Promise<any> {
47
77
  return this._http.get(this._basePath, params);
48
78
  }
49
79
 
80
+ /**
81
+ * Fetch a single room session by ID.
82
+ *
83
+ * @param sessionId - Unique identifier of the room session.
84
+ * @returns The room-session record.
85
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
86
+ */
50
87
  async get(sessionId: string): Promise<any> {
51
88
  return this._http.get(this._path(sessionId));
52
89
  }
53
90
 
91
+ /**
92
+ * List the event log for a room session.
93
+ *
94
+ * @param sessionId - Unique identifier of the room session.
95
+ * @param params - Optional filter / pagination query parameters.
96
+ * @returns A paginated list of session events.
97
+ * @throws {RestError} On any non-2xx HTTP response.
98
+ */
54
99
  async listEvents(sessionId: string, params?: QueryParams): Promise<any> {
55
100
  return this._http.get(this._path(sessionId, 'events'), params);
56
101
  }
57
102
 
103
+ /**
104
+ * List members that participated in a room session.
105
+ *
106
+ * @param sessionId - Unique identifier of the room session.
107
+ * @param params - Optional filter / pagination query parameters.
108
+ * @returns A paginated list of members (past and current).
109
+ * @throws {RestError} On any non-2xx HTTP response.
110
+ */
58
111
  async listMembers(sessionId: string, params?: QueryParams): Promise<any> {
59
112
  return this._http.get(this._path(sessionId, 'members'), params);
60
113
  }
61
114
 
115
+ /**
116
+ * List recordings captured during a room session.
117
+ *
118
+ * @param sessionId - Unique identifier of the room session.
119
+ * @param params - Optional filter / pagination query parameters.
120
+ * @returns A paginated list of session recordings.
121
+ * @throws {RestError} On any non-2xx HTTP response.
122
+ */
62
123
  async listRecordings(sessionId: string, params?: QueryParams): Promise<any> {
63
124
  return this._http.get(this._path(sessionId, 'recordings'), params);
64
125
  }
@@ -70,18 +131,47 @@ export class VideoRoomRecordings extends BaseResource {
70
131
  super(http, basePath);
71
132
  }
72
133
 
134
+ /**
135
+ * List all room recordings in the project.
136
+ *
137
+ * @param params - Optional filter / pagination query parameters.
138
+ * @returns A paginated list of recordings.
139
+ * @throws {RestError} On any non-2xx HTTP response.
140
+ */
73
141
  async list(params?: QueryParams): Promise<any> {
74
142
  return this._http.get(this._basePath, params);
75
143
  }
76
144
 
145
+ /**
146
+ * Fetch a room recording by ID.
147
+ *
148
+ * @param recordingId - Unique identifier of the recording.
149
+ * @returns The recording record.
150
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
151
+ */
77
152
  async get(recordingId: string): Promise<any> {
78
153
  return this._http.get(this._path(recordingId));
79
154
  }
80
155
 
156
+ /**
157
+ * Delete a room recording.
158
+ *
159
+ * @param recordingId - Unique identifier of the recording.
160
+ * @returns The platform's delete response.
161
+ * @throws {RestError} On any non-2xx HTTP response.
162
+ */
81
163
  async delete(recordingId: string): Promise<any> {
82
164
  return this._http.delete(this._path(recordingId));
83
165
  }
84
166
 
167
+ /**
168
+ * List event log entries for a room recording.
169
+ *
170
+ * @param recordingId - Unique identifier of the recording.
171
+ * @param params - Optional filter / pagination query parameters.
172
+ * @returns A paginated list of recording events.
173
+ * @throws {RestError} On any non-2xx HTTP response.
174
+ */
85
175
  async listEvents(recordingId: string, params?: QueryParams): Promise<any> {
86
176
  return this._http.get(this._path(recordingId, 'events'), params);
87
177
  }
@@ -95,14 +185,38 @@ export class VideoConferences extends CrudResource {
95
185
  super(http, basePath);
96
186
  }
97
187
 
188
+ /**
189
+ * List conference tokens associated with a conference.
190
+ *
191
+ * @param conferenceId - Unique identifier of the conference.
192
+ * @param params - Optional filter / pagination query parameters.
193
+ * @returns A paginated list of conference tokens.
194
+ * @throws {RestError} On any non-2xx HTTP response.
195
+ */
98
196
  async listConferenceTokens(conferenceId: string, params?: QueryParams): Promise<any> {
99
197
  return this._http.get(this._path(conferenceId, 'conference_tokens'), params);
100
198
  }
101
199
 
200
+ /**
201
+ * List outbound streams associated with a conference.
202
+ *
203
+ * @param conferenceId - Unique identifier of the conference.
204
+ * @param params - Optional filter / pagination query parameters.
205
+ * @returns A paginated list of streams.
206
+ * @throws {RestError} On any non-2xx HTTP response.
207
+ */
102
208
  async listStreams(conferenceId: string, params?: QueryParams): Promise<any> {
103
209
  return this._http.get(this._path(conferenceId, 'streams'), params);
104
210
  }
105
211
 
212
+ /**
213
+ * Start an outbound stream from a conference (e.g. RTMP to YouTube).
214
+ *
215
+ * @param conferenceId - Unique identifier of the conference.
216
+ * @param body - Stream configuration (destination URL, credentials, etc.).
217
+ * @returns The newly-created stream record.
218
+ * @throws {RestError} On any non-2xx HTTP response.
219
+ */
106
220
  async createStream(conferenceId: string, body: any): Promise<any> {
107
221
  return this._http.post(this._path(conferenceId, 'streams'), body);
108
222
  }
@@ -114,10 +228,24 @@ export class VideoConferenceTokens extends BaseResource {
114
228
  super(http, basePath);
115
229
  }
116
230
 
231
+ /**
232
+ * Fetch a conference token by ID.
233
+ *
234
+ * @param tokenId - Unique identifier of the conference token.
235
+ * @returns The conference-token record.
236
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
237
+ */
117
238
  async get(tokenId: string): Promise<any> {
118
239
  return this._http.get(this._path(tokenId));
119
240
  }
120
241
 
242
+ /**
243
+ * Reset / regenerate a conference token, invalidating the previous value.
244
+ *
245
+ * @param tokenId - Unique identifier of the conference token to reset.
246
+ * @returns The refreshed token record with a new secret.
247
+ * @throws {RestError} On any non-2xx HTTP response.
248
+ */
121
249
  async reset(tokenId: string): Promise<any> {
122
250
  return this._http.post(this._path(tokenId, 'reset'));
123
251
  }
@@ -129,27 +257,66 @@ export class VideoStreams extends BaseResource {
129
257
  super(http, basePath);
130
258
  }
131
259
 
260
+ /**
261
+ * Fetch a video stream by ID.
262
+ *
263
+ * @param streamId - Unique identifier of the stream.
264
+ * @returns The stream record.
265
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
266
+ */
132
267
  async get(streamId: string): Promise<any> {
133
268
  return this._http.get(this._path(streamId));
134
269
  }
135
270
 
271
+ /**
272
+ * Update a video stream's configuration (e.g. destination URL).
273
+ *
274
+ * @param streamId - Unique identifier of the stream.
275
+ * @param body - Full updated stream attributes (replace semantics).
276
+ * @returns The updated stream record.
277
+ * @throws {RestError} On any non-2xx HTTP response.
278
+ */
136
279
  async update(streamId: string, body: any): Promise<any> {
137
280
  return this._http.put(this._path(streamId), body);
138
281
  }
139
282
 
283
+ /**
284
+ * Stop and delete a video stream.
285
+ *
286
+ * @param streamId - Unique identifier of the stream.
287
+ * @returns The platform's delete response.
288
+ * @throws {RestError} On any non-2xx HTTP response.
289
+ */
140
290
  async delete(streamId: string): Promise<any> {
141
291
  return this._http.delete(this._path(streamId));
142
292
  }
143
293
  }
144
294
 
145
- /** Video API namespace. */
295
+ /**
296
+ * Video API namespace.
297
+ *
298
+ * Access via `client.video.*`.
299
+ *
300
+ * @example Create a room and issue a client token
301
+ * ```ts
302
+ * const room = await client.video.rooms.create({ name: 'standup' });
303
+ * const token = await client.video.roomTokens.create({ room_name: 'standup', user_name: 'Alice' });
304
+ * ```
305
+ */
146
306
  export class VideoNamespace {
307
+ /** Video room CRUD plus outbound stream management. */
147
308
  readonly rooms: VideoRooms;
309
+ /** Issue JWT tokens for browser / mobile clients to join rooms. */
148
310
  readonly roomTokens: VideoRoomTokens;
311
+ /** Past and active room session read access. */
149
312
  readonly roomSessions: VideoRoomSessions;
313
+ /** Room recording read, delete, and event-log access. */
150
314
  readonly roomRecordings: VideoRoomRecordings;
315
+ /** Video conference CRUD plus stream / token management. */
151
316
  readonly conferences: VideoConferences;
317
+ /** Individual conference token read / reset operations. */
152
318
  readonly conferenceTokens: VideoConferenceTokens;
319
+ /** Individual video stream read / update / delete operations. */
153
320
  readonly streams: VideoStreams;
154
321
 
155
322
  constructor(http: HttpClient) {
@@ -12,10 +12,17 @@ import type { QueryParams } from './types.js';
12
12
  /**
13
13
  * Async generator that yields items across paginated API responses.
14
14
  *
15
- * @param http - HttpClient instance
16
- * @param path - Initial API path
17
- * @param params - Query parameters for the first request
18
- * @param dataKey - Key containing the array of items (default: "data")
15
+ * Handles both relay REST (`links.next`) and LAML (`next_page_uri`) pagination
16
+ * styles transparently.
17
+ *
18
+ * @typeParam T - Element type yielded.
19
+ * @param http - {@link HttpClient} instance used to fetch each page.
20
+ * @param path - Initial API path (absolute URL or path relative to `http.baseUrl`).
21
+ * @param params - Query parameters applied to the first request only.
22
+ * Subsequent pages use the server-supplied next-page URL unchanged.
23
+ * @param dataKey - Key on each response containing the array of items.
24
+ * Defaults to `"data"`.
25
+ * @returns An async iterable that yields one `T` per call until exhausted.
19
26
  */
20
27
  export async function* paginate<T>(
21
28
  http: HttpClient,
@@ -65,10 +72,17 @@ export async function* paginate<T>(
65
72
  /**
66
73
  * Collect all paginated items into an array.
67
74
  *
68
- * @param http - HttpClient instance
69
- * @param path - Initial API path
70
- * @param params - Query parameters
71
- * @param dataKey - Key containing the array of items (default: "data")
75
+ * Convenience wrapper around {@link paginate} for callers who want the full
76
+ * list. Beware: loads every page into memory — for very large result sets,
77
+ * iterate via `paginate()` directly.
78
+ *
79
+ * @typeParam T - Element type collected.
80
+ * @param http - {@link HttpClient} instance used to fetch each page.
81
+ * @param path - Initial API path.
82
+ * @param params - Query parameters applied to the first request.
83
+ * @param dataKey - Key on each response containing the array of items.
84
+ * Defaults to `"data"`.
85
+ * @returns A flat array of every item across all pages.
72
86
  */
73
87
  export async function paginateAll<T>(
74
88
  http: HttpClient,
@@ -84,8 +84,43 @@ export interface ParameterSchemaEntry {
84
84
  /**
85
85
  * Abstract base class for agent skills.
86
86
  *
87
- * Skills are modular capabilities that can be added to an agent.
88
- * They define tools, prompt sections, hints, and global data.
87
+ * Skills are modular, reusable capabilities that plug into an {@link AgentBase}.
88
+ * A single skill can contribute:
89
+ *
90
+ * - **Tools** (SWAIG functions) via `getTools()` or `defineTool()`
91
+ * - **Prompt sections** via `_getPromptSections()`
92
+ * - **Speech hints** via `getHints()`
93
+ * - **Global data** seeded into each call via `getGlobalData()`
94
+ *
95
+ * Skills are added to an agent with `agent.addSkill('name', config)` and the
96
+ * {@link SkillManager} calls `setAgent()` + `setup()` in sequence before the
97
+ * agent starts serving requests.
98
+ *
99
+ * @example Custom skill
100
+ * ```ts
101
+ * import { SkillBase, FunctionResult, type SkillToolDefinition } from '@signalwire/sdk';
102
+ *
103
+ * export class GreetingSkill extends SkillBase {
104
+ * static override SKILL_NAME = 'greeting';
105
+ * static override SKILL_DESCRIPTION = 'Responds with a configurable greeting.';
106
+ *
107
+ * override getTools(): SkillToolDefinition[] {
108
+ * return [{
109
+ * name: 'say_hello',
110
+ * description: 'Say a friendly hello.',
111
+ * parameters: { type: 'object', properties: {} },
112
+ * handler: () => new FunctionResult(this.getConfig('message', 'Hi!')),
113
+ * }];
114
+ * }
115
+ * }
116
+ *
117
+ * // In your agent:
118
+ * agent.addSkill(new GreetingSkill({ message: 'Howdy!' }));
119
+ * ```
120
+ *
121
+ * @see {@link SkillManager}
122
+ * @see {@link SkillRegistry}
123
+ * @see {@link AgentBase.addSkill}
89
124
  */
90
125
  export abstract class SkillBase {
91
126
  /**
@@ -60,12 +60,16 @@ export class SkillManager {
60
60
  * Add a skill to the manager, validating env vars and calling setup().
61
61
  * Uses the skill's instance key for deduplication.
62
62
  *
63
- * Throws on duplicate (when multi-instance is disallowed), missing env vars,
64
- * or setup errors. {@link loadSkill} / {@link loadSkillByName} wrap this and
65
- * catch to return `[false, msg]`, matching Python `load_skill`'s return
66
- * contract (`skill_manager.py` lines 114-118).
63
+ * {@link loadSkill} / {@link loadSkillByName} wrap this and catch to return
64
+ * `[false, msg]`, matching Python `load_skill`'s return contract
65
+ * (`skill_manager.py` lines 114-118).
67
66
  *
68
67
  * @param skill - The skill instance to add.
68
+ * @returns Resolves once the skill is registered.
69
+ * @throws {Error} When a single-instance skill is already loaded, its
70
+ * required environment variables are missing, its parameter schema is
71
+ * empty, its required packages cannot be imported, or `setup()` returns
72
+ * `false`.
69
73
  */
70
74
  async addSkill(skill: SkillBase): Promise<void> {
71
75
  const name = skill.skillName;
@@ -50,6 +50,11 @@ const VALID_CATEGORIES = [
50
50
  *
51
51
  * Tier 2 built-in skill. Requires the `API_NINJAS_KEY` environment variable.
52
52
  * Supports optional `default_category` and `reveal_answer` config options.
53
+ *
54
+ * @example
55
+ * ```ts
56
+ * agent.addSkill('api_ninjas_trivia', { default_category: 'sciencenature' });
57
+ * ```
53
58
  */
54
59
  export class ApiNinjasTriviaSkill extends SkillBase {
55
60
  static override SKILL_NAME = 'api_ninjas_trivia';
@@ -72,6 +72,11 @@ interface AnthropicErrorResponse {
72
72
  * Tier 3 built-in skill. Requires the `ANTHROPIC_API_KEY` environment variable.
73
73
  * Supports `model` and `max_tokens` config options to control which Claude model
74
74
  * is used and the maximum response length.
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * agent.addSkill('ask_claude', { model: 'claude-sonnet-4-6', max_tokens: 512 });
79
+ * ```
75
80
  */
76
81
  export class AskClaudeSkill extends SkillBase {
77
82
  // TS-only skill (no Python equivalent).
@@ -72,6 +72,11 @@ interface ParsedSkill {
72
72
  * This skill parses Claude Code skill directories and makes them available
73
73
  * as SWAIG tools that the AI can call. Each Claude skill becomes a tool
74
74
  * that returns the skill's instructions when invoked.
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * agent.addSkill('claude_skills', { skills_dir: './claude-skills' });
79
+ * ```
75
80
  */
76
81
  export class ClaudeSkillsSkill extends SkillBase {
77
82
  // Python ground truth: skills/claude_skills/skill.py
@@ -75,6 +75,21 @@ interface CustomSkillsConfigData {
75
75
  * **Security warning:** This skill uses `new Function()` to compile user-provided
76
76
  * code at runtime. It is gated behind the `SWML_ALLOW_CUSTOM_HANDLER_CODE=true`
77
77
  * environment variable to prevent unintended code execution.
78
+ *
79
+ * @example
80
+ * ```ts
81
+ * // Requires SWML_ALLOW_CUSTOM_HANDLER_CODE=true
82
+ * agent.addSkill('custom_skills', {
83
+ * tools: [
84
+ * {
85
+ * name: 'echo',
86
+ * description: 'Echo back the caller-supplied message.',
87
+ * parameters: { type: 'object', properties: { msg: { type: 'string' } } },
88
+ * handlerBody: 'return new FunctionResult(args.msg);',
89
+ * },
90
+ * ],
91
+ * });
92
+ * ```
78
93
  */
79
94
  export class CustomSkillsSkill extends SkillBase {
80
95
  // TS-only skill (no Python equivalent).
@@ -58,6 +58,15 @@ interface DataSphereResponse {
58
58
  * `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN`, and `SIGNALWIRE_SPACE` environment
59
59
  * variables. Supports `count`, `distance`, `tags`, `language`, `pos_to_expand`,
60
60
  * `max_synonyms`, and `no_results_message` config options.
61
+ *
62
+ * @example
63
+ * ```ts
64
+ * agent.addSkill('datasphere', {
65
+ * document_id: 'doc_abc123',
66
+ * count: 3,
67
+ * tags: ['faq'],
68
+ * });
69
+ * ```
61
70
  */
62
71
  export class DataSphereSkill extends SkillBase {
63
72
  // Python ground truth: skills/datasphere/skill.py:20-27.
@@ -33,6 +33,14 @@ const DEFAULT_NO_RESULTS_MESSAGE =
33
33
  * executes directly, without a webhook endpoint. Supports `document_id`,
34
34
  * `count`, `distance`, `tags`, `language`, `pos_to_expand`, `max_synonyms`,
35
35
  * and `no_results_message` config options.
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * agent.addSkill('datasphere_serverless', {
40
+ * document_id: 'doc_abc123',
41
+ * count: 3,
42
+ * });
43
+ * ```
36
44
  */
37
45
  export class DataSphereServerlessSkill extends SkillBase {
38
46
  // Python ground truth: skills/datasphere_serverless/skill.py:20-28
@@ -18,6 +18,13 @@ import { FunctionResult } from '../../FunctionResult.js';
18
18
  *
19
19
  * Tier 1 built-in skill with no external dependencies. Supports all IANA
20
20
  * timezone identifiers via the Intl.DateTimeFormat API.
21
+ *
22
+ * Registers two SWAIG tools: `get_current_time` and `get_current_date`.
23
+ *
24
+ * @example
25
+ * ```ts
26
+ * agent.addSkill('datetime');
27
+ * ```
21
28
  */
22
29
  export class DateTimeSkill extends SkillBase {
23
30
  // Python ground truth: skills/datetime/skill.py
@@ -98,6 +98,11 @@ interface RoutesV2Response {
98
98
  *
99
99
  * Tier 3 built-in skill. Requires the `GOOGLE_MAPS_API_KEY` environment variable.
100
100
  * Supports a `default_mode` config option ("driving"|"walking"|"bicycling"|"transit").
101
+ *
102
+ * @example
103
+ * ```ts
104
+ * agent.addSkill('google_maps', { default_mode: 'driving' });
105
+ * ```
101
106
  */
102
107
  export class GoogleMapsSkill extends SkillBase {
103
108
  // Python ground truth: skills/google_maps/skill.py
@@ -46,6 +46,16 @@ interface QuestionDefinition {
46
46
  * `questions` config, the same `prefix` / `completion_message` options,
47
47
  * the same two tools (`start_questions`, `submit_answer`), and the same
48
48
  * state shape in `global_data`.
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * agent.addSkill('info_gatherer', {
53
+ * questions: [
54
+ * { key_name: 'name', question_text: 'What is your name?' },
55
+ * { key_name: 'email', question_text: 'Your email?', confirm: true },
56
+ * ],
57
+ * });
58
+ * ```
49
59
  */
50
60
  export class InfoGathererSkill extends SkillBase {
51
61
  // Python ground truth: skills/info_gatherer/skill.py:26-31
@@ -87,6 +87,11 @@ const VALID_CATEGORIES = ['general', 'programming', 'dad'];
87
87
  *
88
88
  * Tier 1 built-in skill with no external dependencies. Includes general,
89
89
  * programming, and dad joke categories.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * agent.addSkill('joke');
94
+ * ```
90
95
  */
91
96
  export class JokeSkill extends SkillBase {
92
97
  // Python ground truth: skills/joke/skill.py
@@ -64,6 +64,13 @@ function safeEvaluate(expr: string): number {
64
64
  *
65
65
  * Tier 1 built-in skill with no external dependencies. Only allows digits,
66
66
  * basic arithmetic operators, parentheses, decimal points, and spaces.
67
+ *
68
+ * Registers a single SWAIG tool: `calculate`.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * agent.addSkill('math');
73
+ * ```
67
74
  */
68
75
  export class MathSkill extends SkillBase {
69
76
  // Python ground truth: skills/math/skill.py
@@ -49,6 +49,14 @@ interface McpToolDefinition {
49
49
  * services, enumerates each service's tools, and registers them as SWAIG
50
50
  * tools prefixed with `tool_prefix` (default `mcp_`). A hidden hangup hook
51
51
  * tool cleans up MCP sessions when the call ends.
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * agent.addSkill('mcp_gateway', {
56
+ * gateway_url: 'https://mcp-gateway.example.com',
57
+ * tool_prefix: 'mcp_',
58
+ * });
59
+ * ```
52
60
  */
53
61
  export class McpGatewaySkill extends SkillBase {
54
62
  // Python ground truth: skills/mcp_gateway/skill.py:~70-76
@@ -146,6 +146,15 @@ function scoreTfIdf(
146
146
  * Document search using TF-IDF in-memory scoring or a remote search server.
147
147
  *
148
148
  * Multi-instance capable (distinguished by `tool_name` + `index_file`).
149
+ *
150
+ * @example Local JSON index
151
+ * ```ts
152
+ * agent.addSkill('native_vector_search', {
153
+ * tool_name: 'search_docs',
154
+ * index_file: './data/support-docs.json',
155
+ * count: 3,
156
+ * });
157
+ * ```
149
158
  */
150
159
  export class NativeVectorSearchSkill extends SkillBase {
151
160
  // Python ground truth: skills/native_vector_search/skill.py:~75-82
@@ -39,6 +39,15 @@ interface PreConfiguredFile {
39
39
  * values that trigger the corresponding file playback.
40
40
  * - Free-form `default_file_url` / `allowed_domains`: emits two tools,
41
41
  * `play_background` (arbitrary URL) and `stop_background`.
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * agent.addSkill('play_background_file', {
46
+ * files: [
47
+ * { key: 'hold', url: 'https://cdn.example.com/hold-music.mp3', description: 'Hold music' },
48
+ * ],
49
+ * });
50
+ * ```
42
51
  */
43
52
  export class PlayBackgroundFileSkill extends SkillBase {
44
53
  // Python ground truth: skills/play_background_file/skill.py
@@ -56,6 +56,11 @@ const STRIP_TAG_REGEXES: RegExp[] = [
56
56
  * mirrors the Python schema (delay, concurrent_requests, timeout, max_pages,
57
57
  * max_depth, extract_type, max_text_length, clean_text, selectors,
58
58
  * follow_patterns, user_agent, headers, follow_robots_txt, cache_enabled).
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * agent.addSkill('spider', { max_pages: 5, max_depth: 2 });
63
+ * ```
59
64
  */
60
65
  export class SpiderSkill extends SkillBase {
61
66
  // Python ground truth: skills/spider/skill.py:~140-145
@@ -59,6 +59,16 @@ interface TransferConfig {
59
59
  * Multi-instance capable (distinguished by `tool_name`).
60
60
  * Accepts either Python-style `transfers` config (regex → per-entry config)
61
61
  * or TypeScript-style `patterns` array of named destinations.
62
+ *
63
+ * @example
64
+ * ```ts
65
+ * agent.addSkill('swml_transfer', {
66
+ * patterns: [
67
+ * { name: 'sales', pattern: /sales|pricing|buy/i, to: '+15551112222' },
68
+ * { name: 'support', pattern: /help|support|broken/i, to: '+15553334444' },
69
+ * ],
70
+ * });
71
+ * ```
62
72
  */
63
73
  export class SwmlTransferSkill extends SkillBase {
64
74
  // Python ground truth: skills/swml_transfer/skill.py:~60-67
@@ -57,6 +57,13 @@ interface WeatherApiResponse {
57
57
  * **Unit aliases:** For migration compatibility with the Python SDK the `units`
58
58
  * config also accepts `"fahrenheit"` (normalized to `"imperial"`) and
59
59
  * `"celsius"` (normalized to `"metric"`).
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * agent.addSkill('weather_api', { units: 'imperial' });
64
+ * // or pass the key explicitly:
65
+ * agent.addSkill('weather_api', { api_key: process.env.WEATHER_API_KEY });
66
+ * ```
60
67
  */
61
68
  export class WeatherApiSkill extends SkillBase {
62
69
  // Python ground truth: skills/weather_api/skill.py
@@ -191,6 +191,15 @@ interface GoogleSearchResponse {
191
191
  * Supported config: `tool_name`, `num_results`, `no_results_message`,
192
192
  * `safe_search`, `delay`, `max_content_length`, `oversample_factor`,
193
193
  * `min_quality_score`.
194
+ *
195
+ * @example
196
+ * ```ts
197
+ * agent.addSkill('web_search', {
198
+ * api_key: process.env.GOOGLE_SEARCH_API_KEY,
199
+ * search_engine_id: process.env.GOOGLE_CSE_ID,
200
+ * num_results: 3,
201
+ * });
202
+ * ```
194
203
  */
195
204
  export class WebSearchSkill extends SkillBase {
196
205
  // Python ground truth: skills/web_search/skill.py:559-567