@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
@@ -14,29 +14,72 @@ export class DatasphereDocuments extends CrudResource {
14
14
  super(http, '/api/datasphere/documents');
15
15
  }
16
16
 
17
- /** Semantic search across documents. */
17
+ /**
18
+ * Run a semantic search across indexed documents.
19
+ *
20
+ * @param body - Search payload (typically `{ query: "...", document_id?: "...",
21
+ * limit?: 5, tags?: [...] }`).
22
+ * @returns The ranked search hits.
23
+ * @throws {RestError} On any non-2xx HTTP response.
24
+ */
18
25
  async search(body: any): Promise<any> {
19
26
  return this._http.post(this._path('search'), body);
20
27
  }
21
28
 
22
- /** List chunks for a document. */
29
+ /**
30
+ * List content chunks for a document.
31
+ *
32
+ * @param documentId - Unique identifier of the document.
33
+ * @param params - Optional filter / pagination query parameters.
34
+ * @returns A paginated list of chunks.
35
+ * @throws {RestError} On any non-2xx HTTP response.
36
+ */
23
37
  async listChunks(documentId: string, params?: QueryParams): Promise<any> {
24
38
  return this._http.get(this._path(documentId, 'chunks'), params);
25
39
  }
26
40
 
27
- /** Get a specific chunk. */
41
+ /**
42
+ * Fetch a specific chunk of a document by ID.
43
+ *
44
+ * @param documentId - Unique identifier of the document.
45
+ * @param chunkId - Unique identifier of the chunk.
46
+ * @returns The chunk record with its content.
47
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
48
+ */
28
49
  async getChunk(documentId: string, chunkId: string): Promise<any> {
29
50
  return this._http.get(this._path(documentId, 'chunks', chunkId));
30
51
  }
31
52
 
32
- /** Delete a specific chunk. */
53
+ /**
54
+ * Delete a specific chunk from a document.
55
+ *
56
+ * @param documentId - Unique identifier of the document.
57
+ * @param chunkId - Unique identifier of the chunk.
58
+ * @returns The platform's delete response.
59
+ * @throws {RestError} On any non-2xx HTTP response.
60
+ */
33
61
  async deleteChunk(documentId: string, chunkId: string): Promise<any> {
34
62
  return this._http.delete(this._path(documentId, 'chunks', chunkId));
35
63
  }
36
64
  }
37
65
 
