@signalhousellc/sdk 1.0.51 → 1.0.53

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",
   "exports": {
-    ".": "./src/SignalHouseSDK.js"
+    ".": "./src/SignalHouseSDK.js",
+    "./voice-browser": "./src/domains/voice/browser/index.js"
   },
   "files": [
     "src/",
@@ -15,5 +16,13 @@
   "license": "ISC",
   "dependencies": {
     "axios": "^1.13.5"
+  },
+  "peerDependencies": {
+    "jssip": "^3.13.0"
+  },
+  "peerDependenciesMeta": {
+    "jssip": {
+      "optional": true
+    }
   }
 }

package/src/SignalHouseSDK.js

@@ -22,6 +22,7 @@ import { Subscriptions } from "./domains/Subscriptions.js";
 import { Users } from "./domains/Users.js";
 import { Notifications } from "./domains/Notifications.js";
 import { Webhooks } from "./domains/Webhooks.js";
+import { Voice } from "./domains/Voice.js";
 
 export class SignalHouseSDK {
 	/**
@@ -29,6 +30,7 @@ export class SignalHouseSDK {
 	 * @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.
 	 * @throws {Error} Throws an error if the API key or base URL is missing from the configuration
 	 * @returns {SignalHouseSDK} An instance of the SignalHouseSDK
 	 */
@@ -66,6 +68,9 @@ export class SignalHouseSDK {
 		this.users = new Users(client, this.enableAdmin);
 		this.notifications = new Notifications(client, this.enableAdmin);
 		this.webhooks = new Webhooks(client, this.enableAdmin);
+		// Voice domain targets the voice-backend service under /voice. Available
+		// like any other domain; gating (if any) will be decided later.
+		this.voice = new Voice(client, this.enableAdmin);
 	}
 
 	/**

package/src/domains/Auth.js

@@ -58,6 +58,37 @@ export class Auth {
 		return this.client(`/auth/verify-email`, { method: "POST", body: { token }, ...options });
 	}
 
+	/**
+	 * Request a password-reset link be emailed to the given address (public). Always resolves
+	 * successfully regardless of whether an account exists for the email, so it cannot be used to
+	 * enumerate registered emails.
+	 * @async
+	 * @roles public
+	 * @param {Object} params
+	 * @param {string} params.email - The email address to send a reset link to
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} The response from the server ({ success: true })
+	 */
+	async forgotPassword({ email, options = {} }) {
+		this.client._require({ email });
+		return this.client(`/auth/forgot-password`, { method: "POST", body: { email }, ...options });
+	}
+
+	/**
+	 * Reset a password using the single-use token from a password-reset email link (public)
+	 * @async
+	 * @roles public
+	 * @param {Object} params
+	 * @param {string} params.token - The single-use reset token from the email link
+	 * @param {string} params.password - The new password to set (min 8 characters)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} The response from the server ({ success: true })
+	 */
+	async resetPasswordWithToken({ token, password, options = {} }) {
+		this.client._require({ token, password });
+		return this.client(`/auth/reset-password`, { method: "POST", body: { token, password }, ...options });
+	}
+
 	/**
 	 * Resend the account verification email to the authenticated caller
 	 * @async
@@ -115,4 +146,19 @@ export class Auth {
 	async logoutAll({ options = {} } = {}) {
 		return this.client(`/auth/logout-all`, { method: "POST", ...options });
 	}
+
+	/**
+	 * Mint a single-use, short-lived external-link token for the authenticated caller. The token is
+	 * handed to the GHL/Shopify backend so it can link the caller's existing V2 group to its tenant.
+	 * @async
+	 * @roles admin, developer, billing, user
+	 * @param {Object} params
+	 * @param {string} params.product - The external system to link to ("ghl" or "shopify")
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<Object>} The response from the server ({ token })
+	 */
+	async requestExternalLinkToken({ product, options = {} }) {
+		this.client._require({ product });
+		return this.client(`/auth/external-link-token`, { method: "POST", body: { product }, ...options });
+	}
 }

package/src/domains/Brands.js

