@signalhousellc/sdk 1.0.67 → 1.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.67",
+  "version": "1.0.68",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",
@@ -19,7 +19,9 @@
   },
   "scripts": {
     "postinstall": "node scripts/install-skills.mjs",
-    "sync-skills": "node scripts/sync-skills.mjs"
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "build:types": "tsc -p tsconfig.json",
+    "check:types": "tsc -p tsconfig.json --noEmit"
   },
   "agents": {
     "skills": "./skills"
@@ -36,5 +38,10 @@
     "jssip": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "jssip": "^3.13.8",
+    "typescript": "^5.9.3"
   }
 }

package/src/SignalHouseSDK.js

@@ -6,6 +6,19 @@ import axios from "axios";
  * @property {object} [headers] - Additional headers to include in the request
  */
 
+/**
+ * @typedef {Object} SignalHouseSDKConfig
+ * @property {string} apiKey - The API key for authenticating requests to the SignalHouse API
+ * @property {string} baseUrl - The base URL for the SignalHouse API (e.g., "https://api.signalhouse.com")
+ * @property {boolean} [enableAdmin=false] - Enable admin-scoped behaviors on domains that support them
+ */
+
+/**
+ * The envelope every domain method resolves to. Non-2xx responses never reject; check `success` first.
+ * @template T
+ * @typedef {{ success: true, data: T, status: number } | { success: false, error: string|Object, status: number|null }} SdkResponse
+ */
+
 // Main SDK Class (SignalHouseSDK.js)
 import { Auth } from "./domains/Auth.js";
 import { Billing } from "./domains/Billing.js";
@@ -29,19 +42,15 @@ import { Agents } from "./domains/Agents.js";
 export class SignalHouseSDK {
 	/**
 	 * Initialize the SignalHouseSDK with the required configuration
-	 * @param {Object} config - The configuration object for initializing the SDK
-	 * @param {string} config.apiKey - The API key for authenticating requests to the SignalHouse API
-	 * @param {string} config.baseUrl - The base URL for the SignalHouse API (e.g., "https://api.signalhouse.com")
-	 * @param {boolean} [config.enableAdmin=false] - Enable admin-scoped behaviors on domains that support them.
+	 * @param {SignalHouseSDKConfig} config - The configuration object for initializing the SDK
 	 * @throws {Error} Throws an error if the API key or base URL is missing from the configuration
-	 * @returns {SignalHouseSDK} An instance of the SignalHouseSDK
 	 */
-	constructor(config = {}) {
+	constructor(config) {
 		// Validate required config parameters
-		if (!config.apiKey) {
+		if (!config?.apiKey) {
 			throw new Error("API key is required to initialize SignalHouseSDK");
 		}
-		if (!config.baseUrl) {
+		if (!config?.baseUrl) {
 			throw new Error("Base URL is required to initialize SignalHouseSDK");
 		}
 
@@ -90,19 +99,21 @@ export class SignalHouseSDK {
 		const instance = axios.create({ baseURL: this.baseUrl, headers: isMultipart ? {} : { "Content-Type": "application/json" } });
 
 		// Add a request interceptor to include the API key in the Authorization header
-		instance.interceptors.request.use((config) => {
+		instance.interceptors.request.use((/** @type {import('axios').InternalAxiosRequestConfig & { token?: string }} */ config) => {
 			const token = config.token || this.apiKey;
 			config.headers.Authorization = `Bearer ${token}`;
 			delete config.token; // Remove token from config to avoid sending it as a header
 			return config;
 		});
 
-		// Standardize responses
+		// Standardize responses. The fulfilled handler deliberately replaces the AxiosResponse with the
+		// SdkResponse envelope, which axios's interceptor typing does not model; the cast keeps that intent visible.
 		instance.interceptors.response.use(
 			// Standard 2xx responses
-			(response) => {
+			/** @type {(response: import('axios').AxiosResponse) => any} */
+			((response) => {
 				return { success: true, data: response.data, status: response.status };
-			},
+			}),
 
 			// Non-2xx responses
 			(error) => {
@@ -156,7 +167,7 @@ export class SignalHouseSDK {
 	_require(fields) {
 		for (const [name, value] of Object.entries(fields)) {
 			if (value === undefined || value === null || value === "") {
-				const error = new Error(`Missing required parameter: ${name}`);
+				const error = /** @type {Error & { status?: number }} */ (new Error(`Missing required parameter: ${name}`));
 				error.name = "SignalHouseValidationError";
 				error.status = 400; // Match API validation code
 				throw error;

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 });