38
- /** Datasphere API namespace. */
66
+ /**
67
+ * Datasphere API namespace.
68
+ *
69
+ * Access via `client.datasphere.*`. Datasphere is SignalWire's RAG service —
70
+ * index documents and run semantic search from within agent tools.
71
+ *
72
+ * @example
73
+ * ```ts
74
+ * const hits = await client.datasphere.documents.search({
75
+ * query: 'refund policy',
76
+ * document_id: 'doc_abc',
77
+ * limit: 5,
78
+ * });
79
+ * ```
80
+ */
39
81
  export class DatasphereNamespace {
82
+ /** Document CRUD plus semantic search and chunk management. */
40
83
  readonly documents: DatasphereDocuments;
41
84
 
42
85
  constructor(http: HttpClient) {
@@ -25,22 +25,46 @@ export class FabricResourcePUT extends CrudWithAddresses {
25
25
  }
26
26
  }
27
27
 
28
- /** Call flows with version management. Uses singular 'call_flow' for sub-resource paths. */
28
+ /** Call flows with version management. Uses singular `call_flow` for sub-resource paths. */
29
29
  export class CallFlowsResource extends FabricResourcePUT {
30
30
  constructor(http: HttpClient, basePath: string) {
31
31
  super(http, basePath);
32
32
  }
33
33
 
34
+ /**
35
+ * List addresses attached to a call flow resource.
36
+ *
37
+ * @param resourceId - Unique identifier of the call flow.
38
+ * @param params - Optional filter / pagination query parameters.
39
+ * @returns A paginated list of addresses.
40
+ * @throws {RestError} On any non-2xx HTTP response.
41
+ */
34
42
  override async listAddresses(resourceId: string, params?: QueryParams): Promise<any> {
35
43
  const path = this._basePath.replace('/call_flows', '/call_flow');
36
44
  return this._http.get(`${path}/${resourceId}/addresses`, params);
37
45
  }
38
46
 
47
+ /**
48
+ * List all saved versions of a call flow.
49
+ *
50
+ * @param resourceId - Unique identifier of the call flow.
51
+ * @param params - Optional filter / pagination query parameters.
52
+ * @returns A paginated list of call-flow versions.
53
+ * @throws {RestError} On any non-2xx HTTP response.
54
+ */
39
55
  async listVersions(resourceId: string, params?: QueryParams): Promise<any> {
40
56
  const path = this._basePath.replace('/call_flows', '/call_flow');
41
57
  return this._http.get(`${path}/${resourceId}/versions`, params);
42
58
  }
43
59
 
60
+ /**
61
+ * Publish a new version of a call flow.
62
+ *
63
+ * @param resourceId - Unique identifier of the call flow.
64
+ * @param body - Version payload (schema and metadata). Defaults to `{}`.
65
+ * @returns The newly-published version record.
66
+ * @throws {RestError} On any non-2xx HTTP response.
67
+ */
44
68
  async deployVersion(resourceId: string, body: any = {}): Promise<any> {
45
69
  const path = this._basePath.replace('/call_flows', '/call_flow');
46
70
  return this._http.post(`${path}/${resourceId}/versions`, body);
@@ -53,6 +77,14 @@ export class ConferenceRoomsResource extends FabricResourcePUT {
53
77
  super(http, basePath);
54
78
  }
55
79
 
80
+ /**
81
+ * List addresses attached to a conference-room resource.
82
+ *
83
+ * @param resourceId - Unique identifier of the conference room.
84
+ * @param params - Optional filter / pagination query parameters.
85
+ * @returns A paginated list of addresses.
86
+ * @throws {RestError} On any non-2xx HTTP response.
87
+ */
56
88
  override async listAddresses(resourceId: string, params?: QueryParams): Promise<any> {
57
89
  const path = this._basePath.replace('/conference_rooms', '/conference_room');
58
90
  return this._http.get(`${path}/${resourceId}/addresses`, params);
@@ -65,22 +97,63 @@ export class SubscribersResource extends FabricResourcePUT {
65
97
  super(http, basePath);
66
98
  }
67
99
 
100
+ /**
101
+ * List the SIP endpoints registered under a subscriber.
102
+ *
103
+ * @param subscriberId - Unique identifier of the subscriber.
104
+ * @param params - Optional filter / pagination query parameters.
105
+ * @returns A paginated list of SIP endpoints.
106
+ * @throws {RestError} On any non-2xx HTTP response.
107
+ */
68
108
  async listSipEndpoints(subscriberId: string, params?: QueryParams): Promise<any> {
69
109
  return this._http.get(this._path(subscriberId, 'sip_endpoints'), params);
70
110
  }
71
111
 
112
+ /**
113
+ * Register a new SIP endpoint under a subscriber.
114
+ *
115
+ * @param subscriberId - Unique identifier of the subscriber.
116
+ * @param body - SIP endpoint payload (credentials, codecs, etc.).
117
+ * @returns The newly-created SIP endpoint record.
118
+ * @throws {RestError} On any non-2xx HTTP response.
119
+ */
72
120
  async createSipEndpoint(subscriberId: string, body: any): Promise<any> {
73
121
  return this._http.post(this._path(subscriberId, 'sip_endpoints'), body);
74
122
  }
75
123
 
124
+ /**
125
+ * Fetch a single SIP endpoint by ID.
126
+ *
127
+ * @param subscriberId - Unique identifier of the subscriber.
128
+ * @param endpointId - Unique identifier of the SIP endpoint.
129
+ * @returns The SIP endpoint record.
130
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
131
+ */
76
132
  async getSipEndpoint(subscriberId: string, endpointId: string): Promise<any> {
77
133
  return this._http.get(this._path(subscriberId, 'sip_endpoints', endpointId));
78
134
  }
79
135
 
136
+ /**
137
+ * Update a SIP endpoint's settings.
138
+ *
139
+ * @param subscriberId - Unique identifier of the subscriber.
140
+ * @param endpointId - Unique identifier of the SIP endpoint.
141
+ * @param body - Partial update payload (PATCH semantics).
142
+ * @returns The updated SIP endpoint record.
143
+ * @throws {RestError} On any non-2xx HTTP response.
144
+ */
80
145
  async updateSipEndpoint(subscriberId: string, endpointId: string, body: any): Promise<any> {
81
146
  return this._http.patch(this._path(subscriberId, 'sip_endpoints', endpointId), body);
82
147
  }
83
148
 
149
+ /**
150
+ * Delete a SIP endpoint.
151
+ *
152
+ * @param subscriberId - Unique identifier of the subscriber.
153
+ * @param endpointId - Unique identifier of the SIP endpoint.
154
+ * @returns The platform's delete response.
155
+ * @throws {RestError} On any non-2xx HTTP response.
156
+ */
84
157
  async deleteSipEndpoint(subscriberId: string, endpointId: string): Promise<any> {
85
158
  return this._http.delete(this._path(subscriberId, 'sip_endpoints', endpointId));
86
159
  }
@@ -103,26 +176,71 @@ export class GenericResources extends BaseResource {
103
176
  super(http, basePath);
104
177
  }
105
178
 
179
+ /**
180
+ * List all fabric resources regardless of specific type.
181
+ *
182
+ * @param params - Optional filter / pagination query parameters.
183
+ * @returns A paginated list of generic fabric resources.
184
+ * @throws {RestError} On any non-2xx HTTP response.
185
+ */
106
186
  async list(params?: QueryParams): Promise<any> {
107
187
  return this._http.get(this._basePath, params);
108
188
  }
109
189
 
190
+ /**
191
+ * Fetch a single fabric resource by ID.
192
+ *
193
+ * @param resourceId - Unique identifier of the resource.
194
+ * @returns The resource record.
195
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
196
+ */
110
197
  async get(resourceId: string): Promise<any> {
111
198
  return this._http.get(this._path(resourceId));
112
199
  }
113
200
 
201
+ /**
202
+ * Delete a fabric resource.
203
+ *
204
+ * @param resourceId - Unique identifier of the resource.
205
+ * @returns The platform's delete response.
206
+ * @throws {RestError} On any non-2xx HTTP response.
207
+ */
114
208
  async delete(resourceId: string): Promise<any> {
115
209
  return this._http.delete(this._path(resourceId));
116
210
  }
117
211
 
212
+ /**
213
+ * List addresses associated with any fabric resource.
214
+ *
215
+ * @param resourceId - Unique identifier of the resource.
216
+ * @param params - Optional filter / pagination query parameters.
217
+ * @returns A paginated list of addresses.
218
+ * @throws {RestError} On any non-2xx HTTP response.
219
+ */
118
220
  async listAddresses(resourceId: string, params?: QueryParams): Promise<any> {
119
221
  return this._http.get(this._path(resourceId, 'addresses'), params);
120
222
  }
121
223
 
224
+ /**
225
+ * Assign a phone route to a fabric resource.
226
+ *
227
+ * @param resourceId - Unique identifier of the resource.
228
+ * @param body - Phone route payload (typically `{ phone_number_id }`).
229
+ * @returns The phone-route assignment record.
230
+ * @throws {RestError} On any non-2xx HTTP response.
231
+ */
122
232
  async assignPhoneRoute(resourceId: string, body: any): Promise<any> {
123
233
  return this._http.post(this._path(resourceId, 'phone_routes'), body);
124
234
  }
125
235
 
236
+ /**
237
+ * Assign a domain application to a fabric resource.
238
+ *
239
+ * @param resourceId - Unique identifier of the resource.
240
+ * @param body - Domain application payload.
241
+ * @returns The domain-application assignment record.
242
+ * @throws {RestError} On any non-2xx HTTP response.
243
+ */
126
244
  async assignDomainApplication(resourceId: string, body: any): Promise<any> {
127
245
  return this._http.post(this._path(resourceId, 'domain_applications'), body);
128
246
  }
@@ -134,10 +252,24 @@ export class FabricAddresses extends BaseResource {
134
252
  super(http, basePath);
135
253
  }
136
254
 
255
+ /**
256
+ * List all fabric addresses in the project.
257
+ *
258
+ * @param params - Optional filter / pagination query parameters.
259
+ * @returns A paginated list of fabric addresses.
260
+ * @throws {RestError} On any non-2xx HTTP response.
261
+ */
137
262
  async list(params?: QueryParams): Promise<any> {
138
263
  return this._http.get(this._basePath, params);
139
264
  }
140
265
 
266
+ /**
267
+ * Fetch a single fabric address by ID.
268
+ *
269
+ * @param addressId - Unique identifier of the address.
270
+ * @returns The address record.
271
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
272
+ */
141
273
  async get(addressId: string): Promise<any> {
142
274
  return this._http.get(this._path(addressId));
143
275
  }
@@ -149,49 +281,112 @@ export class FabricTokens extends BaseResource {
149
281
  super(http, '/api/fabric');
150
282
  }
151
283
 
284
+ /**
285
+ * Issue a new subscriber JWT used by end-user clients.
286
+ *
287
+ * @param body - Token payload (subscriber ID, TTL, scopes). Defaults to `{}`.
288
+ * @returns The token record, typically `{ token: "eyJ..." }`.
289
+ * @throws {RestError} On any non-2xx HTTP response.
290
+ */
152
291
  async createSubscriberToken(body: any = {}): Promise<any> {
153
292
  return this._http.post(this._path('subscribers', 'tokens'), body);
154
293
  }
155
294
 
295
+ /**
296
+ * Refresh an existing subscriber JWT, extending its lifetime.
297
+ *
298
+ * @param body - Refresh payload (usually containing the current token).
299
+ * Defaults to `{}`.
300
+ * @returns The refreshed token record.
301
+ * @throws {RestError} On any non-2xx HTTP response.
302
+ */
156
303
  async refreshSubscriberToken(body: any = {}): Promise<any> {
157
304
  return this._http.post(this._path('subscribers', 'tokens', 'refresh'), body);
158
305
  }
159
306
 
307
+ /**
308
+ * Create a single-use invite token for onboarding a new subscriber.
309
+ *
310
+ * @param body - Invite payload (email, phone, permissions). Defaults to `{}`.
311
+ * @returns The invite record, including the share URL / code.
312
+ * @throws {RestError} On any non-2xx HTTP response.
313
+ */
160
314
  async createInviteToken(body: any = {}): Promise<any> {
161
315
  return this._http.post(this._path('subscriber', 'invites'), body);
162
316
  }
163
317
 
318
+ /**
319
+ * Issue a guest token (no subscriber account required).
320
+ *
321
+ * @param body - Guest-token payload (context, TTL, etc.). Defaults to `{}`.
322
+ * @returns The token record.
323
+ * @throws {RestError} On any non-2xx HTTP response.
324
+ */
164
325
  async createGuestToken(body: any = {}): Promise<any> {
165
326
  return this._http.post(this._path('guests', 'tokens'), body);
166
327
  }
167
328
 
329
+ /**
330
+ * Issue a short-lived embed token for browser-side SignalWire widgets.
331
+ *
332
+ * @param body - Embed-token payload (allowed origins, TTL, etc.). Defaults to `{}`.
333
+ * @returns The token record.
334
+ * @throws {RestError} On any non-2xx HTTP response.
335
+ */
168
336
  async createEmbedToken(body: any = {}): Promise<any> {
169
337
  return this._http.post(this._path('embeds', 'tokens'), body);
170
338
  }
171
339
  }
172
340
 
173
- /** Fabric API namespace grouping all resource types. */
341
+ /**
342
+ * Fabric API namespace grouping all resource types.
343
+ *
344
+ * Access via `client.fabric.*`.
345
+ *
346
+ * @example
347
+ * ```ts
348
+ * const agents = await client.fabric.aiAgents.list();
349
+ * const flow = await client.fabric.callFlows.create({ name: 'main-ivr' });
350
+ * const token = await client.fabric.tokens.createSubscriberToken({ subscriber_id: 'sub_123' });
351
+ * ```
352
+ */
174
353
  export class FabricNamespace {
175
354
  // PUT-update resources
355
+ /** SWML script CRUD (full-replacement `PUT` update). */
176
356
  readonly swmlScripts: FabricResourcePUT;
357
+ /** Relay Application CRUD (full-replacement `PUT` update). */
177
358
  readonly relayApplications: FabricResourcePUT;
359
+ /** Call Flow CRUD with version listing and publishing. */
178
360
  readonly callFlows: CallFlowsResource;
361
+ /** Conference Room CRUD with address listing. */
179
362
  readonly conferenceRooms: ConferenceRoomsResource;
363
+ /** FreeSWITCH Connector CRUD. */
180
364
  readonly freeswitchConnectors: FabricResourcePUT;
365
+ /** Subscriber CRUD plus nested SIP endpoint management. */
181
366
  readonly subscribers: SubscribersResource;
367
+ /** Top-level SIP endpoint CRUD. */
182
368
  readonly sipEndpoints: FabricResourcePUT;
369
+ /** cXML (LaML) script CRUD. */
183
370
  readonly cxmlScripts: FabricResourcePUT;
371
+ /** cXML application read / update / delete (no create). */
184
372
  readonly cxmlApplications: CxmlApplicationsResource;
185
373
 
186
374
  // PATCH-update resources
375
+ /** SWML webhook CRUD (partial-update `PATCH` semantics). */
187
376
  readonly swmlWebhooks: FabricResource;
377
+ /** AI Agent CRUD — the platform-managed agent registration resource. */
188
378
  readonly aiAgents: FabricResource;
379
+ /** SIP Gateway CRUD. */
189
380
  readonly sipGateways: FabricResource;
381
+ /** cXML webhook CRUD. */
190
382
  readonly cxmlWebhooks: FabricResource;
191
383
 
192
384
  // Special resources
385
+ /** Generic operations across all resource types (list, get, delete, phone route assignment). */
193
386
  readonly resources: GenericResources;
387
+ /** Read-only access to the unified fabric address table. */
194
388
  readonly addresses: FabricAddresses;
389
+ /** Subscriber, guest, invite, and embed token generation. */
195
390
  readonly tokens: FabricTokens;
196
391
 
197
392
  constructor(http: HttpClient) {
@@ -7,13 +7,24 @@
7
7
  import type { HttpClient } from '../HttpClient.js';
8
8
  import { BaseResource } from '../base/BaseResource.js';
9
9
 
10
- /** Import externally-hosted phone numbers. */
10
+ /**
11
+ * Import externally-hosted phone numbers.
12
+ *
13
+ * Access via `client.importedNumbers.*`.
14
+ */
11
15
  export class ImportedNumbersResource extends BaseResource {
12
16
  constructor(http: HttpClient) {
13
17
  super(http, '/api/relay/rest/imported_phone_numbers');
14
18
  }
15
19
 
16
- /** Import a phone number. */
20
+ /**
21
+ * Import an externally-hosted phone number into this project.
22
+ *
23
+ * @param body - Import payload specifying the number, carrier details,
24
+ * and any routing configuration required by the platform.
25
+ * @returns The newly-imported phone-number record.
26
+ * @throws {RestError} On any non-2xx HTTP response.
27
+ */
17
28
  async create(body: any): Promise<any> {
18
29
  return this._http.post(this._basePath, body);
19
30
  }
@@ -14,10 +14,25 @@ export class MessageLogs extends BaseResource {
14
14
  super(http, basePath);
15
15
  }
16
16
 
17
+ /**
18
+ * List message log entries.
19
+ *
20
+ * @param params - Optional filter / pagination query parameters
21
+ * (e.g. date range, direction, status).
22
+ * @returns A paginated list of message log entries.
23
+ * @throws {RestError} On any non-2xx HTTP response.
24
+ */
17
25
  async list(params?: QueryParams): Promise<any> {
18
26
  return this._http.get(this._basePath, params);
19
27
  }
20
28
 
29
+ /**
30
+ * Fetch a single message log entry by ID.
31
+ *
32
+ * @param logId - Unique identifier of the log entry.
33
+ * @returns The log entry record.
34
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
35
+ */
21
36
  async get(logId: string): Promise<any> {
22
37
  return this._http.get(this._path(logId));
23
38
  }
@@ -29,14 +44,36 @@ export class VoiceLogs extends BaseResource {
29
44
  super(http, basePath);
30
45
  }
31
46
 
47
+ /**
48
+ * List voice (call) log entries.
49
+ *
50
+ * @param params - Optional filter / pagination query parameters.
51
+ * @returns A paginated list of voice log entries.
52
+ * @throws {RestError} On any non-2xx HTTP response.
53
+ */
32
54
  async list(params?: QueryParams): Promise<any> {
33
55
  return this._http.get(this._basePath, params);
34
56
  }
35
57
 
58
+ /**
59
+ * Fetch a single voice log entry by ID.
60
+ *
61
+ * @param logId - Unique identifier of the log entry.
62
+ * @returns The log entry record.
63
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
64
+ */
36
65
  async get(logId: string): Promise<any> {
37
66
  return this._http.get(this._path(logId));
38
67
  }
39
68
 
69
+ /**
70
+ * List events captured during a voice log entry.
71
+ *
72
+ * @param logId - Unique identifier of the log entry.
73
+ * @param params - Optional filter / pagination query parameters.
74
+ * @returns A paginated list of events for the log entry.
75
+ * @throws {RestError} On any non-2xx HTTP response.
76
+ */
40
77
  async listEvents(logId: string, params?: QueryParams): Promise<any> {
41
78
  return this._http.get(this._path(logId, 'events'), params);
42
79
  }
@@ -48,10 +85,24 @@ export class FaxLogs extends BaseResource {
48
85
  super(http, basePath);
49
86
  }
50
87
 
88
+ /**
89
+ * List fax log entries.
90
+ *
91
+ * @param params - Optional filter / pagination query parameters.
92
+ * @returns A paginated list of fax log entries.
93
+ * @throws {RestError} On any non-2xx HTTP response.
94
+ */
51
95
  async list(params?: QueryParams): Promise<any> {
52
96
  return this._http.get(this._basePath, params);
53
97
  }
54
98
 
99
+ /**
100
+ * Fetch a single fax log entry by ID.
101
+ *
102
+ * @param logId - Unique identifier of the log entry.
103
+ * @returns The log entry record.
104
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
105
+ */
55
106
  async get(logId: string): Promise<any> {
56
107
  return this._http.get(this._path(logId));
57
108
  }
@@ -63,16 +114,32 @@ export class ConferenceLogs extends BaseResource {
63
114
  super(http, basePath);
64
115
  }
65
116
 
117
+ /**
118
+ * List conference log entries.
119
+ *
120
+ * @param params - Optional filter / pagination query parameters.
121
+ * @returns A paginated list of conference log entries.
122
+ * @throws {RestError} On any non-2xx HTTP response.
123
+ */
66
124
  async list(params?: QueryParams): Promise<any> {
67
125
  return this._http.get(this._basePath, params);
68
126
  }
69
127
  }
70
128
 
71
- /** Logs API namespace. */
129
+ /**
130
+ * Logs API namespace.
131
+ *
132
+ * Access via `client.logs.*`. Read-only access to message, voice, fax, and
133
+ * conference logs for auditing and observability.
134
+ */
72
135
  export class LogsNamespace {
136
+ /** SMS/MMS message log queries. */
73
137
  readonly messages: MessageLogs;
138
+ /** Voice call log queries with event drill-down. */
74
139
  readonly voice: VoiceLogs;
140
+ /** Fax log queries. */
75
141
  readonly fax: FaxLogs;
142
+ /** Conference log queries. */
76
143
  readonly conferences: ConferenceLogs;
77
144
 
78
145
  constructor(http: HttpClient) {
@@ -8,13 +8,30 @@ import type { HttpClient } from '../HttpClient.js';
8
8
  import type { QueryParams } from '../types.js';
9
9
  import { BaseResource } from '../base/BaseResource.js';
10
10
 
11
- /** Phone number lookup (carrier, CNAM). */
11
+ /**
12
+ * Phone number lookup (carrier, CNAM).
13
+ *
14
+ * Access via `client.lookup.*`.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * const info = await client.lookup.phoneNumber('+15551234567', { include: 'carrier,caller-name' });
19
+ * ```
20
+ */
12
21
  export class LookupResource extends BaseResource {
13
22
  constructor(http: HttpClient) {
14
23
  super(http, '/api/relay/rest/lookup');
15
24
  }
16
25
 
17
- /** Look up carrier/CNAM info for a phone number. */
26
+ /**
27
+ * Look up carrier and CNAM information for a phone number.
28
+ *
29
+ * @param e164 - The phone number in E.164 format (e.g. `"+15551234567"`).
30
+ * @param params - Optional query parameters, most commonly
31
+ * `include: "carrier,caller-name"` to enable carrier and CNAM lookups.
32
+ * @returns The lookup record containing any requested datasets.
33
+ * @throws {RestError} On any non-2xx HTTP response.
34
+ */
18
35
  async phoneNumber(e164: string, params?: QueryParams): Promise<any> {
19
36
  return this._http.get(this._path('phone_number', e164), params);
20
37
  }
@@ -7,23 +7,54 @@
7
7
  import type { HttpClient } from '../HttpClient.js';
8
8
  import { BaseResource } from '../base/BaseResource.js';
9
9
 
10
- /** Multi-factor authentication via SMS or phone call. */
10
+ /**
11
+ * Multi-factor authentication via SMS or phone call.
12
+ *
13
+ * Access via `client.mfa.*`. Two-step flow: call `.sms()` or `.call()` to send
14
+ * a code, then `.verify()` to confirm it.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * const req = await client.mfa.sms({ to: '+15551234567' });
19
+ * const result = await client.mfa.verify(req.id, { token: '123456' });
20
+ * ```
21
+ */
11
22
  export class MfaResource extends BaseResource {
12
23
  constructor(http: HttpClient) {
13
24
  super(http, '/api/relay/rest/mfa');
14
25
  }
15
26
 
16
- /** Initiate MFA via SMS. */
27
+ /**
28
+ * Initiate MFA by sending a one-time code to a phone number over SMS.
29
+ *
30
+ * @param body - MFA request payload (typically `{ to: "+15551234567",
31
+ * message?: "Your code is {code}" }`).
32
+ * @returns The MFA request record; its `id` is used by {@link verify}.
33
+ * @throws {RestError} On any non-2xx HTTP response.
34
+ */
17
35
  async sms(body: any): Promise<any> {
18
36
  return this._http.post(this._path('sms'), body);
19
37
  }
20
38
 
21
- /** Initiate MFA via phone call. */
39
+ /**
40
+ * Initiate MFA by placing a phone call that reads out a one-time code.
41
+ *
42
+ * @param body - MFA request payload (typically `{ to: "+15551234567" }`).
43
+ * @returns The MFA request record; its `id` is used by {@link verify}.
44
+ * @throws {RestError} On any non-2xx HTTP response.
45
+ */
22
46
  async call(body: any): Promise<any> {
23
47
  return this._http.post(this._path('call'), body);
24
48
  }
25
49
 
26
- /** Verify an MFA code. */
50
+ /**
51
+ * Verify the one-time code the user received via SMS or call.
52
+ *
53
+ * @param requestId - The `id` returned from {@link sms} or {@link call}.
54
+ * @param body - Verification payload (typically `{ token: "123456" }`).
55
+ * @returns The verification result — success or failure shape.
56
+ * @throws {RestError} On any non-2xx HTTP response.
57
+ */
27
58
  async verify(requestId: string, body: any): Promise<any> {
28
59
  return this._http.post(this._path(requestId, 'verify'), body);
29
60
  }