@@ -53,6 +53,42 @@
  * @property {string} [altBusinessIdType] - The type of the alternative business identifier ("NONE", "DUNS", "LEI", "GIIN")
  * @property {string} [brandRelationship] - Not in use - reserved for future use
  * @property {string} [businessContactEmail] - The email address of the business contact for the brand (required if entityType is PUBLIC_PROFIT or NON_PROFIT)
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free brand. Optional sub-fields: legalEntityType, businessRegistrationType, taxId, countryCode, supportPhone, taxIdIssuingCountry, businessDBA. (Toll-Free brands sync to Infobip; only DCA_PENDING/DCA_ACTIVE brands are editable and subgroupId is immutable.)
+ */
+
+/**
+ * @typedef {Object} TollFreeBrandDetails
+ * @property {string} businessRegistrationType - The business registration type (required, one of EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER)
+ * @property {string} legalEntityType - The legal entity type (required, one of PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR)
+ * @property {string} taxId - The business tax identifier (required, at most 50 characters)
+ * @property {string} countryCode - The business country code (required, 2-letter ISO code)
+ * @property {string} supportPhone - The customer-support phone number (required, at most 20 characters)
+ * @property {string} [taxIdIssuingCountry] - The country that issued the tax ID (optional, 2-letter ISO code)
+ * @property {string} [businessDBA] - The business "doing business as" name (optional, at most 255 characters)
+ */
+
+/**
+ * @typedef {Object} CreateTollFreeBrandData
+ * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
+ * @property {string} displayName - The display name for the brand (required, at most 255 characters)
+ * @property {string} companyName - The company name for the brand (required, at most 255 characters)
+ * @property {string} street - The street address of the primary contact for the brand (required, at most 255 characters)
+ * @property {string} city - The city of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} state - The state of the primary contact for the brand (required, at most 20 characters; must be a valid 2-letter US state code when country is "US")
+ * @property {string} postalCode - The postal code of the primary contact for the brand (required, at most 10 characters)
+ * @property {string} email - The email address of the primary contact for the brand (required, valid email, at most 100 characters)
+ * @property {string} firstName - The first name of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} lastName - The last name of the primary contact for the brand (required, at most 100 characters)
+ * @property {string} website - The website URL for the brand (required, valid URL, at most 255 characters)
+ * @property {TollFreeBrandDetails} tollFree - The Toll-Free brand details (required)
+ * @property {string} [referenceId] - A unique reference for the brand (optional, at most 50 characters)
+ * @property {Array<string>} [tag] - An array of tags to associate with the brand (optional)
+ * @property {boolean} [mock] - Whether to create the brand in the mock environment (for testing purposes only)
+ * @property {string} [optInLink] - A URL linking to the opt-in flow for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the brand (optional, valid URL, at most 255 characters)
+ * @property {string} [landingId] - The ID of the landing page associated with the brand (optional)
+ * @property {string} [country] - The country code of the primary contact for the brand (optional, 2-letter code; when "US", state must be a valid 2-letter US state code)
  */
 
 export class Brands {
@@ -73,11 +109,12 @@ export class Brands {
 	 * @param {number} [params.page] - The page number for pagination
 	 * @param {number} [params.limit] - The number of items per page
 	 * @param {string} [params.status] - The status of the brand to filter by (PENDING_CREATION, PENDING_APPROVAL, UNVERIFIED, VERIFIED, VETTED_VERIFIED, PENDING_DELETE, DELETED)
+	 * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC" or "TOLL_FREE")
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array>} The response from the server
 	 */
-	async getBrands({ id, subgroupId, groupId, page, limit, status, options = {} }) {
-		const filters = { id, subgroupId, groupId, page, limit, status };
+	async getBrands({ id, subgroupId, groupId, page, limit, status, registrationType, options = {} }) {
+		const filters = { id, subgroupId, groupId, page, limit, status, registrationType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/brand${queryString}`, { method: "GET", ...options });
 	}
@@ -113,6 +150,21 @@ export class Brands {
 		return this.client(`/brand`, { method: "POST", body: brandData, ...options });
 	}
 
+	/**
+	 * Create a new Toll-Free (TFN) brand
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for creating the toll-free brand
+	 * @param {CreateTollFreeBrandData} params.brandData - The data for the toll-free brand to be created (see CreateTollFreeBrandData typedef for details; TFN-specific fields live under brandData.tollFree, and registrationType is forced server-side by the route)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the brandData parameter is missing
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async createTollFreeBrand({ brandData, options = {} }) {
+		this.client._require({ brandData });
+		return this.client(`/brand/toll-free`, { method: "POST", body: brandData, ...options });
+	}
+
 	/**
 	 * Transfer one or more brands to a different subgroup
 	 * @async

package/src/domains/Campaigns.js

@@ -64,6 +64,41 @@
  * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [embeddedLinkSample] - A sample of the embedded link used in the campaign (optional, must be at most 255 characters if provided)
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (≤500), exampleMessage, customerCareEmail, optInImageURLs, optIns, multiNumberReason (≤500)). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
+ */
+
+/**
+ * @typedef {Object} TollFreeOptIn
+ * @property {string} [callToAction] - The opt-in call-to-action text for this channel (optional, at most 2048 characters)
+ * @property {string} [url] - The opt-in web URL (web channel only, optional, at most 2048 characters)
+ * @property {Array<string>} [keywords] - The opt-in keywords (keyword channel only, optional)
+ */
+
+/**
+ * @typedef {Object} TollFreeCampaignDetails
+ * @property {string} useCase - The Toll-Free use case (required, e.g. TWO_FA, GENERAL_MARKETING, HEALTHCARE, MIXED — one of the Toll-Free use-case values)
+ * @property {string} messageVolume - The estimated monthly message volume tier (required, one of TEN, HUNDRED, THOUSAND, TEN_THOUSAND, HUNDRED_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, FIVE_HUNDRED_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, ONE_MILLION, FIVE_MILLION, TEN_MILLION_PLUS)
+ * @property {string} programSummary - A summary of the messaging program (required, at most 500 characters)
+ * @property {string} exampleMessage - An example message (required, at most 4096 characters; stored verbatim, no STOP/HELP appended by the server)
+ * @property {string} customerCareEmail - A customer-care contact email (required, valid email)
+ * @property {Array<string>} optInImageURLs - URLs to opt-in proof images (required, at least one, each at most 2048 characters)
+ * @property {Object} [optIns] - Opt-in method details. Each channel is optional.
+ * @property {TollFreeOptIn} [optIns.verbal] - Verbal opt-in details
+ * @property {TollFreeOptIn} [optIns.web] - Online (web) opt-in details
+ * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
+ * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
+ * @property {string} [multiNumberReason] - Internally-stored reason the customer requested more than one Toll-Free number on the campaign (optional, at most 500 characters). Required when more than one phone number is assigned; captured for Signal House review only and never sent to the carrier.
+ */
+
+/**
+ * @typedef {Object} CreateTollFreeCampaignData
+ * @property {string} brandId - The ID of the Toll-Free brand associated with the campaign (required, at least 7 characters)
+ * @property {TollFreeCampaignDetails} tollFree - The Toll-Free campaign details (required)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (optional, at most 2048 characters)
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (optional, at most 2048 characters)
+ * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
+ * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
+ * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, at least 1 and at most 5, each at least 10 digits and digits only). Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
  */
 
 export class Campaigns {
@@ -133,11 +168,12 @@ export class Campaigns {
 	 * @param {string} [params.search] - Search term to filter campaigns by campaignId or brandId
 	 * @param {string} [params.sortBy] - Field to sort by (e.g. "createdAt", "campaignId", "brandId", "groupId", "subgroupId", "usecase", "status")
 	 * @param {string} [params.sortOrder] - Sort direction ("asc" or "desc")
+	 * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC" or "TOLL_FREE")
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
 	 */
-	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, options = {} }) {
-		const filters = { id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder };
+	async getCampaigns({ id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, registrationType, options = {} }) {
+		const filters = { id, brandId, subgroupId, groupId, page, limit, status, search, sortBy, sortOrder, registrationType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/campaign${queryString}`, { method: "GET", ...options });
 	}
@@ -157,6 +193,21 @@ export class Campaigns {
 		return this.client(`/campaign`, { method: "POST", body: campaignData, ...options });
 	}
 
+	/**
+	 * Create a new Toll-Free (TFN) campaign and submit it for Signal House review
+	 * @async
+	 * @roles api, admin, developer, user
+	 * @param {Object} params - The parameters for creating the toll-free campaign
+	 * @param {CreateTollFreeCampaignData} params.campaignData - The data for the toll-free campaign to be created (see CreateTollFreeCampaignData typedef for details)
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the campaignData parameter is missing
+	 * @returns {Promise<Object>} The response from the server
+	 */
+	async createTollFreeCampaign({ campaignData, options = {} }) {
+		this.client._require({ campaignData });
+		return this.client(`/campaign/toll-free`, { method: "POST", body: campaignData, ...options });
+	}
+
 	/**
 	 * Update an existing campaign
 	 * @async

package/src/domains/Groups.js

@@ -52,6 +52,30 @@ export class Groups {
 					const safeGroupId = encodeURIComponent(groupId);
 					return this.client(`/group/${safeGroupId}`, { method: "DELETE", ...options });
 				},
+
+				/**
+				 * Link an external tenant (GHL/Shopify) to a V2 group (server-to-server). Exchanges a
+				 * single-use link token for a canonical group, adopting an empty portal group, repointing
+				 * to an existing group, or flagging for manual review.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for linking an external account
+				 * @param {string} params.linkToken - The single-use external-link token minted by the portal user
+				 * @param {string} params.externalSystem - The external system ("ghl" or "shopify")
+				 * @param {string} params.externalId - The external tenant identifier
+				 * @param {string} [params.existingGroupId] - An existing V2 group ID to repoint to, if any
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if linkToken, externalSystem, or externalId is missing
+				 * @returns {Promise<Object>} - The link outcome ({ status, canonicalGroupId, ... })
+				 */
+				linkExternal: async ({ linkToken, externalSystem, externalId, existingGroupId, options = {} }) => {
+					this.client._require({ linkToken, externalSystem, externalId });
+					return this.client(`/group/link-external`, {
+						method: "POST",
+						body: { linkToken, externalSystem, externalId, ...(existingGroupId ? { existingGroupId } : {}) },
+						...options,
+					});
+				},
 			};
 		}
 	}

