@signalhousellc/sdk 1.0.67 → 1.0.69

package/src/domains/Users.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateUserData
  * @property {string} groupId - The ID of the group to which the user belongs (must start with "G" and be at least 8 characters long)
@@ -20,9 +26,11 @@
 
 /**
  * @typedef {Object} CreateServiceUserData
- * @property {string} groupId - The ID of the group to which the service user belongs (required)
+ * @property {string} groupId - The ID of the group to which the service user belongs (required for customer API keys)
  * @property {string} name - The name of the service user (required)
- * @property {string} role - The role of the service user (admin, developer, billing, user) (required)
+ * @property {string} role - The role of the service user: "api" for a customer API key (required)
+ * @property {string[]} [allowedIps] - Only accept this API key from these IPv4/IPv6 addresses or CIDR ranges (max 100). Omit or pass [] for no IP restriction. Customer API keys only.
+ * @property {string[]} [allowedCountries] - Only accept this API key from these countries, as ISO 3166-1 alpha-2 codes such as "US" (max 250). Omit or pass [] for no country restriction. Customer API keys only.
  */
 
 /**
@@ -41,6 +49,8 @@
  * @property {string} [country] - The country of the user's address (optional)
  * @property {string} [postalCode] - The postal code of the user's address (optional)
  * @property {string} [status] - The status of the user (e.g., "active", "inactive")
+ * @property {string[]} [allowedIps] - Customer API keys only: replace the key's allowed IPv4/IPv6 addresses or CIDR ranges ([] removes the restriction). Requires an interactive admin or developer session; an API key cannot change its own restrictions.
+ * @property {string[]} [allowedCountries] - Customer API keys only: replace the key's allowed ISO 3166-1 alpha-2 country codes ([] removes the restriction). Requires an interactive admin or developer session.
  */
 
 export class Users {
@@ -61,8 +71,8 @@ export class Users {
 				 * @param {string} [params.search] - Search users by email (case-insensitive)
 				 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
 				 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - A promise that resolves to the list of users
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the list of users
 				 */
 				getUsers: async ({ email, userType, page, limit, search, sortBy, sortOrder, options = {} }) => {
 					const filters = { email, userType, page, limit, search, sortBy, sortOrder };
@@ -75,8 +85,8 @@ export class Users {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for creating an internal user
 				 * @param {CreateServiceUserData} params.data - The data for the new internal user
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - A promise that resolves to the created internal user
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the created internal user
 				 */
 				createInternalUser: async ({ data, options = {} }) => {
 					this.client._require({ data: data });
@@ -99,8 +109,8 @@ export class Users {
 	 * @param {string} [params.search] - Search users by email (case-insensitive)
 	 * @param {string} [params.sortBy] - Field to sort by (createdAt, email, activeGroupId, companyName, status, _id)
 	 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - A promise that resolves to the list of users
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the list of users
 	 */
 	async getUsers({ id, groupId, userType, page, limit, search, sortBy, sortOrder, options = {} }) {
 		const filters = { id, groupId, userType, page, limit, search, sortBy, sortOrder };
@@ -114,9 +124,9 @@ export class Users {
 	 * @roles api, admin
 	 * @param {Object} params - The parameters for creating a user (see CreateUserData typedef for details)
 	 * @param {CreateUserData} params.data - The data for the new user
-	 * @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 required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the created user
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the created user
 	 */
 	async createUser({ data, options = {} }) {
 		this.client._require({ data: data });
@@ -129,9 +139,9 @@ export class Users {
 	 * @roles admin, developer
 	 * @param {Object} params - The parameters for creating a service user (see CreateServiceUserData typedef for details)
 	 * @param {CreateServiceUserData} params.data - The data for the new service user
-	 * @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 required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the created service user
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the created service user
 	 */
 	async createServiceUser({ data, options = {} }) {
 		this.client._require({ data: data });
@@ -145,9 +155,9 @@ export class Users {
 	 * @param {Object} params - The parameters for updating a user (see UpdateUserData typedef for details)
 	 * @param {string} params.id - The ID of the user to update
 	 * @param {UpdateUserData} params.data - The data to update for the user
-	 * @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 required fields in the data parameter are missing
-	 * @returns {Promise<Object>} - A promise that resolves to the updated user
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the updated user
 	 */
 	async updateUser({ id, data, options = {} }) {
 		this.client._require({ id, data: data });
@@ -161,9 +171,9 @@ export class Users {
 	 * @roles api, admin
 	 * @param {Object} params - The parameters for deleting a user
 	 * @param {string} params.id - The ID of the user 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>} - A promise that resolves to the deleted user
+	 * @returns {Promise<SdkResponse<any>>} - A promise that resolves to the deleted user
 	 */
 	async deleteUser({ id, options = {} }) {
 		this.client._require({ id });
@@ -176,8 +186,8 @@ export class Users {
 	 * @async
 	 * @roles api, 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 ({ acceptedTermsOfService: true })
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server ({ acceptedTermsOfService: true })
 	 */
 	async acceptTermsOfService({ options = {} } = {}) {
 		return this.client(`/user/accept-terms`, { method: "PUT", body: { acceptedTermsOfService: true }, ...options });
@@ -189,8 +199,8 @@ export class Users {
 	 * @roles api, admin, self
 	 * @param {Object} params
 	 * @param {string} params.id - The ID of 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 getNotificationPreferences({ id, options = {} }) {
 		this.client._require({ id });
@@ -205,8 +215,8 @@ export class Users {
 	 * @param {Object} params
 	 * @param {string} params.id - The ID of the user
 	 * @param {Array<{name: string, web: boolean, email: boolean}>} params.notificationPreferences - Array of notification preference objects
-	 * @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 updateNotificationPreferences({ id, notificationPreferences, options = {} }) {
 		this.client._require({ id, notificationPreferences });

package/src/domains/Webhooks.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Webhooks {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -17,8 +23,8 @@ export class Webhooks {
 	 * @param {string} [params.phoneNumber] - Filter by associated phone number (for SMS webhooks)
 	 * @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
-	 * @returns {Promise<Array>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<Array>>} The response from the server
 	 */
 	async getWebhooks({ id, groupId, endpointType, phoneNumber, page, limit, options = {} }) {
 		const filters = { id, groupId, endpointType, phoneNumber, page, limit };
@@ -31,15 +37,17 @@ export class Webhooks {
 	 * plaintext HMAC-SHA256 secret used to sign every delivery to this endpoint, sent as the
 	 * `X-SignalHouse-Signature` header alongside `X-SignalHouse-Timestamp` (the signed string is
 	 * `${timestamp}.${rawRequestBody}`) and `X-SignalHouse-Delivery-Id` (stable across retries of the
-	 * same event, for receiver-side dedup). Store this secret now: it is never returned again by any
-	 * read (SHGHL-2944).
+	 * same event, for receiver-side dedup), plus `X-SignalHouse-Signature-V1` (`t=<ms>,v1=<hex>[,v1=<hex>]`,
+	 * every currently valid signature). Store this secret now: it is never returned again by any read
+	 * (SHGHL-2944). If it's lost, call `rotateWebhookSecret`. Verify deliveries with
+	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
 	 * @param {Object} params.webhookData - The data for the new webhook
-	 * @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 webhookData parameter is missing or if required fields in webhookData are missing
-	 * @returns {Promise<Object>} The response from the server, including the plaintext `signingSecret` (this one time only)
+	 * @returns {Promise<SdkResponse<any>>} The response from the server, including the plaintext `signingSecret` (this one time only)
 	 */
 	async createWebhook({ webhookData, options = {} }) {
 		this.client._require({ webhookData: webhookData });
@@ -47,17 +55,19 @@ export class Webhooks {
 	}
 
 	/**
-	 * Update an existing webhook with the specified data. Like every other read of a webhook, the
-	 * response carries `hasSigningSecret` (boolean), never the signing secret itself — see
-	 * `createWebhook` (SHGHL-2944).
+	 * Update an existing webhook with the specified data. `updateData` may include `name`, `url`,
+	 * `subscribedEvents` and (SHGHL-3486) `authType`, `apiHeaderPrefix` and `credentials` (`{ key, secret? }`)
+	 * to change the endpoint's own credentials in place: credentials are required when switching to an auth
+	 * type that needs them, and omitted credentials keep the stored ones. Like every read of a webhook, the
+	 * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for updating a webhook
 	 * @param {string} params.id - The ID of the webhook to update
 	 * @param {Object} params.updateData - The data for the webhook to be updated, including fields such as endpoint URL and event types
-	 * @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 response from the server
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async updateWebhook({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -65,15 +75,37 @@ export class Webhooks {
 		return this.client(`/webhook/${safeId}`, { method: "PUT", body: updateData, ...options });
 	}
 
+	/**
+	 * Rotate a webhook's signing secret, or give a webhook created before signing existed its first one
+	 * (SHGHL-3486). The response includes the new plaintext `signingSecret`, returned this one time only.
+	 * The replaced secret keeps working for `graceSeconds` (default 86400, max 604800, 0 = stop now):
+	 * during that window each delivery's `X-SignalHouse-Signature-V1` header carries a signature for both,
+	 * and `previousSecretExpiresAt` in the response says when the old one stops. Not available to OAuth
+	 * connector tokens.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for rotating the secret
+	 * @param {string} params.id - The ID of the webhook
+	 * @param {number} [params.graceSeconds] - How long the replaced secret stays valid
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the id parameter is missing
+	 * @returns {Promise<SdkResponse<any>>} The webhook, including the new plaintext `signingSecret` (this one time only)
+	 */
+	async rotateWebhookSecret({ id, graceSeconds, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/webhook/${safeId}/rotate-secret`, { method: "POST", body: graceSeconds === undefined ? {} : { graceSeconds }, ...options });
+	}
+
 	/**
 	 * Delete a webhook by its ID (mark as inactive)
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for deleting a webhook
 	 * @param {string} params.id - The ID of the webhook 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 response from the server
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async deleteWebhook({ id, options = {} }) {
 		this.client._require({ id });

package/src/domains/voice/Analytics.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} VoiceAnalyticsFilters
  * @property {string} [dateFrom] - ISO-8601 lower bound on call start time.
@@ -61,8 +67,8 @@ export class Analytics {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
 	 * @param {VoiceAnalyticsFilters} [params.filters] - Optional filters. Summary tiles honor every filter except `direction`; breakdowns honor all filters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ success, range, outbound: VoiceDirectionSummary, inbound: VoiceDirectionSummary, byDate: VoiceBreakdownBucket[], byNumber: VoiceBreakdownBucket[], byCarrier: VoiceBreakdownBucket[], byChannel: VoiceBreakdownBucket[] }` (byChannel = per-callSource breakdown).
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, range, outbound: VoiceDirectionSummary, inbound: VoiceDirectionSummary, byDate: VoiceBreakdownBucket[], byNumber: VoiceBreakdownBucket[], byCarrier: VoiceBreakdownBucket[], byChannel: VoiceBreakdownBucket[] }` (byChannel = per-callSource breakdown).
 	 */
 	async get({ filters = {}, options = {} } = {}) {
 		const query = new URLSearchParams();

package/src/domains/voice/CallLogs.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} ListCallLogsFilters
  * @property {number} [page] - 1-indexed page (default 1).
@@ -40,8 +46,8 @@ export class CallLogs {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
 	 * @param {ListCallLogsFilters} [params.filters] - Optional filters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ success, data: [...call logs], meta: { total, page, limit, totalPages } }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: [...call logs], meta: { total, page, limit, totalPages } }`.
 	 */
 	async list({ filters = {}, options = {} } = {}) {
 		const query = new URLSearchParams();
@@ -59,9 +65,9 @@ export class CallLogs {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The call log UUID or callId.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ success, data: { ...call log } }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: { ...call log } }`.
 	 */
 	async get({ id, options = {} }) {
 		this.client._require({ id });
@@ -76,9 +82,9 @@ export class CallLogs {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The call log UUID or callId.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ success, data: { callId, url, expiresIn } }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: { callId, url, expiresIn } }`.
 	 */
 	async getRecording({ id, options = {} }) {
 		this.client._require({ id });
@@ -93,9 +99,9 @@ export class CallLogs {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The call log UUID or callId.
 	 * @param {boolean} [params.read=true] - true = read, false = unread.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ success, data: { id, voicemailReadAt } }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: { id, voicemailReadAt } }`.
 	 */
 	async markVoicemailRead({ id, read = true, options = {} }) {
 		this.client._require({ id });

package/src/domains/voice/Calls.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateCallData
  * @property {string} to - Destination phone number in E.164 format (e.g. "+15551234567") or SIP URI.
@@ -48,9 +54,9 @@ export class Calls {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {CreateCallData} params.callData - The call to place.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If callData is missing.
-	 * @returns {Promise<Object>} The created call: `{ call_id, status, direction, from, to, created_at }`.
+	 * @returns {Promise<SdkResponse<any>>} The created call: `{ call_id, status, direction, from, to, created_at }`.
 	 */
 	async create({ callData, options = {} }) {
 		this.client._require({ callData });
@@ -63,8 +69,8 @@ export class Calls {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
 	 * @param {ListCallsFilters} [params.filters] - Optional filters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ calls: [...], total, page, limit }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ calls: [...], total, page, limit }`.
 	 */
 	async list({ filters = {}, options = {} } = {}) {
 		const query = new URLSearchParams();
@@ -82,9 +88,9 @@ export class Calls {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The call log UUID (the value returned as `call_id` from `create`).
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} The call log.
+	 * @returns {Promise<SdkResponse<any>>} The call log.
 	 */
 	async get({ id, options = {} }) {
 		this.client._require({ id });
@@ -99,9 +105,9 @@ export class Calls {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The call log UUID.
 	 * @param {"NORMAL"|"BUSY"|"NO_ANSWER"|"REJECTED"} [params.reason] - Hangup reason recorded on the call log. Defaults to NORMAL.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ success: boolean, message: string }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ success: boolean, message: string }`.
 	 */
 	async hangup({ id, reason, options = {} }) {
 		this.client._require({ id });

package/src/domains/voice/GlobalVoiceSettings.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} GlobalVoiceSettingsData
  * @property {string[]} [acceptedRegions] - Accepted regions as country calling codes; empty = all allowed.
@@ -23,8 +29,8 @@ export class GlobalVoiceSettings {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ success, data: { accountId, acceptedRegions, maxSpendPerMinute, e911Enabled, ... } | null }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: { accountId, acceptedRegions, maxSpendPerMinute, e911Enabled, ... } | null }`.
 	 */
 	async get({ options = {} } = {}) {
 		return this.client(`/voice/api/v1/global-voice-settings`, { method: "GET", ...options });
@@ -37,9 +43,9 @@ export class GlobalVoiceSettings {
 	 * @roles api, admin, developer
 	 * @param {Object} params - Request parameters.
 	 * @param {GlobalVoiceSettingsData} params.settingsData - Fields to set.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If settingsData is missing.
-	 * @returns {Promise<Object>} `{ success, data: { ...settings } }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ success, data: { ...settings } }`.
 	 */
 	async update({ settingsData, options = {} }) {
 		this.client._require({ settingsData });

package/src/domains/voice/ProgrammableVoiceProfiles.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateProgrammableVoiceProfileData
  * @property {string} name - Profile name (required).
@@ -49,8 +55,8 @@ export class ProgrammableVoiceProfiles {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ profiles: [...] }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ profiles: [...] }`.
 	 */
 	async list({ options = {} } = {}) {
 		return this.client(`/voice/api/v1/programmable-voice-profiles`, { method: "GET", ...options });
@@ -62,9 +68,9 @@ export class ProgrammableVoiceProfiles {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async get({ id, options = {} }) {
 		this.client._require({ id });
@@ -78,9 +84,9 @@ export class ProgrammableVoiceProfiles {
 	 * @roles api, admin, developer
 	 * @param {Object} params - Request parameters.
 	 * @param {CreateProgrammableVoiceProfileData} params.profileData - The profile to create.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If profileData is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async create({ profileData, options = {} }) {
 		this.client._require({ profileData });
@@ -94,9 +100,9 @@ export class ProgrammableVoiceProfiles {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
 	 * @param {UpdateProgrammableVoiceProfileData} params.updateData - Fields to update.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or updateData is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async update({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -110,9 +116,9 @@ export class ProgrammableVoiceProfiles {
 	 * @roles api, admin, developer
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async toggleActive({ id, options = {} }) {
 		this.client._require({ id });
@@ -127,9 +133,9 @@ export class ProgrammableVoiceProfiles {
 	 * @roles api, admin, developer
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ message: string }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ message: string }`.
 	 */
 	async delete({ id, options = {} }) {
 		this.client._require({ id });
@@ -146,9 +152,9 @@ export class ProgrammableVoiceProfiles {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
 	 * @param {string} params.e164 - The phone number in E.164 (a leading "+" is optional).
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or e164 is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async assignNumber({ id, e164, options = {} }) {
 		this.client._require({ id, e164 });
@@ -167,9 +173,9 @@ export class ProgrammableVoiceProfiles {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The profile UUID.
 	 * @param {string} params.e164 - The phone number in E.164 (a leading "+" is optional).
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or e164 is missing.
-	 * @returns {Promise<Object>} `{ profile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ profile: {...} }`.
 	 */
 	async unassignNumber({ id, e164, options = {} }) {
 		this.client._require({ id, e164 });

package/src/domains/voice/SipProfiles.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateSipProfileData
  * @property {string} name - Profile name (required).
@@ -37,8 +43,8 @@ export class SipProfiles {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ sipProfiles: [...] }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfiles: [...] }`.
 	 */
 	async list({ options = {} } = {}) {
 		return this.client(`/voice/sip-profiles`, { method: "GET", ...options });
@@ -51,9 +57,9 @@ export class SipProfiles {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfile: {...} }`.
 	 */
 	async get({ id, options = {} }) {
 		this.client._require({ id });
@@ -70,9 +76,9 @@ export class SipProfiles {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ password: string|null }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ password: string|null }`.
 	 */
 	async getPassword({ id, options = {} }) {
 		this.client._require({ id });
@@ -86,8 +92,8 @@ export class SipProfiles {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} [params] - Request parameters.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} `{ transports: [{ transport, address, port }, ...] }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ transports: [{ transport, address, port }, ...] }`.
 	 */
 	async getTransports({ options = {} } = {}) {
 		return this.client(`/voice/sip-profiles/transports`, { method: "GET", ...options });
@@ -102,9 +108,9 @@ export class SipProfiles {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {CreateSipProfileData} params.profileData - The SIP profile to create.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If profileData is missing.
-	 * @returns {Promise<Object>} `{ sipProfile: {...}, password: string, sipServer: string, message: string }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfile: {...}, password: string, sipServer: string, message: string }`.
 	 */
 	async create({ profileData, options = {} }) {
 		this.client._require({ profileData });
@@ -119,9 +125,9 @@ export class SipProfiles {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
 	 * @param {UpdateSipProfileData} params.updateData - Fields to update.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or updateData is missing.
-	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfile: {...} }`.
 	 */
 	async update({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -136,9 +142,9 @@ export class SipProfiles {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ message: string }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ message: string }`.
 	 */
 	async delete({ id, options = {} }) {
 		this.client._require({ id });
@@ -156,9 +162,9 @@ export class SipProfiles {
 	 * @param {string} params.id - The SIP profile UUID.
 	 * @param {string} [params.e164] - The phone number in E.164 to assign (preferred).
 	 * @param {string} [params.phoneNumberId] - Legacy: a voice-backend phone number UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing, or neither e164 nor phoneNumberId is provided.
-	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfile: {...} }`.
 	 */
 	async assignNumber({ id, e164, phoneNumberId, options = {} }) {
 		this.client._require({ id });
@@ -180,9 +186,9 @@ export class SipProfiles {
 	 * @param {string} params.id - The SIP profile UUID.
 	 * @param {string} [params.e164] - The phone number in E.164 to unassign (preferred).
 	 * @param {string} [params.phoneNumberId] - Legacy: a voice-backend phone number UUID.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing, or neither e164 nor phoneNumberId is provided.
-	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipProfile: {...} }`.
 	 */
 	async unassignNumber({ id, e164, phoneNumberId, options = {} }) {
 		this.client._require({ id });