@signalhousellc/sdk 1.0.67 → 1.0.69

package/src/domains/Agents.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateAgentProfileData
  * @property {string} groupId - The parent group id (at least 8 characters, starts with 'G').
@@ -7,10 +13,6 @@
  * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
  * @property {string} [greeting] - Opening line the agent leads with.
  * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
- * @property {string|null} [voiceId] - ElevenLabs voice id for the voice channel; null until set.
- * @property {string} [llmProvider] - LLM backend: "bedrock", "openai", "anthropic", or "groq" (defaults to "bedrock").
- * @property {string|null} [llmModel] - Concrete model id for the provider; null = provider default.
- * @property {number} [temperature] - Sampling temperature (0-2).
  */
 
 /**
@@ -20,10 +22,33 @@
  * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
  * @property {string} [greeting] - Opening line the agent leads with.
  * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
- * @property {string|null} [voiceId] - ElevenLabs voice id for the voice channel.
- * @property {string} [llmProvider] - LLM backend: "bedrock", "openai", "anthropic", or "groq".
+ */
+
+/**
+ * The per-channel settings for one agent. Model, voice and sampling settings live here rather
+ * than on the profile: each channel is served by a different runtime, and the model catalogues
+ * do not overlap — so a value that is valid on one channel may be invalid on another.
+ * @typedef {Object} AgentChannelSettingData
+ * @property {string[]} [allowedTools] - Tools enabled on this channel — built-in keys or custom agentTool ids.
+ * @property {boolean} [enabled] - Whether the agent answers on this channel.
+ * @property {string} [channelPrompt] - Channel-specific prompt text appended to the agent's system prompt.
+ * @property {string|null} [greeting] - Channel-specific greeting override; null = use the agent's greeting.
+ * @property {string} [llmProvider] - LLM backend for this channel: "bedrock", "openai", "anthropic", or "groq" (defaults to "bedrock").
  * @property {string|null} [llmModel] - Concrete model id for the provider; null = provider default.
  * @property {number} [temperature] - Sampling temperature (0-2).
+ * @property {string|null} [voiceId] - Voice identifier for spoken channels; ignored off the voice channel.
+ * @property {number|null} [speed] - Speaking rate multiplier (0.7-1.2); null = platform default.
+ * @property {number|null} [stability] - Voice consistency (0-1); lower is more expressive and more variable.
+ * @property {number|null} [similarityBoost] - How closely synthesis tracks the source voice (0-1).
+ * @property {string|null} [speechModel] - Speech synthesis model; separate from `llmModel`, which decides what is said rather than how it is voiced.
+ * @property {string|null} [turnEagerness] - How readily the agent decides the caller has finished: "patient", "normal", or "eager".
+ * @property {number|null} [turnTimeoutSeconds] - Silence before the agent takes its turn: 1-300, or -1 for no timeout.
+ * @property {number|null} [initialWaitSeconds] - Silence before the agent speaks first: 1-300, or -1 for no timeout.
+ * @property {number|null} [silenceEndCallSeconds] - Silence before the call is ended outright (10-7200).
+ * @property {number|null} [maxCallDurationSeconds] - Hard ceiling on one conversation (60-7200).
+ * @property {boolean} [allowGreetingInterruption] - Whether a caller may talk over the greeting.
+ * @property {string[]} [keyterms] - Words the transcriber is biased toward — names, jargon, unusual spellings.
+ * @property {Object|null} [backgroundSound] - Ambient audio bed as `{ preset, volume }`; null = silence.
  */
 
 export class Agents {
@@ -32,21 +57,37 @@ export class Agents {
 		this.enableAdmin = enableAdmin;
 	}
 
+	/**
+	 * List the voices an agent can be configured to speak with.
+	 *
+	 * The catalog is platform-wide, not per-account, so this takes no scope. `voiceId` is the
+	 * value to set on a spoken channel's setting.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - The parameters for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} - The available voices, each as `{ voiceId, name, description, previewUrl, gender, accent, age, useCase, language }`.
+	 */
+	async getAgentVoices({ options = {} } = {}) {
+		return this.client("/agent/voices", { method: "GET", ...options });
+	}
+
 	/**
 	 * List the agent profiles under a group.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for listing agent profiles.
 	 * @param {string} params.groupId - The group whose profiles to list (required).
+	 * @param {string} [params.subgroupId] - Narrow to the agents this subgroup can use — its own, plus the group-level agents shared with every subgroup.
 	 * @param {number} [params.page] - The page number for pagination.
 	 * @param {number} [params.limit] - The number of items per page for pagination.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The list of agent profiles returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The list of agent profiles returned from the server.
 	 */
-	async getAgentProfiles({ groupId, page, limit, options = {} }) {
+	async getAgentProfiles({ groupId, subgroupId, page, limit, options = {} }) {
 		this.client._require({ groupId });
-		const queryString = this.client._getQueryString({ groupId, page, limit });
+		const queryString = this.client._getQueryString({ groupId, subgroupId, page, limit });
 		return this.client(`/agent/profiles${queryString}`, { method: "GET", ...options });
 	}
 
@@ -56,9 +97,9 @@ export class Agents {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting an agent profile.
 	 * @param {string} params.agentProfileId - The id of the agent profile to fetch.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the agentProfileId parameter is missing.
-	 * @returns {Promise<Object>} - The agent profile returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The agent profile returned from the server.
 	 */
 	async getAgentProfile({ agentProfileId, options = {} }) {
 		this.client._require({ agentProfileId });
@@ -72,9 +113,9 @@ export class Agents {
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating an agent profile (see CreateAgentProfileData typedef).
 	 * @param {CreateAgentProfileData} params.profileData - The data for the agent profile to create, including required fields groupId and name.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the profileData parameter is missing.
-	 * @returns {Promise<Object>} - The created agent profile returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The created agent profile returned from the server.
 	 */
 	async createAgentProfile({ profileData, options = {} }) {
 		this.client._require({ profileData });
@@ -88,9 +129,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for updating an agent profile (see UpdateAgentProfileData typedef).
 	 * @param {string} params.id - The id of the agent profile to update.
 	 * @param {UpdateAgentProfileData} params.updateData - The data for the agent profile to update.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
-	 * @returns {Promise<Object>} - The updated agent profile returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The updated agent profile returned from the server.
 	 */
 	async updateAgentProfile({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -104,9 +145,9 @@ export class Agents {
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for deleting an agent profile.
 	 * @param {string} params.id - The id of the agent profile to delete.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id parameter is missing.
-	 * @returns {Promise<Object>} - The inactivated agent profile returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The inactivated agent profile returned from the server.
 	 */
 	async deleteAgentProfile({ id, options = {} }) {
 		this.client._require({ id });
@@ -127,9 +168,9 @@ export class Agents {
 	 * @param {string} params.message - The user's message (required).
 	 * @param {string} [params.conversationId] - Continue this conversation; omit to start a new one.
 	 * @param {string} [params.contactIdentifier] - The far-end identifier (webchat visitor id, sender number).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if agentProfileId, channel, or message is missing.
-	 * @returns {Promise<Object>} - `{ conversationId, conversationSessionId, reply, toolInvocations, ok }` from the server.
+	 * @returns {Promise<SdkResponse<any>>} - `{ conversationId, conversationSessionId, reply, toolInvocations, ok }` from the server.
 	 */
 	async sendAgentMessage({ agentProfileId, channel, message, conversationId, contactIdentifier, options = {} }) {
 		this.client._require({ agentProfileId, channel, message });
@@ -139,6 +180,114 @@ export class Agents {
 		return this.client(`/agent/messages`, { method: "POST", body, ...options });
 	}
 
+	/**
+	 * Start a conversation without sending a message.
+	 *
+	 * The counterpart to `sendAgentMessage` for callers that run the model themselves —
+	 * a voice runtime, or your own LLM. Those record what was said; `sendAgentMessage`
+	 * decides it. Both write the same conversation records.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for starting a conversation.
+	 * @param {string} params.agentProfileId - The agent this conversation belongs to (required).
+	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice" (required).
+	 * @param {string} [params.contactIdentifier] - The far-end identifier (visitor id, caller number).
+	 * @param {string} [params.callId] - Telephony call id, for the voice channel.
+	 * @param {Object} [params.metadata] - Arbitrary metadata stored with the conversation.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
+	 * @returns {Promise<Object>} - The created conversation, including `conversationId` and `conversationSessionId`.
+	 */
+	async startConversation({ agentProfileId, channel, contactIdentifier, callId, metadata, options = {} }) {
+		this.client._require({ agentProfileId, channel });
+		const body = { agentProfileId, channel };
+		if (contactIdentifier !== undefined && contactIdentifier !== null) body.contactIdentifier = contactIdentifier;
+		if (callId !== undefined && callId !== null) body.callId = callId;
+		if (metadata !== undefined && metadata !== null) body.metadata = metadata;
+		return this.client(`/agent/conversations`, { method: "POST", body, ...options });
+	}
+
+	/**
+	 * Read one conversation with a page of its messages, in order.
+	 *
+	 * Paged rather than whole: a transcript has no natural ceiling. Omitting `limit` gives 100
+	 * messages, not all of them.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for reading a conversation.
+	 * @param {string} params.conversationId - The conversation to read (required).
+	 * @param {number} [params.page] - Page number; defaults to 1.
+	 * @param {number} [params.limit] - Messages per page; defaults to 100, capped at 500.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the conversationId parameter is missing.
+	 * @returns {Promise<Object>} - A one-element array with the conversation and its `messages`.
+	 */
+	async getConversation({ conversationId, page, limit, options = {} }) {
+		this.client._require({ conversationId });
+		const safeId = encodeURIComponent(conversationId);
+		const queryString = this.client._getQueryString({ page, limit });
+		return this.client(`/agent/conversations/${safeId}${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Append one message to a conversation.
+	 *
+	 * Records a turn rather than generating one, so `role` is explicit — an assistant turn
+	 * your own runtime produced is the normal case here. `content` is optional so a
+	 * tool-only turn needs no prose.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for appending a message.
+	 * @param {string} params.conversationId - The conversation to append to (required).
+	 * @param {string} params.role - "user", "assistant", "system", or "tool" (required).
+	 * @param {string} [params.content] - What was said.
+	 * @param {Array<Object>} [params.toolCalls] - Tools invoked on this turn.
+	 * @param {Array<Object>} [params.toolResults] - Their results.
+	 * @param {number} [params.ttfbMs] - Time to first byte/audio, in milliseconds.
+	 * @param {number} [params.latencyMs] - Total turn latency, in milliseconds.
+	 * @param {boolean} [params.bargeInOccurred] - Whether the far end talked over this turn.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if conversationId or role is missing.
+	 * @returns {Promise<Object>} - The persisted message.
+	 */
+	async appendConversationMessage({ conversationId, role, content, toolCalls, toolResults, ttfbMs, latencyMs, bargeInOccurred, options = {} }) {
+		this.client._require({ conversationId, role });
+		const safeId = encodeURIComponent(conversationId);
+		const body = { role };
+		if (content !== undefined && content !== null) body.content = content;
+		if (toolCalls !== undefined && toolCalls !== null) body.toolCalls = toolCalls;
+		if (toolResults !== undefined && toolResults !== null) body.toolResults = toolResults;
+		if (ttfbMs !== undefined && ttfbMs !== null) body.ttfbMs = ttfbMs;
+		if (latencyMs !== undefined && latencyMs !== null) body.latencyMs = latencyMs;
+		if (bargeInOccurred !== undefined && bargeInOccurred !== null) body.bargeInOccurred = bargeInOccurred;
+		return this.client(`/agent/conversations/${safeId}/messages`, { method: "POST", body, ...options });
+	}
+
+	/**
+	 * End a conversation, closing its open session.
+	 *
+	 * `status` records HOW it ended and cannot be recovered afterwards, so pass the one that
+	 * actually happened. Ending an already-ended conversation is a no-op, so a retry after a
+	 * dropped connection cannot overwrite it.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for ending a conversation.
+	 * @param {string} params.conversationId - The conversation to end (required).
+	 * @param {string} [params.status] - "completed", "escalated", or "abandoned" (defaults to "completed").
+	 * @param {Object} [params.metadata] - Metadata merged onto the conversation.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the conversationId parameter is missing.
+	 * @returns {Promise<Object>} - The ended conversation.
+	 */
+	async endConversation({ conversationId, status, metadata, options = {} }) {
+		this.client._require({ conversationId });
+		const safeId = encodeURIComponent(conversationId);
+		const body = {};
+		if (status !== undefined && status !== null) body.status = status;
+		if (metadata !== undefined && metadata !== null) body.metadata = metadata;
+		return this.client(`/agent/conversations/${safeId}`, { method: "PUT", body, ...options });
+	}
+
 	/**
 	 * List an agent's per-channel settings (the tools enabled per channel, whether the
 	 * channel is on, and any channel-specific prompt/greeting).
@@ -146,9 +295,9 @@ export class Agents {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for listing channel settings.
 	 * @param {string} params.agentProfileId - The agent whose channel settings to list.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the agentProfileId parameter is missing.
-	 * @returns {Promise<Object>} - The agent's channel settings returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The agent's channel settings returned from the server.
 	 */
 	async getAgentChannelSettings({ agentProfileId, options = {} }) {
 		this.client._require({ agentProfileId });
@@ -163,9 +312,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for getting a channel setting.
 	 * @param {string} params.agentProfileId - The agent the setting belongs to.
 	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
-	 * @returns {Promise<Object>} - The channel setting returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The channel setting returned from the server.
 	 */
 	async getAgentChannelSetting({ agentProfileId, channel, options = {} }) {
 		this.client._require({ agentProfileId, channel });
@@ -182,10 +331,10 @@ export class Agents {
 	 * @param {Object} params - The parameters for the upsert.
 	 * @param {string} params.agentProfileId - The agent the setting belongs to.
 	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
-	 * @param {Object} [params.settingData] - The fields to set: allowedTools (string[]), enabled (boolean), channelPrompt (string), greeting (string|null).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {AgentChannelSettingData} [params.settingData] - The fields to set.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
-	 * @returns {Promise<Object>} - The created or updated channel setting returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The created or updated channel setting returned from the server.
 	 */
 	async upsertAgentChannelSetting({ agentProfileId, channel, settingData = {}, options = {} }) {
 		this.client._require({ agentProfileId, channel });
@@ -201,9 +350,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for the delete.
 	 * @param {string} params.agentProfileId - The agent the setting belongs to.
 	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
-	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
 	 */
 	async deleteAgentChannelSetting({ agentProfileId, channel, options = {} }) {
 		this.client._require({ agentProfileId, channel });
@@ -221,9 +370,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for reading tenant settings.
 	 * @param {string} params.groupId - The group (required).
 	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The tenant settings returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The tenant settings returned from the server.
 	 */
 	async getTenantAiSettings({ groupId, subgroupId, options = {} }) {
 		this.client._require({ groupId });
@@ -240,9 +389,9 @@ export class Agents {
 	 * @param {string} params.groupId - The group (required).
 	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
 	 * @param {Object} [params.settingsData] - Fields to set: brandName (string), tone (string), timezone (IANA string), businessHours (array of {day, closed, open, close}), afterHoursMessage (string).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The created or updated tenant settings returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The created or updated tenant settings returned from the server.
 	 */
 	async upsertTenantAiSettings({ groupId, subgroupId, settingsData = {}, options = {} }) {
 		this.client._require({ groupId });
@@ -257,9 +406,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for the delete.
 	 * @param {string} params.groupId - The group (required).
 	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
 	 */
 	async deleteTenantAiSettings({ groupId, subgroupId, options = {} }) {
 		this.client._require({ groupId });
@@ -278,9 +427,9 @@ export class Agents {
 	 * @param {string} [params.agentProfileId] - Narrow to one agent.
 	 * @param {number} [params.page] - Page number (1-based) for pagination.
 	 * @param {number} [params.limit] - Items per page (max 100; server default 25).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The knowledge items returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The knowledge items returned from the server.
 	 */
 	async getKnowledgeItems({ groupId, subgroupId, agentProfileId, page, limit, options = {} }) {
 		this.client._require({ groupId });
@@ -294,9 +443,9 @@ export class Agents {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a knowledge item.
 	 * @param {string} params.knowledgeItemId - The id of the knowledge item to fetch.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the knowledgeItemId parameter is missing.
-	 * @returns {Promise<Object>} - The knowledge item returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The knowledge item returned from the server.
 	 */
 	async getKnowledgeItem({ knowledgeItemId, options = {} }) {
 		this.client._require({ knowledgeItemId });
@@ -314,9 +463,9 @@ export class Agents {
 	 *                                   Optional: subgroupId (starts with 'S', nullable), agentProfileId
 	 *                                   (nullable = shared across the tenant's agents), title, source
 	 *                                   ("manual" | "url" | "document" | "import"), enabled (boolean), metadata (object|null).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the itemData parameter is missing.
-	 * @returns {Promise<Object>} - The created knowledge item returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The created knowledge item returned from the server.
 	 */
 	async createKnowledgeItem({ itemData, options = {} }) {
 		this.client._require({ itemData });
@@ -331,9 +480,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for updating a knowledge item.
 	 * @param {string} params.id - The id of the knowledge item to update.
 	 * @param {Object} params.updateData - The fields to update: title, text, source, enabled, metadata.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
-	 * @returns {Promise<Object>} - The updated knowledge item returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The updated knowledge item returned from the server.
 	 */
 	async updateKnowledgeItem({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -347,9 +496,9 @@ export class Agents {
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for deleting a knowledge item.
 	 * @param {string} params.id - The id of the knowledge item to delete.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id parameter is missing.
-	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
 	 */
 	async deleteKnowledgeItem({ id, options = {} }) {
 		this.client._require({ id });
@@ -369,9 +518,9 @@ export class Agents {
 	 * @param {string} [params.type] - Narrow to a tool type: "builtin", "webhook", or "mcp".
 	 * @param {number} [params.page] - Page number (1-based) for pagination.
 	 * @param {number} [params.limit] - Items per page (max 100; server default 25).
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the groupId parameter is missing.
-	 * @returns {Promise<Object>} - The tools returned from the server (secrets redacted).
+	 * @returns {Promise<SdkResponse<any>>} - The tools returned from the server (secrets redacted).
 	 */
 	async getAgentTools({ groupId, subgroupId, agentProfileId, type, page, limit, options = {} }) {
 		this.client._require({ groupId });
@@ -385,9 +534,9 @@ export class Agents {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting a tool.
 	 * @param {string} params.agentToolId - The id of the tool to fetch.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the agentToolId parameter is missing.
-	 * @returns {Promise<Object>} - The tool returned from the server (secrets redacted).
+	 * @returns {Promise<SdkResponse<any>>} - The tool returned from the server (secrets redacted).
 	 */
 	async getAgentTool({ agentToolId, options = {} }) {
 		this.client._require({ agentToolId });
@@ -411,9 +560,9 @@ export class Agents {
 	 *                                   call (reserved/framing and `x-signalhouse-*` names are rejected); `signingSecret` makes us
 	 *                                   send `X-SignalHouse-Signature: sha256=HMAC-SHA256(`${X-SignalHouse-Timestamp}.${rawBody}`)`
 	 *                                   so you can verify the call and reject replays. Stored, never returned.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the toolData parameter is missing.
-	 * @returns {Promise<Object>} - The created tool returned from the server (secrets redacted).
+	 * @returns {Promise<SdkResponse<any>>} - The created tool returned from the server (secrets redacted).
 	 */
 	async createAgentTool({ toolData, options = {} }) {
 		this.client._require({ toolData });
@@ -428,9 +577,9 @@ export class Agents {
 	 * @param {Object} params - The parameters for updating a tool.
 	 * @param {string} params.id - The id of the tool to update.
 	 * @param {Object} params.updateData - The fields to update: name, description, type, builtinKey, parametersSchema, config, webhookUrl, webhookAuth, mcpServerUrl, channels, enabled.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
-	 * @returns {Promise<Object>} - The updated tool returned from the server (secrets redacted).
+	 * @returns {Promise<SdkResponse<any>>} - The updated tool returned from the server (secrets redacted).
 	 */
 	async updateAgentTool({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -444,9 +593,9 @@ export class Agents {
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for deleting a tool.
 	 * @param {string} params.id - The id of the tool to delete.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} Throws an error if the id parameter is missing.
-	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 * @returns {Promise<SdkResponse<any>>} - The delete confirmation returned from the server.
 	 */
 	async deleteAgentTool({ id, options = {} }) {
 		this.client._require({ id });

package/src/domains/Auth.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Auth {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -13,9 +19,9 @@ export class Auth {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for forcing a group logout
 				 * @param {string} params.groupId - The ID of the group whose users should be force-logged-out
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupId parameter is missing
-				 * @returns {Promise<Object>} - The response containing loggedOutCount
+				 * @returns {Promise<SdkResponse<any>>} - The response containing loggedOutCount
 				 */
 				forceLogoutGroupUsers: async ({ groupId, options = {} }) => {
 					this.client._require({ groupId });
@@ -33,8 +39,8 @@ export class Auth {
 	 * @param {Object} params
 	 * @param {string} params.email - The user's email address
 	 * @param {string} params.password - The user's password
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async login({ email, password, options = {} }) {
 		return this.client(`/auth`, { method: "POST", body: { email, password }, ...options });
@@ -57,8 +63,8 @@ export class Auth {
 	 * @param {boolean} [params.acceptedTermsOfService] - Whether the user accepted the Terms of Service
 	 * @param {string} [params.psXid] - PartnerStack click id (ps_xid) captured from a referral link
 	 * @param {string} [params.psPartnerKey] - PartnerStack partner key (ps_partner_key) captured from a referral link
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server (contains the JWT token)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server (contains the JWT token)
 	 */
 	async register({ businessName, fullName, email, password, phone, dialCode, country, volume, products, acceptedTermsOfService, psXid, psPartnerKey, options = {} }) {
 		return this.client(`/auth/register`, {
@@ -83,8 +89,8 @@ export class Auth {
 	 * @roles public
 	 * @param {Object} params
 	 * @param {string} params.token - The verification token from the email link
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ verified: true, token?: string })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ verified: true, token?: string })
 	 */
 	async verifyEmail({ token, options = {} }) {
 		this.client._require({ token });
@@ -99,8 +105,8 @@ export class Auth {
 	 * @roles public
 	 * @param {Object} params
 	 * @param {string} params.email - The email address to send a reset link to
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ success: true })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ success: true })
 	 */
 	async forgotPassword({ email, options = {} }) {
 		this.client._require({ email });
@@ -114,8 +120,8 @@ export class Auth {
 	 * @param {Object} params
 	 * @param {string} params.token - The single-use reset token from the email link
 	 * @param {string} params.password - The new password to set (min 8 characters)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ success: true })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ success: true })
 	 */
 	async resetPasswordWithToken({ token, password, options = {} }) {
 		this.client._require({ token, password });
@@ -129,8 +135,8 @@ export class Auth {
 	 * @async
 	 * @roles admin, developer, billing, user
 	 * @param {Object} [params]
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ sent: true })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ sent: true })
 	 */
 	async sendVerificationEmail({ options = {} } = {}) {
 		return this.client(`/auth/send-verification-email`, { method: "POST", ...options });
@@ -143,8 +149,8 @@ export class Auth {
 	 * @param {Object} params
 	 * @param {string} params.userId - The id of the user
 	 * @param {string} params.newPassword - The new password to set for the user
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async resetPassword({ userId, newPassword, options = {} }) {
         this.client._require({ userId, newPassword });
@@ -161,8 +167,8 @@ export class Auth {
 	 * @param {string} [params.userId] - Returns history for a specific user (one of groupId/userId required)
 	 * @param {number} [params.page] - Page number (min 1, default 1)
 	 * @param {number} [params.limit] - Results per page (min 1, max 100, default 20)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async getAuthHistory({ groupId, userId, page, limit, options = {} }) {
 		this.client._require({ "groupId or userId": groupId ?? userId });
@@ -175,8 +181,8 @@ export class Auth {
 	 * @async
 	 * @roles admin
 	 * @param {Object} [params]
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response containing loggedOutCount
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response containing loggedOutCount
 	 */
 	async logoutAll({ options = {} } = {}) {
 		return this.client(`/auth/logout-all`, { method: "POST", ...options });
@@ -188,8 +194,8 @@ export class Auth {
 	 * @async
 	 * @roles admin, developer, billing, user, api
 	 * @param {Object} [params]
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response containing { groupId }
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response containing { groupId }
 	 */
 	async getGroupId({ options = {} } = {}) {
 		return this.client(`/auth/group-id`, { method: "GET", ...options });
@@ -202,8 +208,8 @@ export class Auth {
 	 * @roles admin, developer, billing, user
 	 * @param {Object} params
 	 * @param {string} params.product - The external system to link to ("ghl" or "shopify")
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ token })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ token })
 	 */
 	async requestExternalLinkToken({ product, options = {} }) {
 		this.client._require({ product });