package/src/domains/Numbers.js

@@ -111,6 +111,45 @@ export class Numbers {
 		return this.client(`/number`, { method: "POST", body: { phoneNumbers, subgroupId }, ...options });
 	}
 
+	/**
+	 * Purchase one or more Toll-Free numbers via the asynchronous resource-request flow.
+	 *
+	 * Toll-Free numbers are ordered by quantity (not picked individually) and provisioned asynchronously;
+	 * per-number completion is delivered via webhook/polling, not in this response. The returned `orderId`
+	 * can be polled with {@link Numbers#getTollFreeOrderStatus} for the order's outcome.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for purchasing toll-free numbers
+	 * @param {number} params.quantity - The number of toll-free numbers to purchase (1-10)
+	 * @param {string} params.subgroupId - The subgroup the purchased numbers are assigned to
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the quantity or subgroupId parameter is missing
+	 * @returns {Promise<Object>} A promise that resolves to `{ message, orderId }` once the request is queued.
+	 */
+	async purchaseTollFreeNumbers({ quantity, subgroupId, options = {} }) {
+		this.client._require({ quantity, subgroupId });
+		return this.client(`/number/toll-free`, { method: "POST", body: { quantity, subgroupId }, ...options });
+	}
+
+	/**
+	 * Read the outcome of a Toll-Free number purchase by the `orderId` returned from
+	 * {@link Numbers#purchaseTollFreeNumbers}. Reports per-number status as ready / provisioning / failed
+	 * counts (plus failure reasons) so a client can poll until the order reaches a terminal state. The
+	 * provisioned numbers themselves appear in the regular numbers list as they materialize.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for reading the order status
+	 * @param {string} params.orderId - The order id returned by `purchaseTollFreeNumbers`
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the orderId parameter is missing
+	 * @returns {Promise<Object>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }] }`.
+	 */
+	async getTollFreeOrderStatus({ orderId, options = {} }) {
+		this.client._require({ orderId });
+		const safeOrderId = encodeURIComponent(orderId);
+		return this.client(`/number/toll-free/order/${safeOrderId}`, { method: "GET", ...options });
+	}
+
 	/**
 	 * Update an existing phone number's details (e.g., setting a friendly name)
 	 * @async

package/src/domains/Voice.js

@@ -0,0 +1,26 @@
+import { SipTrunks } from "./voice/SipTrunks.js";
+import { SipProfiles } from "./voice/SipProfiles.js";
+import { Calls } from "./voice/Calls.js";
+import { Tokens } from "./voice/Tokens.js";
+
+/**
+ * Voice domain — wraps the voice-backend service (mounted under /voice on the
+ * platform host). Groups all voice-service sub-resources under a single
+ * namespace, accessed via `sdk.voice.*`.
+ *
+ * Sub-resources:
+ * - `sdk.voice.sipTrunks`   — SIP trunk (peer-to-peer connections to PBX/carrier).
+ * - `sdk.voice.sipProfiles` — SIP profile / endpoint (single registerable UA).
+ * - `sdk.voice.calls`       — Outbound call origination + call log queries.
+ * - `sdk.voice.tokens`      — Mint ephemeral SIP credentials for the browser voice SDK.
+ */
+export class Voice {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+		this.sipTrunks = new SipTrunks(client, enableAdmin);
+		this.sipProfiles = new SipProfiles(client, enableAdmin);
+		this.calls = new Calls(client, enableAdmin);
+		this.tokens = new Tokens(client, enableAdmin);
+	}
+}

