@signalhousellc/sdk 1.5.1 → 1.6.0

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 (54) hide show
  1. package/README.md +5 -56
  2. package/index.d.ts +1 -0
  3. package/index.js +2 -0
  4. package/package.json +32 -34
  5. package/voice-browser.d.ts +1 -0
  6. package/voice-browser.js +2 -0
  7. package/warn.js +7 -0
  8. package/webhooks.d.ts +1 -0
  9. package/webhooks.js +2 -0
  10. package/scripts/install-skills.mjs +0 -329
  11. package/skills/VENDORED.json +0 -22
  12. package/skills/signalhouse-10dlc/SKILL.md +0 -172
  13. package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md +0 -62
  14. package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md +0 -104
  15. package/skills/signalhouse-advisor/SKILL.md +0 -84
  16. package/skills/signalhouse-numbers/SKILL.md +0 -82
  17. package/skills/signalhouse-setup/SKILL.md +0 -121
  18. package/skills/signalhouse-sms/SKILL.md +0 -81
  19. package/skills/signalhouse-webhooks/SKILL.md +0 -148
  20. package/src/SignalHouseSDK.js +0 -201
  21. package/src/domains/Agents.js +0 -987
  22. package/src/domains/Auth.js +0 -225
  23. package/src/domains/Billing.js +0 -265
  24. package/src/domains/Brands.js +0 -566
  25. package/src/domains/Campaigns.js +0 -691
  26. package/src/domains/Dnc.js +0 -168
  27. package/src/domains/Groups.js +0 -187
  28. package/src/domains/Landings.js +0 -237
  29. package/src/domains/Messages.js +0 -609
  30. package/src/domains/Notifications.js +0 -62
  31. package/src/domains/Numbers.js +0 -574
  32. package/src/domains/Onboarding.js +0 -128
  33. package/src/domains/Registrations.js +0 -246
  34. package/src/domains/Shortlinks.js +0 -80
  35. package/src/domains/Subgroups.js +0 -136
  36. package/src/domains/Subscriptions.js +0 -164
  37. package/src/domains/Templates.js +0 -403
  38. package/src/domains/Tickets.js +0 -100
  39. package/src/domains/Users.js +0 -228
  40. package/src/domains/Voice.js +0 -41
  41. package/src/domains/Webhooks.js +0 -125
  42. package/src/domains/voice/Analytics.js +0 -82
  43. package/src/domains/voice/CallLogs.js +0 -111
  44. package/src/domains/voice/Calls.js +0 -118
  45. package/src/domains/voice/GlobalVoiceSettings.js +0 -54
  46. package/src/domains/voice/NumberRoutes.js +0 -82
  47. package/src/domains/voice/ProgrammableVoiceProfiles.js +0 -191
  48. package/src/domains/voice/SipProfiles.js +0 -203
  49. package/src/domains/voice/SipTrunks.js +0 -203
  50. package/src/domains/voice/Tokens.js +0 -96
  51. package/src/domains/voice/browser/Call.js +0 -366
  52. package/src/domains/voice/browser/Device.js +0 -484
  53. package/src/domains/voice/browser/index.js +0 -17
  54. package/src/webhooks/verifySignature.js +0 -66
