@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
@@ -13,11 +13,27 @@ import type { HttpClientOptions, QueryParams } from './types.js';
13
13
 
14
14
  const logger = getLogger('rest_client');
15
15
 
16
+ /**
17
+ * Low-level HTTP client used by every REST namespace resource.
18
+ *
19
+ * Handles Basic Auth, JSON encoding/decoding, and error normalisation
20
+ * ({@link RestError} on non-2xx). Normally you do not instantiate this
21
+ * directly — construct a {@link RestClient} instead.
22
+ */
16
23
  export class HttpClient {
24
+ /** Fully-qualified base URL (no trailing slash). */
17
25
  readonly baseUrl: string;
18
26
  private readonly _authHeader: string;
19
27
  private readonly _fetch: typeof globalThis.fetch;
20
28
 
29
+ /**
30
+ * Build a new HTTP client.
31
+ *
32
+ * @param options - Connection options. Either `host` (bare hostname;
33
+ * `https://` is prepended automatically) or `baseUrl` (fully-qualified)
34
+ * must be provided along with `project` + `token`.
35
+ * @throws {Error} When neither `host` nor `baseUrl` is supplied.
36
+ */
21
37
  constructor(options: HttpClientOptions) {
22
38
  if (!options.host && !options.baseUrl) {
23
39
  throw new Error('HttpClientOptions requires either "host" or "baseUrl".');
@@ -81,22 +97,67 @@ export class HttpClient {
81
97
  return JSON.parse(text) as T;
82
98
  }
83
99
 
100
+ /**
101
+ * Perform an authenticated HTTP GET and return the parsed JSON response.
102
+ *
103
+ * @typeParam T - Expected response body type.
104
+ * @param path - Absolute URL or path relative to {@link HttpClient.baseUrl}.
105
+ * @param params - Optional query parameters; `undefined` values are skipped.
106
+ * @returns The parsed JSON body, or `{}` on `204 No Content`.
107
+ * @throws {RestError} On any non-2xx HTTP response.
108
+ */
84
109
  async get<T = any>(path: string, params?: QueryParams): Promise<T> {
85
110
  return this._request<T>('GET', path, undefined, params);
86
111
  }
87
112
 
113
+ /**
114
+ * Perform an authenticated HTTP POST and return the parsed JSON response.
115
+ *
116
+ * @typeParam T - Expected response body type.
117
+ * @param path - Absolute URL or path relative to {@link HttpClient.baseUrl}.
118
+ * @param body - JSON-serialisable request body. Omit to send no body.
119
+ * @param params - Optional query parameters appended to the URL.
120
+ * @returns The parsed JSON body, or `{}` on `204 No Content`.
121
+ * @throws {RestError} On any non-2xx HTTP response.
122
+ */
88
123
  async post<T = any>(path: string, body?: any, params?: QueryParams): Promise<T> {
89
124
  return this._request<T>('POST', path, body, params);
90
125
  }
91
126
 
127
+ /**
128
+ * Perform an authenticated HTTP PUT and return the parsed JSON response.
129
+ *
130
+ * @typeParam T - Expected response body type.
131
+ * @param path - Absolute URL or path relative to {@link HttpClient.baseUrl}.
132
+ * @param body - JSON-serialisable request body.
133
+ * @returns The parsed JSON body, or `{}` on `204 No Content`.
134
+ * @throws {RestError} On any non-2xx HTTP response.
135
+ */
92
136
  async put<T = any>(path: string, body?: any): Promise<T> {
93
137
  return this._request<T>('PUT', path, body);
94
138
  }
95
139
 
140
+ /**
141
+ * Perform an authenticated HTTP PATCH and return the parsed JSON response.
142
+ *
143
+ * @typeParam T - Expected response body type.
144
+ * @param path - Absolute URL or path relative to {@link HttpClient.baseUrl}.
145
+ * @param body - JSON-serialisable partial request body.
146
+ * @returns The parsed JSON body, or `{}` on `204 No Content`.
147
+ * @throws {RestError} On any non-2xx HTTP response.
148
+ */
96
149
  async patch<T = any>(path: string, body?: any): Promise<T> {
97
150
  return this._request<T>('PATCH', path, body);
98
151
  }
99
152
 
153
+ /**
154
+ * Perform an authenticated HTTP DELETE and return the parsed JSON response.
155
+ *
156
+ * @typeParam T - Expected response body type.
157
+ * @param path - Absolute URL or path relative to {@link HttpClient.baseUrl}.
158
+ * @returns The parsed JSON body, or `{}` on `204 No Content`.
159
+ * @throws {RestError} On any non-2xx HTTP response.
160
+ */
100
161
  async delete<T = any>(path: string): Promise<T> {
101
162
  return this._request<T>('DELETE', path);
102
163
  }
@@ -6,11 +6,25 @@
6
6
  * `SignalWireRestError` behavior.
7
7
  */
8
8
  export class RestError extends Error {
9
+ /** HTTP status code returned by the server (e.g. `404`, `500`). */
9
10
  readonly statusCode: number;
11
+ /**
12
+ * Parsed response body. An object when the server returned valid JSON,
13
+ * otherwise the raw response text as a string.
14
+ */
10
15
  readonly body: string | Record<string, unknown>;
16
+ /** Fully-qualified URL that produced the error. */
11
17
  readonly url: string;
18
+ /** HTTP method that produced the error (`GET`, `POST`, etc.). */
12
19
  readonly method: string;
13
20
 
21
+ /**
22
+ * @param statusCode - HTTP status code returned by the server.
23
+ * @param body - Response body — an object if JSON-parseable, otherwise the
24
+ * raw response text.
25
+ * @param url - Fully-qualified URL that produced the error.
26
+ * @param method - HTTP method that produced the error. Defaults to `"GET"`.
27
+ */
14
28
  constructor(
15
29
  statusCode: number,
16
30
  body: string | Record<string, unknown>,
@@ -1,18 +1,31 @@
1
+ import type { HttpClient } from '../HttpClient.js';
2
+
1
3
  /**
2
4
  * Abstract base class for all REST resources.
5
+ *
6
+ * Every namespace resource (e.g. {@link PhoneNumbersResource}, {@link VideoRooms})
7
+ * extends this class to get a typed reference to the shared {@link HttpClient}
8
+ * and a small path-building helper. Not exported for direct use — subclass it.
3
9
  */
4
- import type { HttpClient } from '../HttpClient.js';
5
-
6
10
  export abstract class BaseResource {
7
11
  protected readonly _http: HttpClient;
8
12
  protected readonly _basePath: string;
9
13
 
14
+ /**
15
+ * @param http - Shared HTTP client to issue requests through.
16
+ * @param basePath - Absolute path prefix (e.g. `'/api/relay/rest/phone_numbers'`).
17
+ */
10
18
  constructor(http: HttpClient, basePath: string) {
11
19
  this._http = http;
12
20
  this._basePath = basePath;
13
21
  }
14
22
 
15
- /** Build a sub-resource path by joining parts onto the base path. */
23
+ /**
24
+ * Build a sub-resource path by joining parts onto the base path.
25
+ *
26
+ * @param parts - String or numeric path segments to append.
27
+ * @returns The joined path (no trailing slash).
28
+ */
16
29
  protected _path(...parts: (string | number)[]): string {
17
30
  return [this._basePath, ...parts.map(String)].join('/');
18
31
  }
@@ -8,6 +8,19 @@ import type { HttpClient } from '../HttpClient.js';
8
8
  import type { QueryParams } from '../types.js';
9
9
  import { BaseResource } from './BaseResource.js';
10
10
 
11
+ /**
12
+ * Generic CRUD resource with configurable update method.
13
+ *
14
+ * Provides `list()`, `create()`, `get()`, `update()`, and `delete()` out of the
15
+ * box — most namespace resources extend this and narrow the generic types.
16
+ * `_updateMethod` may be overridden to `'PUT'` for APIs that replace instead
17
+ * of patch.
18
+ *
19
+ * @typeParam TList - Type of the paginated list response.
20
+ * @typeParam TItem - Type of a single resource item.
21
+ * @typeParam TCreate - Request body type for `create()`.
22
+ * @typeParam TUpdate - Request body type for `update()`.
23
+ */
11
24
  export class CrudResource<
12
25
  TList = any,
13
26
  TItem = any,
@@ -21,22 +34,50 @@ export class CrudResource<
21
34
  super(http, basePath);
22
35
  }
23
36
 
24
- /** List resources with optional query parameters. */
37
+ /**
38
+ * List resources with optional query parameters.
39
+ *
40
+ * @param params - Optional filter / pagination query parameters.
41
+ * @returns The paginated list response.
42
+ * @throws {RestError} On any non-2xx HTTP response.
43
+ */
25
44
  async list(params?: QueryParams): Promise<TList> {
26
45
  return this._http.get<TList>(this._basePath, params);
27
46
  }
28
47
 
29
- /** Create a new resource. */
48
+ /**
49
+ * Create a new resource.
50
+ *
51
+ * @param body - Request body describing the resource to create.
52
+ * @returns The newly-created resource.
53
+ * @throws {RestError} On any non-2xx HTTP response.
54
+ */
30
55
  async create(body: TCreate): Promise<TItem> {
31
56
  return this._http.post<TItem>(this._basePath, body);
32
57
  }
33
58
 
34
- /** Get a single resource by ID. */
59
+ /**
60
+ * Fetch a single resource by ID.
61
+ *
62
+ * @param resourceId - Unique identifier of the resource.
63
+ * @returns The resource record.
64
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
65
+ */
35
66
  async get(resourceId: string): Promise<TItem> {
36
67
  return this._http.get<TItem>(this._path(resourceId));
37
68
  }
38
69
 
39
- /** Update a resource by ID. */
70
+ /**
71
+ * Update a resource by ID.
72
+ *
73
+ * Uses HTTP `PATCH` by default; subclasses may set `_updateMethod = 'PUT'`
74
+ * when the remote API requires a full-replacement semantics.
75
+ *
76
+ * @param resourceId - Unique identifier of the resource.
77
+ * @param body - Request body with updated fields.
78
+ * @returns The updated resource.
79
+ * @throws {RestError} On any non-2xx HTTP response.
80
+ */
40
81
  async update(resourceId: string, body: TUpdate): Promise<TItem> {
41
82
  if (this._updateMethod === 'PUT') {
42
83
  return this._http.put<TItem>(this._path(resourceId), body);
@@ -44,7 +85,13 @@ export class CrudResource<
44
85
  return this._http.patch<TItem>(this._path(resourceId), body);
45
86
  }
46
87
 
47
- /** Delete a resource by ID. */
88
+ /**
89
+ * Delete a resource by ID.
90
+ *
91
+ * @param resourceId - Unique identifier of the resource.
92
+ * @returns The platform's delete response (often an empty body on success).
93
+ * @throws {RestError} On any non-2xx HTTP response.
94
+ */
48
95
  async delete(resourceId: string): Promise<any> {
49
96
  return this._http.delete(this._path(resourceId));
50
97
  }
@@ -8,6 +8,10 @@ import type { HttpClient } from '../HttpClient.js';
8
8
  import type { QueryParams } from '../types.js';
9
9
  import { CrudResource } from './CrudResource.js';
10
10
 
11
+ /**
12
+ * {@link CrudResource} extended with a `listAddresses()` helper for resources that
13
+ * have associated Address records (e.g. fabric resources).
14
+ */
11
15
  export class CrudWithAddresses<
12
16
  TList = any,
13
17
  TItem = any,
@@ -19,7 +23,14 @@ export class CrudWithAddresses<
19
23
  super(http, basePath);
20
24
  }
21
25
 
22
- /** List addresses associated with a resource. */
26
+ /**
27
+ * List addresses associated with a specific resource instance.
28
+ *
29
+ * @param resourceId - Unique identifier of the owning resource.
30
+ * @param params - Optional filter / pagination query parameters.
31
+ * @returns A paginated list of addresses.
32
+ * @throws {RestError} On any non-2xx HTTP response.
33
+ */
23
34
  async listAddresses(resourceId: string, params?: QueryParams): Promise<any> {
24
35
  return this._http.get(this._path(resourceId, 'addresses'), params);
25
36
  }
package/src/rest/index.ts CHANGED
@@ -57,44 +57,74 @@ const logger = getLogger('rest_client');
57
57
  */
58
58
  export class RestClient {
59
59
  // Fabric API
60
+ /** Fabric composition — AI Agents, SWML scripts, call flows, tokens, etc. */
60
61
  readonly fabric: FabricNamespace;
61
62
 
62
63
  // Calling API
64
+ /** REST-based call control surface (all 37 commands as methods). */
63
65
  readonly calling: CallingNamespace;
64
66
 
65
67
  // Relay REST resources
68
+ /** Phone-number CRUD plus availability search. */
66
69
  readonly phoneNumbers: PhoneNumbersResource;
70
+ /** Relay Address CRUD. */
67
71
  readonly addresses: AddressesResource;
72
+ /** Call-queue CRUD plus member operations. */
68
73
  readonly queues: QueuesResource;
74
+ /** Recording read / delete. */
69
75
  readonly recordings: RecordingsResource;
76
+ /** Number-group CRUD plus membership operations. */
70
77
  readonly numberGroups: NumberGroupsResource;
78
+ /** Verified Caller ID CRUD plus verification flow. */
71
79
  readonly verifiedCallers: VerifiedCallersResource;
80
+ /** Project-level SIP profile read / update (singleton). */
72
81
  readonly sipProfile: SipProfileResource;
82
+ /** Carrier + CNAM phone-number lookups. */
73
83
  readonly lookup: LookupResource;
84
+ /** Short-code read / update. */
74
85
  readonly shortCodes: ShortCodesResource;
86
+ /** Import externally-hosted phone numbers. */
75
87
  readonly importedNumbers: ImportedNumbersResource;
88
+ /** Multi-factor authentication (SMS / voice code send + verify). */
76
89
  readonly mfa: MfaResource;
90
+ /** US 10DLC Campaign Registry — brands, campaigns, orders, numbers. */
77
91
  readonly registry: RegistryNamespace;
78
92
 
79
93
  // Datasphere API
94
+ /** Datasphere RAG — document indexing and semantic search. */
80
95
  readonly datasphere: DatasphereNamespace;
81
96
 
82
97
  // Video API
98
+ /** Video rooms, sessions, recordings, conferences, tokens, streams. */
83
99
  readonly video: VideoNamespace;
84
100
 
85
101
  // Logs
102
+ /** Read-only message / voice / fax / conference logs. */
86
103
  readonly logs: LogsNamespace;
87
104
 
88
105
  // Project management
106
+ /** Project-scoped API token management. */
89
107
  readonly project: ProjectNamespace;
90
108
 
91
109
  // PubSub & Chat
110
+ /** PubSub token issuance. */
92
111
  readonly pubsub: PubSubResource;
112
+ /** Chat token issuance. */
93
113
  readonly chat: ChatResource;
94
114
 
95
115
  // Compatibility (Twilio-compatible) API
116
+ /** Twilio-compatible LAML surface (legacy; prefer native namespaces for new work). */
96
117
  readonly compat: CompatNamespace;
97
118
 
119
+ /**
120
+ * Create a new REST client.
121
+ *
122
+ * @param options - Connection options. `project`, `token`, and `host` are
123
+ * required. If any are omitted they fall back to `SIGNALWIRE_PROJECT_ID`,
124
+ * `SIGNALWIRE_API_TOKEN`, and `SIGNALWIRE_SPACE` environment variables.
125
+ * @throws {Error} When `project`, `token`, or `host` is missing from both
126
+ * the options and the environment.
127
+ */
98
128
  constructor(options: ClientOptions = {}) {
99
129
  const project = options.project || process.env['SIGNALWIRE_PROJECT_ID'] || '';
100
130
  const token = options.token || process.env['SIGNALWIRE_API_TOKEN'] || '';
@@ -8,24 +8,56 @@ 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
- /** Address management (no update endpoint). */
11
+ /**
12
+ * Address management (no update endpoint).
13
+ *
14
+ * Access via `client.addresses.*`.
15
+ */
12
16
  export class AddressesResource extends BaseResource {
13
17
  constructor(http: HttpClient) {
14
18
  super(http, '/api/relay/rest/addresses');
15
19
  }
16
20
 
21
+ /**
22
+ * List all addresses in the project.
23
+ *
24
+ * @param params - Optional filter / pagination query parameters.
25
+ * @returns A paginated list of addresses.
26
+ * @throws {RestError} On any non-2xx HTTP response.
27
+ */
17
28
  async list(params?: QueryParams): Promise<any> {
18
29
  return this._http.get(this._basePath, params);
19
30
  }
20
31
 
32
+ /**
33
+ * Create a new address.
34
+ *
35
+ * @param body - Address attributes (name, display name, context, etc.).
36
+ * @returns The newly-created address.
37
+ * @throws {RestError} On any non-2xx HTTP response.
38
+ */
21
39
  async create(body: any): Promise<any> {
22
40
  return this._http.post(this._basePath, body);
23
41
  }
24
42
 
43
+ /**
44
+ * Fetch a single address by ID.
45
+ *
46
+ * @param addressId - Unique identifier of the address.
47
+ * @returns The address record.
48
+ * @throws {RestError} On any non-2xx HTTP response (including `404`).
49
+ */
25
50
  async get(addressId: string): Promise<any> {
26
51
  return this._http.get(this._path(addressId));
27
52
  }
28
53
 
54
+ /**
55
+ * Delete an address.
56
+ *
57
+ * @param addressId - Unique identifier of the address.
58
+ * @returns The platform's delete response.
59
+ * @throws {RestError} On any non-2xx HTTP response.
60
+ */
29
61
  async delete(addressId: string): Promise<any> {
30
62
  return this._http.delete(this._path(addressId));
31
63
  }