@signalhousellc/sdk 1.0.66 → 1.0.68

package/src/domains/Subscriptions.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Subscriptions {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -11,8 +17,8 @@ export class Subscriptions {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for getting subscription templates
 				 * @param {string} [params.templateId] - The ID of a specific template to retrieve (optional)
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - The subscription templates returned from the server
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - The subscription templates returned from the server
 				 */
 				getTemplates: async ({ templateId, options = {} }) => {
 					const filters = { templateId };
@@ -26,9 +32,9 @@ export class Subscriptions {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for creating a subscription template
 				 * @param {Object} params.templateData - The data for the new subscription template, including required fields such as templateName and monthlyFee
-				 * @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 templateData parameter is missing or if required fields within templateData are missing
-				 * @returns {Promise<Object>} - The created subscription template object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The created subscription template object returned from the server
 				 */
 				createTemplate: async ({ templateData, options = {} }) => {
 					this.client._require({ templateData: templateData });
@@ -42,9 +48,9 @@ export class Subscriptions {
 				 * @param {Object} params - The parameters for updating a subscription template
 				 * @param {string} params.templateId - The ID of the subscription template to update
 				 * @param {Object} params.templateData - The data for the subscription template, including fields such as templateName and monthlyFee
-				 * @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 templateId or templateData parameter is missing
-				 * @returns {Promise<Object>} - The updated subscription template object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The updated subscription template object returned from the server
 				 */
 				updateTemplate: async ({ templateId, templateData, options = {} }) => {
 					this.client._require({ templateId, templateData });
@@ -58,9 +64,9 @@ export class Subscriptions {
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for deleting a subscription template
 				 * @param {string} params.templateId - The ID of the subscription template 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 templateId parameter is missing
-				 * @returns {Promise<Object>} - The deleted subscription template object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The deleted subscription template object returned from the server
 				 */
 				deleteTemplate: async ({ templateId, options = {} }) => {
 					this.client._require({ templateId });
@@ -75,9 +81,9 @@ export class Subscriptions {
 				 * @param {Object} params - The parameters for creating a custom subscription
 				 * @param {string} params.groupId - The ID of the group to create the custom subscription for
 				 * @param {Object} params.subscriptionData - The data for the custom subscription, including required fields such as subscriptionName and monthlyFee
-				 * @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 or subscriptionData parameter is missing or if required fields within subscriptionData are missing
-				 * @returns {Promise<Object>} - The created custom subscription object returned from the server
+				 * @returns {Promise<SdkResponse<any>>} - The created custom subscription object returned from the server
 				 */
 				createCustomSubscription: async ({ groupId, subscriptionData, options = {} }) => {
 					this.client._require({ groupId, subscriptionData });
@@ -95,8 +101,8 @@ export class Subscriptions {
 	 * @param {Object} params - The parameters for getting subscription history
 	 * @param {string} params.groupId - The ID of the group to get subscription history for
 	 * @param {boolean} [params.onlyActive] - Whether to only include active subscriptions
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - The subscription history returned from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - The subscription history returned from the server
 	 */
 	async getSubscriptions({ groupId, onlyActive, options = {} }) {
 		const filters = { groupId, onlyActive };
@@ -111,9 +117,9 @@ export class Subscriptions {
 	 * @param {Object} params - The parameters for subscribing a group to a template
 	 * @param {string} params.groupId - The ID of the group to subscribe
 	 * @param {string} params.templateId - The ID of the template to subscribe the group to
-	 * @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 or templateId parameter is missing
-	 * @returns {Promise<Object>} - The subscription object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The subscription object returned from the server
 	 */
 	async subscribe({ groupId, templateId, options = {} }) {
 		this.client._require({ groupId, templateId });
@@ -128,9 +134,9 @@ export class Subscriptions {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for unsubscribing a group from a template
 	 * @param {string} params.groupId - The ID of the group to unsubscribe
-	 * @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 subscription object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The subscription object returned from the server
 	 */
 	async unsubscribe({ groupId, options = {} }) {
 		this.client._require({ groupId });

package/src/domains/Tickets.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Tickets {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -11,8 +17,8 @@ export class Tickets {
 				 * @async
 				 * @roles signalhouse
 				 * @param {Object} [params] - Optional parameters
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - Jira form metadata
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - Jira form metadata
 				 */
 				getJiraMetadata: async ({ options = {} } = {}) => {
 					return this.client(`/admin/ticket/jira/metadata`, { method: "GET", ...options });
@@ -24,8 +30,8 @@ export class Tickets {
 				 * @roles signalhouse
 				 * @param {Object} [params]
 				 * @param {string} [params.query] - Optional epic summary/key filter
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - `{ epics: Array<{ id, key, summary }> }`
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ epics: Array<{ id, key, summary }> }`
 				 */
 				searchJiraEpics: async ({ query, options = {} } = {}) => {
 					const queryString = this.client._getQueryString({ query });
@@ -38,8 +44,8 @@ export class Tickets {
 				 * @roles signalhouse
 				 * @param {Object} [params]
 				 * @param {string} [params.query] - Optional issue summary/key filter
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - `{ issues: Array<{ id, key, summary }> }`
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ issues: Array<{ id, key, summary }> }`
 				 */
 				searchJiraParentIssues: async ({ query, options = {} } = {}) => {
 					const queryString = this.client._getQueryString({ query });
@@ -52,8 +58,8 @@ export class Tickets {
 				 * @roles signalhouse
 				 * @param {Object} [params]
 				 * @param {string} [params.query] - Partial name or email
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - `{ users: Array<{ accountId, displayName, emailAddress }> }`
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ users: Array<{ accountId, displayName, emailAddress }> }`
 				 */
 				searchJiraAssignees: async ({ query, options = {} } = {}) => {
 					const queryString = this.client._getQueryString({ query });
@@ -66,8 +72,8 @@ export class Tickets {
 				 * @roles signalhouse
 				 * @param {Object} [params]
 				 * @param {string} [params.query] - Partial label text
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - `{ labels: string[] }`
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - `{ labels: string[] }`
 				 */
 				searchJiraLabels: async ({ query, options = {} } = {}) => {
 					const queryString = this.client._getQueryString({ query });
@@ -80,9 +86,9 @@ export class Tickets {
 				 * @roles signalhouse
 				 * @param {Object} params
 				 * @param {Object} params.data - Create payload (groupId, issueTypeId, priorityId, summary required)
-				 * @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 data parameter is missing
-				 * @returns {Promise<Object>} - Created ticket summary (key, browseUrl, reporter, etc.)
+				 * @returns {Promise<SdkResponse<any>>} - Created ticket summary (key, browseUrl, reporter, etc.)
 				 */
 				createJiraTicket: async ({ data, options = {} }) => {
 					this.client._require({ data });

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)
@@ -61,8 +67,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 +81,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 +105,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 +120,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 +135,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 +151,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 +167,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 +182,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 +195,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 +211,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;
@@ -5,7 +11,9 @@ export class Webhooks {
 	}
 
 	/**
-	 * Get a list of webhooks with optional filters
+	 * Get a list of webhooks with optional filters. Each returned endpoint carries `hasSigningSecret`
+	 * (boolean) instead of the signing secret itself — the plaintext secret is only ever returned once,
+	 * from `createWebhook`, and is never exposed again on any read (SHGHL-2944).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for getting webhooks
@@ -15,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 };
@@ -25,14 +33,19 @@ export class Webhooks {
 	}
 
 	/**
-	 * Create a new webhook with the specified data
+	 * Create a new webhook with the specified data. The response includes a `signingSecret` — a
+	 * 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).
 	 * @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
+	 * @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 });
@@ -40,15 +53,17 @@ export class Webhooks {
 	}
 
 	/**
-	 * Update an existing webhook with the specified data
+	 * 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).
 	 * @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 });
@@ -62,9 +77,9 @@ export class Webhooks {
 	 * @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 });