@@ -1,987 +0,0 @@
1
- /** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
2
- /**
3
- * @template T
4
- * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
5
- */
6
-
7
- /**
8
- * @typedef {Object} CreateAgentProfileData
9
- * @property {string} groupId - The parent group id (at least 8 characters, starts with 'G').
10
- * @property {string|null} [subgroupId] - Optional subgroup id (at least 8 characters, starts with 'S'); null/omitted = group-level agent.
11
- * @property {string} name - The agent's name (required).
12
- * @property {string} [status] - Lifecycle status: "active" or "inactive" (defaults to "active").
13
- * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
14
- * @property {string} [greeting] - Opening line the agent leads with.
15
- * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
16
- * @property {string} [sendAuthority] - Default send authority: "review" or "autopilot" (defaults to "review"). Deployments may override it per subgroup.
17
- */
18
-
19
- /**
20
- * @typedef {Object} UpdateAgentProfileData
21
- * @property {string} [name] - The agent's name.
22
- * @property {string} [status] - Lifecycle status: "active" or "inactive".
23
- * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
24
- * @property {string} [greeting] - Opening line the agent leads with.
25
- * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
26
- * @property {string} [sendAuthority] - Default send authority: "review" or "autopilot". Deployments may override it per subgroup.
27
- */
28
-
29
- /**
30
- * An agent profile as returned by the server. `publishStatus` and `publishedAt` are read-only:
31
- * they change only through `publishAgentProfile` and `unpublishAgentProfile`.
32
- * @typedef {Object} AgentProfile
33
- * @property {string} agentProfileId - The agent profile id.
34
- * @property {string} groupId - The owning group id.
35
- * @property {string|null} subgroupId - The owning subgroup id; null for a group-level agent.
36
- * @property {string} name - The agent's name.
37
- * @property {string} status - Lifecycle status: "active" or "inactive".
38
- * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
39
- * @property {string} [greeting] - Opening line the agent leads with.
40
- * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
41
- * @property {string} sendAuthority - Default send authority: "review" or "autopilot".
42
- * @property {string} publishStatus - "draft" or "published" (read-only).
43
- * @property {string|null} publishedAt - When the profile was last published; null while never published (read-only).
44
- * @property {string} createdAt - Creation timestamp.
45
- * @property {string} updatedAt - Last-update timestamp.
46
- */
47
-
48
- /**
49
- * The fields of a deployment of a group-level agent to a subgroup.
50
- * @typedef {Object} AgentDeploymentData
51
- * @property {string|null} [sendAuthorityOverride] - "review" or "autopilot" to override the profile's default for this subgroup; null clears the override so the deployment inherits the profile default.
52
- * @property {boolean} [enabled] - Whether this deployment is live (defaults to true).
53
- */
54
-
55
- /**
56
- * A deployment of a group-level agent to a subgroup, as returned by the server.
57
- * @typedef {Object} AgentDeployment
58
- * @property {string} agentDeploymentId - The deployment id.
59
- * @property {string} groupId - The group that owns the agent and the subgroup.
60
- * @property {string} subgroupId - The subgroup the agent is deployed to.
61
- * @property {string} agentProfileId - The deployed agent.
62
- * @property {string|null} sendAuthorityOverride - "review", "autopilot", or null (inherit the profile default).
63
- * @property {string|null} sendAuthorityChangedBy - userId of whoever last changed the override.
64
- * @property {string|null} sendAuthorityChangedAt - When the override last changed.
65
- * @property {boolean} enabled - Whether this deployment is live.
66
- * @property {string} createdAt - Creation timestamp.
67
- * @property {string} updatedAt - Last-update timestamp.
68
- */
69
-
70
- /**
71
- * The fields of an endpoint binding: which agent answers a number.
72
- * @typedef {Object} AgentEndpointData
73
- * @property {string} agentProfileId - The agent that answers the number (required). It must be active, in the number's group, and either belong to the number's subgroup or be a group-level agent with an enabled deployment there.
74
- * @property {string} [answerMode] - Which inbound messages the agent answers: "all_inbound" (the only mode, and the default).
75
- */
76
-
77
- /**
78
- * An endpoint binding (which agent answers a number), as returned by the server.
79
- * @typedef {Object} AgentEndpoint
80
- * @property {string} agentEndpointId - The binding id ("AEP..." prefix).
81
- * @property {string} groupId - The group that owns the binding.
82
- * @property {string|null} subgroupId - The subgroup the number belongs to.
83
- * @property {string} channel - The channel; "sms" in v1.
84
- * @property {string} endpointType - The endpoint kind; "sms_number" in v1.
85
- * @property {string} endpointValue - The phone number: digits only, country code included, no "+".
86
- * @property {string} agentProfileId - The agent that answers the number.
87
- * @property {string} answerMode - Which inbound messages the agent answers ("all_inbound").
88
- * @property {Object|null} overrides - Free-form per-endpoint overrides; null when none.
89
- * @property {boolean} enabled - Whether the binding is live.
90
- * @property {string} createdAt - Creation timestamp.
91
- * @property {string} updatedAt - Last-update timestamp.
92
- */
93
-
94
- /**
95
- * A reply an SMS agent wrote but did not send, held for a person to approve or reject (the
96
- * Pending Replies queue), as returned by the server.
97
- * @typedef {Object} AgentReplyDraft
98
- * @property {string} agentReplyDraftId - The draft id ("ARD..." prefix).
99
- * @property {string} groupId - The group that owns the draft.
100
- * @property {string|null} subgroupId - The subgroup whose number the reply goes out from.
101
- * @property {string} agentProfileId - The agent that wrote the reply.
102
- * @property {string|null} conversationId - The conversation the reply belongs to.
103
- * @property {string} channel - The channel; "sms".
104
- * @property {string} endpointValue - The agent's number the reply is sent from, digits only.
105
- * @property {string} contactPhoneNumber - The contact the reply is sent to, digits only.
106
- * @property {string} inboundText - The contact message the agent was answering.
107
- * @property {string} draftText - The reply as the agent wrote it.
108
- * @property {string|null} sentText - The text actually sent; differs from draftText when edited.
109
- * @property {string} reason - Why it was held: "review_mode", "escalation", "fallback" or "guardrail".
110
- * @property {string} status - "pending", "sending", "sent", "rejected" or "failed" (the send path accepted nothing, e.g. the contact opted out).
111
- * @property {string|null} decidedBy - The user who approved or rejected it.
112
- * @property {string|null} decidedAt - When it was approved or rejected.
113
- * @property {string|null} sentMessageId - The outbound message id once sent (for an external delivery, the id you reported).
114
- * @property {string|null} claimId - The current claim's id (set when a decision claims the draft); complete and release must name it.
115
- * @property {string|null} deliveredBy - Who delivers an approved reply: "signalhouse" (approveAgentReplyDraft) or "external" (claimAgentReplyDraft); null until decided.
116
- * @property {string|null} failureReason - "delivery_unconfirmed" when an external claim was never completed or released; otherwise null.
117
- * @property {string} createdAt - Creation timestamp.
118
- * @property {string} updatedAt - Last-update timestamp.
119
- */
120
-
121
- /**
122
- * The per-channel settings for one agent. Model, voice and sampling settings live here rather
123
- * than on the profile: each channel is served by a different runtime, and the model catalogues
124
- * do not overlap — so a value that is valid on one channel may be invalid on another.
125
- * @typedef {Object} AgentChannelSettingData
126
- * @property {string[]} [allowedTools] - Tools enabled on this channel — built-in keys or custom agentTool ids.
127
- * @property {boolean} [enabled] - Whether the agent answers on this channel.
128
- * @property {string} [channelPrompt] - Channel-specific prompt text appended to the agent's system prompt.
129
- * @property {string|null} [greeting] - Channel-specific greeting override; null = use the agent's greeting.
130
- * @property {string} [llmProvider] - LLM backend for this channel: "bedrock", "openai", "anthropic", or "groq" (defaults to "bedrock").
131
- * @property {string|null} [llmModel] - Concrete model id for the provider; null = provider default.
132
- * @property {number} [temperature] - Sampling temperature (0-2).
133
- * @property {string|null} [voiceId] - Voice identifier for spoken channels; ignored off the voice channel.
134
- * @property {number|null} [speed] - Speaking rate multiplier (0.7-1.2); null = platform default.
135
- * @property {number|null} [stability] - Voice consistency (0-1); lower is more expressive and more variable.
136
- * @property {number|null} [similarityBoost] - How closely synthesis tracks the source voice (0-1).
137
- * @property {string|null} [speechModel] - Speech synthesis model; separate from `llmModel`, which decides what is said rather than how it is voiced.
138
- * @property {string|null} [turnEagerness] - How readily the agent decides the caller has finished: "patient", "normal", or "eager".
139
- * @property {number|null} [turnTimeoutSeconds] - Silence before the agent takes its turn: 1-300, or -1 for no timeout.
140
- * @property {number|null} [initialWaitSeconds] - Silence before the agent speaks first: 1-300, or -1 for no timeout.
141
- * @property {number|null} [silenceEndCallSeconds] - Silence before the call is ended outright (10-7200).
142
- * @property {number|null} [maxCallDurationSeconds] - Hard ceiling on one conversation (60-7200).
143
- * @property {boolean} [allowGreetingInterruption] - Whether a caller may talk over the greeting.
144
- * @property {string[]} [keyterms] - Words the transcriber is biased toward — names, jargon, unusual spellings.
145
- * @property {Object|null} [backgroundSound] - Ambient audio bed as `{ preset, volume }`; null = silence.
146
- * @property {AgentWorkflow|null} [workflow] - Conversation workflow graph. Voice channel only — sending one on webchat or sms is a 400. null = no workflow.
147
- */
148
-
149
- /**
150
- * A conversation workflow graph, in the voice runtime's own shape. Nodes and edges are keyed
151
- * maps rather than arrays: an edge names its endpoints by node key, and a node's `edge_order`
152
- * names its outgoing edges in the order their conditions are evaluated.
153
- *
154
- * Node bodies are deliberately not enumerated here. Node types are defined by the runtime and
155
- * new ones appear without an SDK release, so the SDK passes them through untouched. The API
156
- * validates the envelope — an entry point under the node key `start_node` typed `start` (the
157
- * runtime looks it up by that exact key), no second `start` node, at most 200 nodes, and every
158
- * edge endpoint naming a node that exists — and rejects a graph that fails any of those.
159
- * @typedef {Object} AgentWorkflow
160
- * @property {Object<string, Object>} nodes - Nodes keyed by node id. Each carries at least `type` and `position` ({ x, y }).
161
- * @property {Object<string, Object>} edges - Edges keyed by edge id. Each carries `source` and `target` node ids.
162
- * @property {Object<string, Object>} [subgraphs] - Nested subgraphs keyed by subgraph id.
163
- * @property {boolean} [prevent_subagent_loops] - Stop a subagent handing control back to one that already ran.
164
- */
165
-
166
- export class Agents {
167
- constructor(client, enableAdmin) {
168
- this.client = client;
169
- this.enableAdmin = enableAdmin;
170
- }
171
-
172
- /**
173
- * List the voices an agent can be configured to speak with.
174
- *
175
- * The catalog is platform-wide, not per-account, so this takes no scope. `voiceId` is the
176
- * value to set on a spoken channel's setting.
177
- * @async
178
- * @roles api, admin, developer, billing, user
179
- * @param {Object} [params] - The parameters for the request.
180
- * @param {RequestOptions} [params.options] - Additional options for the request.
181
- * @returns {Promise<SdkResponse<any>>} - The available voices, each as `{ voiceId, name, description, previewUrl, gender, accent, age, useCase, language }`.
182
- */
183
- async getAgentVoices({ options = {} } = {}) {
184
- return this.client("/agent/voices", { method: "GET", ...options });
185
- }
186
-
187
- /**
188
- * List the agent profiles under a group.
189
- * @async
190
- * @roles api, admin, developer, billing, user
191
- * @param {Object} params - The parameters for listing agent profiles.
192
- * @param {string} params.groupId - The group whose profiles to list (required).
193
- * @param {string} [params.subgroupId] - Narrow to the agents this subgroup can use — its own, plus the group-level agents shared with every subgroup.
194
- * @param {number} [params.page] - The page number for pagination.
195
- * @param {number} [params.limit] - The number of items per page for pagination.
196
- * @param {RequestOptions} [params.options] - Additional options for the request.
197
- * @throws {Error} Throws an error if the groupId parameter is missing.
198
- * @returns {Promise<SdkResponse<any>>} - The list of agent profiles returned from the server.
199
- */
200
- async getAgentProfiles({ groupId, subgroupId, page, limit, options = {} }) {
201
- this.client._require({ groupId });
202
- const queryString = this.client._getQueryString({ groupId, subgroupId, page, limit });
203
- return this.client(`/agent/profiles${queryString}`, { method: "GET", ...options });
204
- }
205
-
206
- /**
207
- * Get a single agent profile by id.
208
- * @async
209
- * @roles api, admin, developer, billing, user
210
- * @param {Object} params - The parameters for getting an agent profile.
211
- * @param {string} params.agentProfileId - The id of the agent profile to fetch.
212
- * @param {RequestOptions} [params.options] - Additional options for the request.
213
- * @throws {Error} Throws an error if the agentProfileId parameter is missing.
214
- * @returns {Promise<SdkResponse<any>>} - The agent profile returned from the server.
215
- */
216
- async getAgentProfile({ agentProfileId, options = {} }) {
217
- this.client._require({ agentProfileId });
218
- const safeId = encodeURIComponent(agentProfileId);
219
- return this.client(`/agent/profiles/${safeId}`, { method: "GET", ...options });
220
- }
221
-
222
- /**
223
- * Create a new agent profile.
224
- * @async
225
- * @roles api, admin, developer
226
- * @param {Object} params - The parameters for creating an agent profile (see CreateAgentProfileData typedef).
227
- * @param {CreateAgentProfileData} params.profileData - The data for the agent profile to create, including required fields groupId and name.
228
- * @param {RequestOptions} [params.options] - Additional options for the request.
229
- * @throws {Error} Throws an error if the profileData parameter is missing.
230
- * @returns {Promise<SdkResponse<any>>} - The created agent profile returned from the server.
231
- */
232
- async createAgentProfile({ profileData, options = {} }) {
233
- this.client._require({ profileData });
234
- return this.client(`/agent/profiles`, { method: "POST", body: profileData, ...options });
235
- }
236
-
237
- /**
238
- * Update an existing agent profile.
239
- * @async
240
- * @roles api, admin, developer
241
- * @param {Object} params - The parameters for updating an agent profile (see UpdateAgentProfileData typedef).
242
- * @param {string} params.id - The id of the agent profile to update.
243
- * @param {UpdateAgentProfileData} params.updateData - The data for the agent profile to update.
244
- * @param {RequestOptions} [params.options] - Additional options for the request.
245
- * @throws {Error} Throws an error if the id or updateData parameter is missing.
246
- * @returns {Promise<SdkResponse<any>>} - The updated agent profile returned from the server.
247
- */
248
- async updateAgentProfile({ id, updateData, options = {} }) {
249
- this.client._require({ id, updateData });
250
- const safeId = encodeURIComponent(id);
251
- return this.client(`/agent/profiles/${safeId}`, { method: "PUT", body: updateData, ...options });
252
- }
253
-
254
- /**
255
- * Permanently delete an agent profile by its id.
256
- *
257
- * Permanently deletes the agent, its channel settings, and any tools and knowledge scoped to it, plus their provider-side counterparts. Tools and knowledge shared across the account are untouched. Conversation records survive — a transcript outlives the agent that produced it.
258
- * @async
259
- * @roles api, admin, developer
260
- * @param {Object} params - The parameters for deleting an agent profile.
261
- * @param {string} params.id - The id of the agent profile to delete.
262
- * @param {RequestOptions} [params.options] - Additional options for the request.
263
- * @throws {Error} Throws an error if the id parameter is missing.
264
- * @returns {Promise<Object>} - The deleted agent profile, as it was.
265
- */
266
- async deleteAgentProfile({ id, options = {} }) {
267
- this.client._require({ id });
268
- const safeId = encodeURIComponent(id);
269
- return this.client(`/agent/profiles/${safeId}`, { method: "DELETE", ...options });
270
- }
271
-
272
- /**
273
- * Send a message to an agent and get its reply — the app-native conversation
274
- * endpoint (webchat / SMS). Omit conversationId to start a new conversation, or
275
- * pass one to continue an existing one. Runs the agent's LLM tool loop server-side
276
- * and returns the assistant's reply along with any tools it invoked.
277
- * @async
278
- * @roles api, admin, developer, billing, user
279
- * @param {Object} params - The parameters for sending a message.
280
- * @param {string} params.agentProfileId - The agent to talk to (required).
281
- * @param {string} params.channel - The channel: "webchat", "sms", or "voice" (required).
282
- * @param {string} params.message - The user's message (required).
283
- * @param {string} [params.conversationId] - Continue this conversation; omit to start a new one.
284
- * @param {string} [params.contactIdentifier] - The far-end identifier (webchat visitor id, sender number).
285
- * @param {RequestOptions} [params.options] - Additional options for the request.
286
- * @throws {Error} Throws an error if agentProfileId, channel, or message is missing.
287
- * @returns {Promise<SdkResponse<any>>} - `{ conversationId, conversationSessionId, reply, toolInvocations, ok }` from the server.
288
- */
289
- async sendAgentMessage({ agentProfileId, channel, message, conversationId, contactIdentifier, options = {} }) {
290
- this.client._require({ agentProfileId, channel, message });
291
- const body = { agentProfileId, channel, message };
292
- if (conversationId !== undefined && conversationId !== null) body.conversationId = conversationId;
293
- if (contactIdentifier !== undefined && contactIdentifier !== null) body.contactIdentifier = contactIdentifier;
294
- return this.client(`/agent/messages`, { method: "POST", body, ...options });
295
- }
296
-
297
- /**
298
- * Start a conversation without sending a message.
299
- *
300
- * The counterpart to `sendAgentMessage` for callers that run the model themselves —
301
- * a voice runtime, or your own LLM. Those record what was said; `sendAgentMessage`
302
- * decides it. Both write the same conversation records.
303
- * @async
304
- * @roles api, admin, developer, billing, user
305
- * @param {Object} params - The parameters for starting a conversation.
306
- * @param {string} params.agentProfileId - The agent this conversation belongs to (required).
307
- * @param {string} params.channel - The channel: "webchat", "sms", or "voice" (required).
308
- * @param {string} [params.contactIdentifier] - The far-end identifier (visitor id, caller number).
309
- * @param {string} [params.callId] - Telephony call id, for the voice channel.
310
- * @param {Object} [params.metadata] - Arbitrary metadata stored with the conversation.
311
- * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
312
- * @throws {Error} Throws an error if agentProfileId or channel is missing.
313
- * @returns {Promise<Object>} - The created conversation, including `conversationId` and `conversationSessionId`.
314
- */
315
- async startConversation({ agentProfileId, channel, contactIdentifier, callId, metadata, options = {} }) {
316
- this.client._require({ agentProfileId, channel });
317
- const body = { agentProfileId, channel };
318
- if (contactIdentifier !== undefined && contactIdentifier !== null) body.contactIdentifier = contactIdentifier;
319
- if (callId !== undefined && callId !== null) body.callId = callId;
320
- if (metadata !== undefined && metadata !== null) body.metadata = metadata;
321
- return this.client(`/agent/conversations`, { method: "POST", body, ...options });
322
- }
323
-
324
- /**
325
- * Read one conversation with a page of its messages, in order.
326
- *
327
- * Paged rather than whole: a transcript has no natural ceiling. Omitting `limit` gives 100
328
- * messages, not all of them.
329
- * @async
330
- * @roles api, admin, developer, billing, user
331
- * @param {Object} params - The parameters for reading a conversation.
332
- * @param {string} params.conversationId - The conversation to read (required).
333
- * @param {number} [params.page] - Page number; defaults to 1.
334
- * @param {number} [params.limit] - Messages per page; defaults to 100, capped at 500.
335
- * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
336
- * @throws {Error} Throws an error if the conversationId parameter is missing.
337
- * @returns {Promise<Object>} - A one-element array with the conversation and its `messages`.
338
- */
339
- async getConversation({ conversationId, page, limit, options = {} }) {
340
- this.client._require({ conversationId });
341
- const safeId = encodeURIComponent(conversationId);
342
- const queryString = this.client._getQueryString({ page, limit });
343
- return this.client(`/agent/conversations/${safeId}${queryString}`, { method: "GET", ...options });
344
- }
345
-
346
- /**
347
- * Append one message to a conversation.
348
- *
349
- * Records a turn rather than generating one, so `role` is explicit — an assistant turn
350
- * your own runtime produced is the normal case here. `content` is optional so a
351
- * tool-only turn needs no prose.
352
- * @async
353
- * @roles api, admin, developer, billing, user
354
- * @param {Object} params - The parameters for appending a message.
355
- * @param {string} params.conversationId - The conversation to append to (required).
356
- * @param {string} params.role - "user", "assistant", "system", or "tool" (required).
357
- * @param {string} [params.content] - What was said.
358
- * @param {Array<Object>} [params.toolCalls] - Tools invoked on this turn.
359
- * @param {Array<Object>} [params.toolResults] - Their results.
360
- * @param {number} [params.ttfbMs] - Time to first byte/audio, in milliseconds.
361
- * @param {number} [params.latencyMs] - Total turn latency, in milliseconds.
362
- * @param {boolean} [params.bargeInOccurred] - Whether the far end talked over this turn.
363
- * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
364
- * @throws {Error} Throws an error if conversationId or role is missing.
365
- * @returns {Promise<Object>} - The persisted message.
366
- */
367
- async appendConversationMessage({ conversationId, role, content, toolCalls, toolResults, ttfbMs, latencyMs, bargeInOccurred, options = {} }) {
368
- this.client._require({ conversationId, role });
369
- const safeId = encodeURIComponent(conversationId);
370
- const body = { role };
371
- if (content !== undefined && content !== null) body.content = content;
372
- if (toolCalls !== undefined && toolCalls !== null) body.toolCalls = toolCalls;
373
- if (toolResults !== undefined && toolResults !== null) body.toolResults = toolResults;
374
- if (ttfbMs !== undefined && ttfbMs !== null) body.ttfbMs = ttfbMs;
375
- if (latencyMs !== undefined && latencyMs !== null) body.latencyMs = latencyMs;
376
- if (bargeInOccurred !== undefined && bargeInOccurred !== null) body.bargeInOccurred = bargeInOccurred;
377
- return this.client(`/agent/conversations/${safeId}/messages`, { method: "POST", body, ...options });
378
- }
379
-
380
- /**
381
- * End a conversation, closing its open session.
382
- *
383
- * `status` records HOW it ended and cannot be recovered afterwards, so pass the one that
384
- * actually happened. Ending an already-ended conversation is a no-op, so a retry after a
385
- * dropped connection cannot overwrite it.
386
- * @async
387
- * @roles api, admin, developer, billing, user
388
- * @param {Object} params - The parameters for ending a conversation.
389
- * @param {string} params.conversationId - The conversation to end (required).
390
- * @param {string} [params.status] - "completed", "escalated", or "abandoned" (defaults to "completed").
391
- * @param {Object} [params.metadata] - Metadata merged onto the conversation.
392
- * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
393
- * @throws {Error} Throws an error if the conversationId parameter is missing.
394
- * @returns {Promise<Object>} - The ended conversation.
395
- */
396
- async endConversation({ conversationId, status, metadata, options = {} }) {
397
- this.client._require({ conversationId });
398
- const safeId = encodeURIComponent(conversationId);
399
- const body = {};
400
- if (status !== undefined && status !== null) body.status = status;
401
- if (metadata !== undefined && metadata !== null) body.metadata = metadata;
402
- return this.client(`/agent/conversations/${safeId}`, { method: "PUT", body, ...options });
403
- }
404
-
405
- /**
406
- * List an agent's per-channel settings (the tools enabled per channel, whether the
407
- * channel is on, and any channel-specific prompt/greeting).
408
- * @async
409
- * @roles api, admin, developer, billing, user
410
- * @param {Object} params - The parameters for listing channel settings.
411
- * @param {string} params.agentProfileId - The agent whose channel settings to list.
412
- * @param {RequestOptions} [params.options] - Additional options for the request.
413
- * @throws {Error} Throws an error if the agentProfileId parameter is missing.
414
- * @returns {Promise<SdkResponse<any>>} - The agent's channel settings returned from the server.
415
- */
416
- async getAgentChannelSettings({ agentProfileId, options = {} }) {
417
- this.client._require({ agentProfileId });
418
- const safeId = encodeURIComponent(agentProfileId);
419
- return this.client(`/agent/profiles/${safeId}/channels`, { method: "GET", ...options });
420
- }
421
-
422
- /**
423
- * Get a single per-channel setting for an agent.
424
- * @async
425
- * @roles api, admin, developer, billing, user
426
- * @param {Object} params - The parameters for getting a channel setting.
427
- * @param {string} params.agentProfileId - The agent the setting belongs to.
428
- * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
429
- * @param {RequestOptions} [params.options] - Additional options for the request.
430
- * @throws {Error} Throws an error if agentProfileId or channel is missing.
431
- * @returns {Promise<SdkResponse<any>>} - The channel setting returned from the server.
432
- */
433
- async getAgentChannelSetting({ agentProfileId, channel, options = {} }) {
434
- this.client._require({ agentProfileId, channel });
435
- const safeId = encodeURIComponent(agentProfileId);
436
- const safeChannel = encodeURIComponent(channel);
437
- return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "GET", ...options });
438
- }
439
-
440
- /**
441
- * Create or update (upsert) an agent's per-channel setting. One row per (agent, channel);
442
- * the channel is taken from the path, the fields from settingData.
443
- * @async
444
- * @roles api, admin, developer
445
- * @param {Object} params - The parameters for the upsert.
446
- * @param {string} params.agentProfileId - The agent the setting belongs to.
447
- * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
448
- * @param {AgentChannelSettingData} [params.settingData] - The fields to set.
449
- * @param {RequestOptions} [params.options] - Additional options for the request.
450
- * @throws {Error} Throws an error if agentProfileId or channel is missing.
451
- * @returns {Promise<SdkResponse<any>>} - The created or updated channel setting returned from the server.
452
- */
453
- async upsertAgentChannelSetting({ agentProfileId, channel, settingData = {}, options = {} }) {
454
- this.client._require({ agentProfileId, channel });
455
- const safeId = encodeURIComponent(agentProfileId);
456
- const safeChannel = encodeURIComponent(channel);
457
- return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "PUT", body: settingData, ...options });
458
- }
459
-
460
- /**
461
- * Delete an agent's per-channel setting.
462
- * @async
463
- * @roles api, admin, developer
464
- * @param {Object} params - The parameters for the delete.
465
- * @param {string} params.agentProfileId - The agent the setting belongs to.
466
- * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
467
- * @param {RequestOptions} [params.options] - Additional options for the request.
468
- * @throws {Error} Throws an error if agentProfileId or channel is missing.
469
- * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
470
- */
471
- async deleteAgentChannelSetting({ agentProfileId, channel, options = {} }) {
472
- this.client._require({ agentProfileId, channel });
473
- const safeId = encodeURIComponent(agentProfileId);
474
- const safeChannel = encodeURIComponent(channel);
475
- return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "DELETE", ...options });
476
- }
477
-
478
- /**
479
- * List a group-level agent's deployments to subgroups.
480
- * @async
481
- * @roles api, admin, developer, billing, user
482
- * @param {Object} params - The parameters for listing deployments.
483
- * @param {string} params.agentProfileId - The agent whose deployments to list.
484
- * @param {RequestOptions} [params.options] - Additional options for the request.
485
- * @throws {Error} Throws an error if the agentProfileId parameter is missing.
486
- * @returns {Promise<SdkResponse<AgentDeployment[]>>} - The agent's deployments returned from the server.
487
- */
488
- async getAgentDeployments({ agentProfileId, options = {} }) {
489
- this.client._require({ agentProfileId });
490
- const safeId = encodeURIComponent(agentProfileId);
491
- return this.client(`/agent/profiles/${safeId}/deployments`, { method: "GET", ...options });
492
- }
493
-
494
- /**
495
- * Deploy a group-level agent to a subgroup, or change that deployment (upsert). One row per
496
- * (agent, subgroup); the subgroup is taken from the path, the fields from deploymentData.
497
- * @async
498
- * @roles api, admin, developer
499
- * @param {Object} params - The parameters for the upsert.
500
- * @param {string} params.agentProfileId - The agent to deploy.
501
- * @param {string} params.subgroupId - The subgroup to deploy to (at least 8 characters, starts with 'S').
502
- * @param {AgentDeploymentData} [params.deploymentData] - The fields to set.
503
- * @param {RequestOptions} [params.options] - Additional options for the request.
504
- * @throws {Error} Throws an error if agentProfileId or subgroupId is missing.
505
- * @returns {Promise<SdkResponse<AgentDeployment>>} - The created or updated deployment returned from the server.
506
- */
507
- async upsertAgentDeployment({ agentProfileId, subgroupId, deploymentData = {}, options = {} }) {
508
- this.client._require({ agentProfileId, subgroupId });
509
- const safeId = encodeURIComponent(agentProfileId);
510
- const safeSubgroupId = encodeURIComponent(subgroupId);
511
- return this.client(`/agent/profiles/${safeId}/deployments/${safeSubgroupId}`, { method: "PUT", body: deploymentData, ...options });
512
- }
513
-
514
- /**
515
- * Remove an agent's deployment from a subgroup.
516
- * @async
517
- * @roles api, admin, developer
518
- * @param {Object} params - The parameters for the delete.
519
- * @param {string} params.agentProfileId - The deployed agent.
520
- * @param {string} params.subgroupId - The subgroup to remove the deployment from.
521
- * @param {RequestOptions} [params.options] - Additional options for the request.
522
- * @throws {Error} Throws an error if agentProfileId or subgroupId is missing.
523
- * @returns {Promise<SdkResponse<AgentDeployment>>} - The removed deployment returned from the server.
524
- */
525
- async deleteAgentDeployment({ agentProfileId, subgroupId, options = {} }) {
526
- this.client._require({ agentProfileId, subgroupId });
527
- const safeId = encodeURIComponent(agentProfileId);
528
- const safeSubgroupId = encodeURIComponent(subgroupId);
529
- return this.client(`/agent/profiles/${safeId}/deployments/${safeSubgroupId}`, { method: "DELETE", ...options });
530
- }
531
-
532
- /**
533
- * List the endpoint bindings (which agent answers which number) in a group.
534
- * @async
535
- * @roles api, admin, developer, billing, user
536
- * @param {Object} params - The parameters for listing endpoint bindings.
537
- * @param {string} params.groupId - The group whose bindings to list (required).
538
- * @param {string} [params.subgroupId] - Narrow to one subgroup's bindings.
539
- * @param {string} [params.agentProfileId] - Narrow to one agent's bindings.
540
- * @param {string} [params.channel] - Narrow to one channel ("sms").
541
- * @param {RequestOptions} [params.options] - Additional options for the request.
542
- * @throws {Error} Throws an error if the groupId parameter is missing.
543
- * @returns {Promise<SdkResponse<AgentEndpoint[]>>} - The bindings, ordered by number, returned from the server.
544
- */
545
- async getAgentEndpoints({ groupId, subgroupId, agentProfileId, channel, options = {} }) {
546
- this.client._require({ groupId });
547
- const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, channel });
548
- return this.client(`/agent/endpoints${queryString}`, { method: "GET", ...options });
549
- }
550
-
551
- /**
552
- * Assign an agent to answer a number (upsert keyed by channel + number). Assigning again
553
- * replaces the previous agent, so a number has one agent per channel. v1 binds SMS numbers only.
554
- * @async
555
- * @roles api, admin, developer
556
- * @param {Object} params - The parameters for the upsert.
557
- * @param {string} params.channel - The channel to bind; must be "sms".
558
- * @param {string} params.endpointValue - The phone number: 10 to 15 digits, country code included, no "+".
559
- * @param {AgentEndpointData} params.endpointData - The agent to assign and its answer mode.
560
- * @param {RequestOptions} [params.options] - Additional options for the request.
561
- * @throws {Error} Throws an error if channel, endpointValue, or endpointData.agentProfileId is missing.
562
- * @returns {Promise<SdkResponse<AgentEndpoint>>} - The created or updated binding returned from the server.
563
- */
564
- async upsertAgentEndpoint({ channel, endpointValue, endpointData, options = {} }) {
565
- this.client._require({ channel, endpointValue, agentProfileId: endpointData?.agentProfileId });
566
- const safeChannel = encodeURIComponent(channel);
567
- const safeEndpointValue = encodeURIComponent(endpointValue);
568
- return this.client(`/agent/endpoints/${safeChannel}/${safeEndpointValue}`, { method: "PUT", body: endpointData, ...options });
569
- }
570
-
571
- /**
572
- * Remove the agent assigned to a number.
573
- * @async
574
- * @roles api, admin, developer
575
- * @param {Object} params - The parameters for the delete.
576
- * @param {string} params.channel - The bound channel; must be "sms".
577
- * @param {string} params.endpointValue - The phone number: digits only, country code included, no "+".
578
- * @param {RequestOptions} [params.options] - Additional options for the request.
579
- * @throws {Error} Throws an error if channel or endpointValue is missing.
580
- * @returns {Promise<SdkResponse<AgentEndpoint>>} - The removed binding returned from the server.
581
- */
582
- async deleteAgentEndpoint({ channel, endpointValue, options = {} }) {
583
- this.client._require({ channel, endpointValue });
584
- const safeChannel = encodeURIComponent(channel);
585
- const safeEndpointValue = encodeURIComponent(endpointValue);
586
- return this.client(`/agent/endpoints/${safeChannel}/${safeEndpointValue}`, { method: "DELETE", ...options });
587
- }
588
-
589
- /**
590
- * List held agent replies (the Pending Replies queue) in a group, newest first.
591
- * @async
592
- * @roles api, admin, developer, billing, user
593
- * @param {Object} params - The parameters for listing drafts.
594
- * @param {string} params.groupId - The group whose drafts to list (required).
595
- * @param {string} [params.subgroupId] - Narrow to one subgroup.
596
- * @param {string} [params.agentProfileId] - Narrow to one agent.
597
- * @param {string} [params.status] - Narrow to one status, e.g. "pending".
598
- * @param {number} [params.page] - Page number for pagination.
599
- * @param {number} [params.limit] - Items per page (default 25, max 500).
600
- * @param {RequestOptions} [params.options] - Additional options for the request.
601
- * @throws {Error} Throws an error if the groupId parameter is missing.
602
- * @returns {Promise<SdkResponse<AgentReplyDraft[]>>} - The drafts returned from the server.
603
- */
604
- async getAgentReplyDrafts({ groupId, subgroupId, agentProfileId, status, page, limit, options = {} }) {
605
- this.client._require({ groupId });
606
- const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, status, page, limit });
607
- return this.client(`/agent/drafts${queryString}`, { method: "GET", ...options });
608
- }
609
-
610
- /**
611
- * Approve a held agent reply and send it from the agent's number, optionally with edited text.
612
- * It goes through the normal SMS send path, so opt-out and billing apply; the draft comes back
613
- * "failed" when the send path accepted nothing. A draft that is no longer pending returns 409.
614
- * @async
615
- * @roles api, admin, developer, billing, user
616
- * @param {Object} params - The parameters for the approval.
617
- * @param {string} params.agentReplyDraftId - The draft to approve.
618
- * @param {string} [params.text] - Replacement text when a person edited the reply.
619
- * @param {RequestOptions} [params.options] - Additional options for the request.
620
- * @throws {Error} Throws an error if the agentReplyDraftId parameter is missing.
621
- * @returns {Promise<SdkResponse<AgentReplyDraft>>} - The draft, now sent (or failed), returned from the server.
622
- */
623
- async approveAgentReplyDraft({ agentReplyDraftId, text, options = {} }) {
624
- this.client._require({ agentReplyDraftId });
625
- const safeId = encodeURIComponent(agentReplyDraftId);
626
- const body = text === undefined ? {} : { text };
627
- return this.client(`/agent/drafts/${safeId}/approve`, { method: "POST", body, ...options });
628
- }
629
-
630
- /**
631
- * Reject a held agent reply so it is never sent. A draft that is no longer pending returns 409.
632
- * @async
633
- * @roles api, admin, developer, billing, user
634
- * @param {Object} params - The parameters for the rejection.
635
- * @param {string} params.agentReplyDraftId - The draft to reject.
636
- * @param {RequestOptions} [params.options] - Additional options for the request.
637
- * @throws {Error} Throws an error if the agentReplyDraftId parameter is missing.
638
- * @returns {Promise<SdkResponse<AgentReplyDraft>>} - The rejected draft returned from the server.
639
- */
640
- async rejectAgentReplyDraft({ agentReplyDraftId, options = {} }) {
641
- this.client._require({ agentReplyDraftId });
642
- const safeId = encodeURIComponent(agentReplyDraftId);
643
- return this.client(`/agent/drafts/${safeId}/reject`, { method: "POST", ...options });
644
- }
645
-
646
- /**
647
- * Claim a held agent reply for delivery through your own channel instead of Signal House's send path.
648
- * Nothing is sent: the draft becomes "sending" with `deliveredBy: "external"`, `sentText` and a new
649
- * `claimId` set, and you then report the outcome with `completeAgentReplyDraft` or `releaseAgentReplyDraft`,
650
- * passing that `claimId`. The claim
651
- * means two approvals can never both deliver. A draft that is no longer pending returns 409; one whose
652
- * number has left its subgroup returns 400 and is closed as failed.
653
- * @async
654
- * @roles api, admin, developer, billing, user
655
- * @param {Object} params - The parameters for the claim.
656
- * @param {string} params.agentReplyDraftId - The draft to claim.
657
- * @param {string} [params.text] - Replacement text when a person edited the reply.
658
- * @param {RequestOptions} [params.options] - Additional options for the request.
659
- * @throws {Error} Throws an error if the agentReplyDraftId parameter is missing.
660
- * @returns {Promise<SdkResponse<AgentReplyDraft>>} - The claimed draft returned from the server.
661
- */
662
- async claimAgentReplyDraft({ agentReplyDraftId, text, options = {} }) {
663
- this.client._require({ agentReplyDraftId });
664
- const safeId = encodeURIComponent(agentReplyDraftId);
665
- const body = text === undefined ? {} : { text };
666
- return this.client(`/agent/drafts/${safeId}/claim`, { method: "POST", body, ...options });
667
- }
668
-
669
- /**
670
- * Mark a claimed agent reply sent once your channel accepted it. Only the claim named by `claimId` can be
671
- * completed (anything else returns 409). It is also accepted after an unfinished claim was closed as
672
- * "failed" with `failureReason: "delivery_unconfirmed"`, which it turns into "sent".
673
- * @async
674
- * @roles api, admin, developer, billing, user
675
- * @param {Object} params - The parameters for the completion.
676
- * @param {string} params.agentReplyDraftId - The claimed draft.
677
- * @param {string} params.claimId - The claim being completed, as returned by `claimAgentReplyDraft`.
678
- * @param {string} [params.externalMessageId] - Your channel's id for the sent message, stored as `sentMessageId`.
679
- * @param {RequestOptions} [params.options] - Additional options for the request.
680
- * @throws {Error} Throws an error if the agentReplyDraftId or claimId parameter is missing.
681
- * @returns {Promise<SdkResponse<AgentReplyDraft>>} - The draft, now sent, returned from the server.
682
- */
683
- async completeAgentReplyDraft({ agentReplyDraftId, claimId, externalMessageId, options = {} }) {
684
- this.client._require({ agentReplyDraftId, claimId });
685
- const safeId = encodeURIComponent(agentReplyDraftId);
686
- const body = externalMessageId === undefined ? { claimId } : { claimId, externalMessageId };
687
- return this.client(`/agent/drafts/${safeId}/complete`, { method: "POST", body, ...options });
688
- }
689
-
690
- /**
691
- * Give back a claim whose reply certainly did not go out: the draft returns to "pending", or with
692
- * `permanent` is closed as "failed". If you cannot tell whether it went out, do not release it; a claim
693
- * left unfinished for 30 minutes is closed as failed with `failureReason: "delivery_unconfirmed"`.
694
- * Only the claim named by `claimId` can be released; anything else returns 409.
695
- * @async
696
- * @roles api, admin, developer, billing, user
697
- * @param {Object} params - The parameters for the release.
698
- * @param {string} params.agentReplyDraftId - The claimed draft.
699
- * @param {string} params.claimId - The claim being released, as returned by `claimAgentReplyDraft`.
700
- * @param {boolean} [params.permanent] - True closes the draft as failed instead of returning it to pending.
701
- * @param {RequestOptions} [params.options] - Additional options for the request.
702
- * @throws {Error} Throws an error if the agentReplyDraftId or claimId parameter is missing.
703
- * @returns {Promise<SdkResponse<AgentReplyDraft>>} - The draft, pending again or failed, returned from the server.
704
- */
705
- async releaseAgentReplyDraft({ agentReplyDraftId, claimId, permanent, options = {} }) {
706
- this.client._require({ agentReplyDraftId, claimId });
707
- const safeId = encodeURIComponent(agentReplyDraftId);
708
- const body = permanent === undefined ? { claimId } : { claimId, permanent };
709
- return this.client(`/agent/drafts/${safeId}/release`, { method: "POST", body, ...options });
710
- }
711
-
712
- /**
713
- * Publish an agent profile, setting its `publishStatus` to "published" and stamping
714
- * `publishedAt`. The server rejects the call with 400 when the agent has no enabled
715
- * deployment, and with 409 when the agent is inactive.
716
- * @async
717
- * @roles api, admin, developer
718
- * @param {Object} params - The parameters for publishing.
719
- * @param {string} params.agentProfileId - The agent profile to publish.
720
- * @param {RequestOptions} [params.options] - Additional options for the request.
721
- * @throws {Error} Throws an error if the agentProfileId parameter is missing.
722
- * @returns {Promise<SdkResponse<AgentProfile>>} - The published agent profile returned from the server.
723
- */
724
- async publishAgentProfile({ agentProfileId, options = {} }) {
725
- this.client._require({ agentProfileId });
726
- const safeId = encodeURIComponent(agentProfileId);
727
- return this.client(`/agent/profiles/${safeId}/publish`, { method: "POST", ...options });
728
- }
729
-
730
- /**
731
- * Return an agent profile to draft, setting its `publishStatus` to "draft".
732
- * @async
733
- * @roles api, admin, developer
734
- * @param {Object} params - The parameters for unpublishing.
735
- * @param {string} params.agentProfileId - The agent profile to unpublish.
736
- * @param {RequestOptions} [params.options] - Additional options for the request.
737
- * @throws {Error} Throws an error if the agentProfileId parameter is missing.
738
- * @returns {Promise<SdkResponse<AgentProfile>>} - The unpublished agent profile returned from the server.
739
- */
740
- async unpublishAgentProfile({ agentProfileId, options = {} }) {
741
- this.client._require({ agentProfileId });
742
- const safeId = encodeURIComponent(agentProfileId);
743
- return this.client(`/agent/profiles/${safeId}/unpublish`, { method: "POST", ...options });
744
- }
745
-
746
- /**
747
- * Read the tenant AI settings for a scope (group, or a subgroup within it) — brand, tone,
748
- * timezone, business hours, and after-hours message. Returns the scope's own row only (no
749
- * group-level fallback).
750
- * @async
751
- * @roles api, admin, developer, billing, user
752
- * @param {Object} params - The parameters for reading tenant settings.
753
- * @param {string} params.groupId - The group (required).
754
- * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
755
- * @param {RequestOptions} [params.options] - Additional options for the request.
756
- * @throws {Error} Throws an error if the groupId parameter is missing.
757
- * @returns {Promise<SdkResponse<any>>} - The tenant settings returned from the server.
758
- */
759
- async getTenantAiSettings({ groupId, subgroupId, options = {} }) {
760
- this.client._require({ groupId });
761
- const queryString = this.client._getQueryString({ groupId, subgroupId });
762
- return this.client(`/agent/tenant-settings${queryString}`, { method: "GET", ...options });
763
- }
764
-
765
- /**
766
- * Create or update (upsert) the tenant AI settings for a scope. The scope is identified by
767
- * the query params; the body carries the settings fields.
768
- * @async
769
- * @roles api, admin, developer
770
- * @param {Object} params - The parameters for the upsert.
771
- * @param {string} params.groupId - The group (required).
772
- * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
773
- * @param {Object} [params.settingsData] - Fields to set: brandName (string), tone (string), timezone (IANA string), businessHours (array of {day, closed, open, close}), afterHoursMessage (string).
774
- * @param {RequestOptions} [params.options] - Additional options for the request.
775
- * @throws {Error} Throws an error if the groupId parameter is missing.
776
- * @returns {Promise<SdkResponse<any>>} - The created or updated tenant settings returned from the server.
777
- */
778
- async upsertTenantAiSettings({ groupId, subgroupId, settingsData = {}, options = {} }) {
779
- this.client._require({ groupId });
780
- const queryString = this.client._getQueryString({ groupId, subgroupId });
781
- return this.client(`/agent/tenant-settings${queryString}`, { method: "PUT", body: settingsData, ...options });
782
- }
783
-
784
- /**
785
- * Delete the tenant AI settings for a scope.
786
- * @async
787
- * @roles api, admin, developer
788
- * @param {Object} params - The parameters for the delete.
789
- * @param {string} params.groupId - The group (required).
790
- * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
791
- * @param {RequestOptions} [params.options] - Additional options for the request.
792
- * @throws {Error} Throws an error if the groupId parameter is missing.
793
- * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
794
- */
795
- async deleteTenantAiSettings({ groupId, subgroupId, options = {} }) {
796
- this.client._require({ groupId });
797
- const queryString = this.client._getQueryString({ groupId, subgroupId });
798
- return this.client(`/agent/tenant-settings${queryString}`, { method: "DELETE", ...options });
799
- }
800
-
801
- /**
802
- * List the knowledge-base items an agent can answer from (RAG), scoped to a group and
803
- * optionally narrowed to a subgroup and/or a single agent.
804
- * @async
805
- * @roles api, admin, developer, billing, user
806
- * @param {Object} params - The parameters for listing knowledge items.
807
- * @param {string} params.groupId - The group whose knowledge to list (required).
808
- * @param {string} [params.subgroupId] - Narrow to a subgroup.
809
- * @param {string} [params.agentProfileId] - Narrow to one agent.
810
- * @param {number} [params.page] - Page number (1-based) for pagination.
811
- * @param {number} [params.limit] - Items per page (max 100; server default 25).
812
- * @param {RequestOptions} [params.options] - Additional options for the request.
813
- * @throws {Error} Throws an error if the groupId parameter is missing.
814
- * @returns {Promise<SdkResponse<any>>} - The knowledge items returned from the server.
815
- */
816
- async getKnowledgeItems({ groupId, subgroupId, agentProfileId, page, limit, options = {} }) {
817
- this.client._require({ groupId });
818
- const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, page, limit });
819
- return this.client(`/agent/knowledge${queryString}`, { method: "GET", ...options });
820
- }
821
-
822
- /**
823
- * Get a single knowledge item by id.
824
- * @async
825
- * @roles api, admin, developer, billing, user
826
- * @param {Object} params - The parameters for getting a knowledge item.
827
- * @param {string} params.knowledgeItemId - The id of the knowledge item to fetch.
828
- * @param {RequestOptions} [params.options] - Additional options for the request.
829
- * @throws {Error} Throws an error if the knowledgeItemId parameter is missing.
830
- * @returns {Promise<SdkResponse<any>>} - The knowledge item returned from the server.
831
- */
832
- async getKnowledgeItem({ knowledgeItemId, options = {} }) {
833
- this.client._require({ knowledgeItemId });
834
- const safeId = encodeURIComponent(knowledgeItemId);
835
- return this.client(`/agent/knowledge/${safeId}`, { method: "GET", ...options });
836
- }
837
-
838
- /**
839
- * Create a knowledge item. The raw `text` is stored and Atlas Vector Search owns the
840
- * embedding — there is no embedding to supply.
841
- * @async
842
- * @roles api, admin, developer
843
- * @param {Object} params - The parameters for creating a knowledge item.
844
- * @param {Object} params.itemData - The knowledge fields. Required: groupId (starts with 'G'), text.
845
- * Optional: subgroupId (starts with 'S', nullable), agentProfileId
846
- * (nullable = shared across the tenant's agents), title, source
847
- * ("manual" | "url" | "document" | "import"), enabled (boolean), metadata (object|null).
848
- * @param {RequestOptions} [params.options] - Additional options for the request.
849
- * @throws {Error} Throws an error if the itemData parameter is missing.
850
- * @returns {Promise<SdkResponse<any>>} - The created knowledge item returned from the server.
851
- */
852
- async createKnowledgeItem({ itemData, options = {} }) {
853
- this.client._require({ itemData });
854
- return this.client(`/agent/knowledge`, { method: "POST", body: itemData, ...options });
855
- }
856
-
857
- /**
858
- * Update a knowledge item. The item's scope (group/subgroup/agent) is immutable and
859
- * cannot be changed.
860
- * @async
861
- * @roles api, admin, developer
862
- * @param {Object} params - The parameters for updating a knowledge item.
863
- * @param {string} params.id - The id of the knowledge item to update.
864
- * @param {Object} params.updateData - The fields to update: title, text, source, enabled, metadata.
865
- * @param {RequestOptions} [params.options] - Additional options for the request.
866
- * @throws {Error} Throws an error if the id or updateData parameter is missing.
867
- * @returns {Promise<SdkResponse<any>>} - The updated knowledge item returned from the server.
868
- */
869
- async updateKnowledgeItem({ id, updateData, options = {} }) {
870
- this.client._require({ id, updateData });
871
- const safeId = encodeURIComponent(id);
872
- return this.client(`/agent/knowledge/${safeId}`, { method: "PUT", body: updateData, ...options });
873
- }
874
-
875
- /**
876
- * Delete a knowledge item by its id.
877
- * @async
878
- * @roles api, admin, developer
879
- * @param {Object} params - The parameters for deleting a knowledge item.
880
- * @param {string} params.id - The id of the knowledge item to delete.
881
- * @param {RequestOptions} [params.options] - Additional options for the request.
882
- * @throws {Error} Throws an error if the id parameter is missing.
883
- * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
884
- */
885
- async deleteKnowledgeItem({ id, options = {} }) {
886
- this.client._require({ id });
887
- const safeId = encodeURIComponent(id);
888
- return this.client(`/agent/knowledge/${safeId}`, { method: "DELETE", ...options });
889
- }
890
-
891
- /**
892
- * List the tools defined under a group — custom webhook tools, configured built-ins, and
893
- * (future) MCP. `webhookAuth` secrets are redacted in the response.
894
- * @async
895
- * @roles api, admin, developer, billing, user
896
- * @param {Object} params - The parameters for listing tools.
897
- * @param {string} params.groupId - The group whose tools to list (required).
898
- * @param {string} [params.subgroupId] - Narrow to a subgroup.
899
- * @param {string} [params.agentProfileId] - Narrow to one agent.
900
- * @param {string} [params.type] - Narrow to a tool type: "builtin", "webhook", or "mcp".
901
- * @param {number} [params.page] - Page number (1-based) for pagination.
902
- * @param {number} [params.limit] - Items per page (max 100; server default 25).
903
- * @param {RequestOptions} [params.options] - Additional options for the request.
904
- * @throws {Error} Throws an error if the groupId parameter is missing.
905
- * @returns {Promise<SdkResponse<any>>} - The tools returned from the server (secrets redacted).
906
- */
907
- async getAgentTools({ groupId, subgroupId, agentProfileId, type, page, limit, options = {} }) {
908
- this.client._require({ groupId });
909
- const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, type, page, limit });
910
- return this.client(`/agent/tools${queryString}`, { method: "GET", ...options });
911
- }
912
-
913
- /**
914
- * Get a single agent tool by id. `webhookAuth` secrets are redacted in the response.
915
- * @async
916
- * @roles api, admin, developer, billing, user
917
- * @param {Object} params - The parameters for getting a tool.
918
- * @param {string} params.agentToolId - The id of the tool to fetch.
919
- * @param {RequestOptions} [params.options] - Additional options for the request.
920
- * @throws {Error} Throws an error if the agentToolId parameter is missing.
921
- * @returns {Promise<SdkResponse<any>>} - The tool returned from the server (secrets redacted).
922
- */
923
- async getAgentTool({ agentToolId, options = {} }) {
924
- this.client._require({ agentToolId });
925
- const safeId = encodeURIComponent(agentToolId);
926
- return this.client(`/agent/tools/${safeId}`, { method: "GET", ...options });
927
- }
928
-
929
- /**
930
- * Create an agent tool. For a webhook tool, `webhookUrl` must be an https URL that does not
931
- * target a private/internal address (rejected otherwise). `webhookAuth` is stored and never
932
- * echoed back.
933
- * @async
934
- * @roles api, admin, developer
935
- * @param {Object} params - The parameters for creating a tool.
936
- * @param {Object} params.toolData - The tool fields. Required: groupId (starts with 'G'), name, description.
937
- * Type-specific: type ("builtin" | "webhook" | "mcp"); webhook → webhookUrl, builtin →
938
- * builtinKey, mcp → mcpServerUrl. Optional: subgroupId, agentProfileId (nullable = shared),
939
- * parametersSchema, config, channels (string[]), enabled (boolean), and webhookAuth —
940
- * which MUST be `{ headers?: { [name]: value }, signingSecret?: string }` (any other shape,
941
- * e.g. `{ header, value }`, is rejected with a 400). `headers` are sent verbatim on every
942
- * call (reserved/framing and `x-signalhouse-*` names are rejected); `signingSecret` makes us
943
- * send `X-SignalHouse-Signature: sha256=HMAC-SHA256(`${X-SignalHouse-Timestamp}.${rawBody}`)`
944
- * so you can verify the call and reject replays. Stored, never returned.
945
- * @param {RequestOptions} [params.options] - Additional options for the request.
946
- * @throws {Error} Throws an error if the toolData parameter is missing.
947
- * @returns {Promise<SdkResponse<any>>} - The created tool returned from the server (secrets redacted).
948
- */
949
- async createAgentTool({ toolData, options = {} }) {
950
- this.client._require({ toolData });
951
- return this.client(`/agent/tools`, { method: "POST", body: toolData, ...options });
952
- }
953
-
954
- /**
955
- * Update an agent tool. The tool's scope (group/subgroup/agent) is immutable. A supplied
956
- * `webhookUrl` is SSRF-checked.
957
- * @async
958
- * @roles api, admin, developer
959
- * @param {Object} params - The parameters for updating a tool.
960
- * @param {string} params.id - The id of the tool to update.
961
- * @param {Object} params.updateData - The fields to update: name, description, type, builtinKey, parametersSchema, config, webhookUrl, webhookAuth, mcpServerUrl, channels, enabled.
962
- * @param {RequestOptions} [params.options] - Additional options for the request.
963
- * @throws {Error} Throws an error if the id or updateData parameter is missing.
964
- * @returns {Promise<SdkResponse<any>>} - The updated tool returned from the server (secrets redacted).
965
- */
966
- async updateAgentTool({ id, updateData, options = {} }) {
967
- this.client._require({ id, updateData });
968
- const safeId = encodeURIComponent(id);
969
- return this.client(`/agent/tools/${safeId}`, { method: "PUT", body: updateData, ...options });
970
- }
971
-
972
- /**
973
- * Delete an agent tool by its id.
974
- * @async
975
- * @roles api, admin, developer
976
- * @param {Object} params - The parameters for deleting a tool.
977
- * @param {string} params.id - The id of the tool to delete.
978
- * @param {RequestOptions} [params.options] - Additional options for the request.
979
- * @throws {Error} Throws an error if the id parameter is missing.
980
- * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
981
- */
982
- async deleteAgentTool({ id, options = {} }) {
983
- this.client._require({ id });
984
- const safeId = encodeURIComponent(id);
985
- return this.client(`/agent/tools/${safeId}`, { method: "DELETE", ...options });
986
- }
987
- }