package/src/domains/voice/Calls.js

@@ -0,0 +1,112 @@
+/**
+ * @typedef {Object} CreateCallData
+ * @property {string} to - Destination phone number in E.164 format (e.g. "+15551234567") or SIP URI.
+ * @property {string} from - Caller ID to present on the outbound leg. Must be an account-owned phone number when not using a SIP trunk.
+ * @property {string} [sip_trunk_id] - Route via a configured SIP trunk. Mutually exclusive with `sip_profile_id` and `to_identity` for the trunk path.
+ * @property {string} [sip_profile_id] - Two-leg-with-bridge: ring this persistent SIP profile first, then dial `to` and bridge. Mutually exclusive with `to_identity`.
+ * @property {string} [to_identity] - Two-leg-with-bridge: ring the SDK-registered identity by logical name (the value passed to `tokens.create({identity})`), then dial `to` and bridge. Mutually exclusive with `sip_profile_id`.
+ * @property {string} [answer_url] - Webhook URL fetched on call answer; returns call-control instructions.
+ * @property {"GET"|"POST"} [answer_method] - HTTP method for `answer_url`. Defaults to POST.
+ * @property {string} [status_callback] - Webhook URL for call status updates (QUEUED, RINGING, ANSWERED, COMPLETED, FAILED).
+ * @property {"GET"|"POST"} [status_callback_method] - HTTP method for `status_callback`. Defaults to POST.
+ * @property {boolean} [recording_enabled] - Record both legs of the call. Defaults to false.
+ * @property {boolean} [transcription_enabled] - Transcribe the recording. Defaults to false.
+ * @property {string} [ivr_flow_id] - Route the call into an AI IVR flow on answer instead of webhook control.
+ * @property {Object} [metadata] - Free-form metadata persisted on the call log.
+ */
+
+/**
+ * @typedef {Object} ListCallsFilters
+ * @property {number} [page] - Page number (1-indexed). Defaults to 1.
+ * @property {number} [limit] - Page size (1-100). Defaults to 20.
+ * @property {"QUEUED"|"RINGING"|"IN_PROGRESS"|"COMPLETED"|"FAILED"|"BUSY"|"NO_ANSWER"|"CANCELED"} [status] - Filter by call status.
+ * @property {"INBOUND"|"OUTBOUND"} [direction] - Filter by call direction.
+ * @property {string} [from] - Filter by caller number.
+ * @property {string} [to] - Filter by destination number.
+ * @property {string} [date_from] - ISO-8601 lower bound on start_time.
+ * @property {string} [date_to] - ISO-8601 upper bound on start_time.
+ */
+
+/**
+ * Voice calls. REST API for placing outbound calls and inspecting call logs.
+ * Wraps voice-backend's `/voice/v1/calls` surface. Accessed via `sdk.voice.calls`.
+ *
+ * Origination modes:
+ * - **Single-leg** (no trunk/profile/identity): Twilio-style direct outbound — dial `to` from caller-ID `from`. Customer's `from` must be an account-owned number.
+ * - **SIP trunk** (`sip_trunk_id`): Route via a configured trunk; the trunk's auth/ACL governs caller-ID rules.
+ * - **Two-leg-with-bridge** (`sip_profile_id` OR `to_identity`): Ring the SDK-registered endpoint first, then dial `to` and bridge. `to_identity` resolves to the most recently-minted unexpired ephemeral identity for that name.
+ */
+export class Calls {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Create an outbound call.
+	 * @async
+	 * @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.
+	 * @throws {Error} If callData is missing.
+	 * @returns {Promise<Object>} The created call: `{ call_id, status, direction, from, to, created_at }`.
+	 */
+	async create({ callData, options = {} }) {
+		this.client._require({ callData });
+		return this.client(`/voice/v1/calls`, { method: "POST", body: callData, ...options });
+	}
+
+	/**
+	 * List call logs for the current account, paginated and filterable.
+	 * @async
+	 * @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 }`.
+	 */
+	async list({ filters = {}, options = {} } = {}) {
+		const query = new URLSearchParams();
+		for (const [k, v] of Object.entries(filters)) {
+			if (v !== undefined && v !== null && v !== "") query.set(k, String(v));
+		}
+		const qs = query.toString();
+		const path = qs ? `/voice/v1/calls?${qs}` : `/voice/v1/calls`;
+		return this.client(path, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single call log by ID.
+	 * @async
+	 * @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.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} The call log.
+	 */
+	async get({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/v1/calls/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Hang up an in-progress call.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @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.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ success: boolean, message: string }`.
+	 */
+	async hangup({ id, reason, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		const body = reason ? { reason } : {};
+		return this.client(`/voice/v1/calls/${safeId}/hangup`, { method: "POST", body, ...options });
+	}
+}