@signalhousellc/sdk 1.0.52 → 1.0.53

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.52",
+  "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/Campaigns.js

@@ -64,7 +64,7 @@
  * @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, additionalInformation (≤500)). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
+ * @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.
  */
 
 /**
@@ -87,7 +87,7 @@
  * @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} [additionalInformation] - Free-text justification sent upstream to the carrier (optional, at most 500 characters). Required when more than one phone number is assigned to the campaign.
+ * @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.
  */
 
 /**
@@ -196,7 +196,7 @@ export class Campaigns {
 	/**
 	 * Create a new Toll-Free (TFN) campaign and submit it for Signal House review
 	 * @async
-	 * @roles api, admin, developer, billing, user
+	 * @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

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

@@ -115,7 +115,8 @@ export class Numbers {
 	 * 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.
+	 * 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
@@ -123,13 +124,32 @@ export class Numbers {
 	 * @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 }` once the request is queued.
+	 * @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 });
+	}
+}

package/src/domains/voice/SipProfiles.js

@@ -0,0 +1,191 @@
+/**
+ * @typedef {Object} CreateSipProfileData
+ * @property {string} name - Profile name (required).
+ * @property {boolean} [recordingAllowed] - Permit call recording on this endpoint.
+ * @property {boolean} [transcriptionEnabled] - Permit transcription on calls to/from this endpoint.
+ * @property {boolean} [sentimentFlag] - Permit sentiment analysis on this endpoint.
+ */
+
+/**
+ * @typedef {Object} UpdateSipProfileData
+ * @property {string} [name] - Profile name.
+ * @property {string} [sipUsername] - SIP username override.
+ * @property {string} [password] - New password (also the way to "regenerate" — pass a fresh value).
+ * @property {"UDP"|"TCP"|"TLS"} [transport] - SIP transport.
+ * @property {boolean} [recordingAllowed] - Permit call recording.
+ * @property {boolean} [transcriptionEnabled] - Permit transcription.
+ * @property {boolean} [sentimentFlag] - Permit sentiment analysis.
+ */
+
+/**
+ * SIP Profile / endpoint management. A SIP profile is a single registerable
+ * UA — a desk phone, a softphone, a SIP-capable device — that registers to
+ * Signal House with a username and password. Distinct from a SIP trunk,
+ * which represents a peer-to-peer link to another PBX or carrier.
+ *
+ * Calls the voice-backend service mounted under /voice. Accessed via
+ * `sdk.voice.sipProfiles`.
+ */
+export class SipProfiles {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * List all SIP profiles belonging to the current account.
+	 * @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: [...] }`.
+	 */
+	async list({ options = {} } = {}) {
+		return this.client(`/voice/sip-profiles`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single SIP profile by ID. NOTE: response does NOT include the
+	 * password — use `getPassword({ id })` to retrieve it.
+	 * @async
+	 * @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.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 */
+	async get({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get the password for a SIP profile. The password is generated by the
+	 * server on create and stored; this endpoint returns the stored value
+	 * (it is NOT one-time-visible like the create response — calling getPassword
+	 * later still returns the password as long as it has not been replaced).
+	 * @async
+	 * @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.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ password: string|null }`.
+	 */
+	async getPassword({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}/password`, { method: "GET", ...options });
+	}
+
+	/**
+	 * List valid SIP transports + their address/port per region from the DB.
+	 * Used by edit-profile UI to populate transport selectors.
+	 * @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 }, ...] }`.
+	 */
+	async getTransports({ options = {} } = {}) {
+		return this.client(`/voice/sip-profiles/transports`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a new SIP profile. The server generates the SIP username and
+	 * password; the password is returned on the create response at the top
+	 * level (NOT nested inside `sipProfile`) and is the only chance to surface
+	 * it without an explicit `getPassword` lookup.
+	 * @async
+	 * @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.
+	 * @throws {Error} If profileData is missing.
+	 * @returns {Promise<Object>} `{ sipProfile: {...}, password: string, sipServer: string, message: string }`.
+	 */
+	async create({ profileData, options = {} }) {
+		this.client._require({ profileData });
+		return this.client(`/voice/sip-profiles`, { method: "POST", body: profileData, ...options });
+	}
+
+	/**
+	 * Update an existing SIP profile. To rotate the password, pass a new
+	 * `password` value here — there is no dedicated regenerate endpoint.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @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.
+	 * @throws {Error} If id or updateData is missing.
+	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 */
+	async update({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}`, { method: "PATCH", body: updateData, ...options });
+	}
+
+	/**
+	 * Delete a SIP profile by ID. Unassigns any linked numbers and frees the
+	 * extension as a side-effect.
+	 * @async
+	 * @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.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ message: string }`.
+	 */
+	async delete({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Assign a phone number to this SIP profile (routes inbound calls on that
+	 * number to the endpoint).
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP profile UUID.
+	 * @param {string} params.phoneNumberId - The phone number UUID to assign.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumberId is missing.
+	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 */
+	async assignNumber({ id, phoneNumberId, options = {} }) {
+		this.client._require({ id, phoneNumberId });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}/assign-number`, {
+			method: "POST",
+			body: { phoneNumberId },
+			...options,
+		});
+	}
+
+	/**
+	 * Unassign a phone number from this SIP profile.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP profile UUID.
+	 * @param {string} params.phoneNumberId - The phone number UUID to unassign.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumberId is missing.
+	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
+	 */
+	async unassignNumber({ id, phoneNumberId, options = {} }) {
+		this.client._require({ id, phoneNumberId });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-profiles/${safeId}/unassign-number`, {
+			method: "POST",
+			body: { phoneNumberId },
+			...options,
+		});
+	}
+}

package/src/domains/voice/SipTrunks.js

@@ -0,0 +1,160 @@
+/**
+ * @typedef {Object} SipTrunkHost
+ * @property {string} host - IP address, hostname, FQDN, or CIDR.
+ * @property {string} [port] - Port number as a string (1025-65535). Destination hosts only.
+ */
+
+/**
+ * @typedef {Object} CreateSipTrunkData
+ * @property {string} name - Trunk name (required, 1-255 chars).
+ * @property {string} region - SIP POP region the trunk lives in (required), e.g. "us-east-1".
+ * @property {"IP_AUTH"|"REGISTRATION"} connectionType - IP_AUTH authenticates by source-IP allow-list; REGISTRATION authenticates via SIP REGISTER with username/password.
+ * @property {string[]} [allowedIps] - Allowed source IPs (IP_AUTH only). Defaults to [].
+ * @property {"tcp"|"udp"|"tls"} [transport] - SIP transport protocol. Defaults to "tcp".
+ * @property {number} [maxSpendPerMinute] - Per-minute spend cap override for this trunk.
+ * @property {SipTrunkHost[]} [destinationHosts] - Where to send outbound SIP traffic. Defaults to [].
+ * @property {SipTrunkHost[]} [sourceHosts] - Allowed source hosts for inbound traffic. Defaults to [].
+ */
+
+/**
+ * @typedef {Object} UpdateSipTrunkData
+ * @property {string} [name] - Trunk name (1-255 chars).
+ * @property {string} [region] - SIP POP region.
+ * @property {"IP_AUTH"|"REGISTRATION"} [connectionType] - Connection/auth type.
+ * @property {string[]} [allowedIps] - Allowed source IPs (IP_AUTH only).
+ * @property {"tcp"|"udp"|"tls"} [transport] - SIP transport protocol.
+ * @property {number} [maxSpendPerMinute] - Per-minute spend cap override.
+ * @property {SipTrunkHost[]} [destinationHosts] - Outbound SIP destinations.
+ * @property {SipTrunkHost[]} [sourceHosts] - Allowed inbound source hosts.
+ */
+
+/**
+ * SIP Trunk management. Calls the voice-backend service mounted under /voice.
+ * Accessed via `sdk.voice.sipTrunks`.
+ */
+export class SipTrunks {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * List all SIP trunks belonging to the current account.
+	 * @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>} The list of SIP trunks: `{ sipTrunks: [...] }`.
+	 */
+	async list({ options = {} } = {}) {
+		return this.client(`/voice/sip-trunks`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single SIP trunk by ID.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} The SIP trunk: `{ sipTrunk: {...} }`.
+	 */
+	async get({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a new SIP trunk.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {CreateSipTrunkData} params.trunkData - The SIP trunk to create.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If trunkData is missing.
+	 * @returns {Promise<Object>} The created SIP trunk: `{ sipTrunk: {...} }`.
+	 */
+	async create({ trunkData, options = {} }) {
+		this.client._require({ trunkData });
+		return this.client(`/voice/sip-trunks`, { method: "POST", body: trunkData, ...options });
+	}
+
+	/**
+	 * Update an existing SIP trunk.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {UpdateSipTrunkData} params.updateData - Fields to update.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or updateData is missing.
+	 * @returns {Promise<Object>} The updated SIP trunk: `{ sipTrunk: {...} }`.
+	 */
+	async update({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}`, { method: "PATCH", body: updateData, ...options });
+	}
+
+	/**
+	 * Delete a SIP trunk by ID.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @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 delete({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Toggle a SIP trunk's active/inactive status.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} The updated SIP trunk: `{ sipTrunk: {...} }`.
+	 */
+	async toggleActive({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/toggle-active`, { method: "POST", ...options });
+	}
+
+	/**
+	 * Regenerate the SIP password for a REGISTRATION-type trunk.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id is missing.
+	 * @returns {Promise<Object>} `{ password: string }`.
+	 */
+	async regeneratePassword({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/regenerate-password`, { method: "POST", ...options });
+	}
+
+	/**
+	 * List available SIP Points of Presence (POPs) and their domains/ports.
+	 * @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>} `{ sipPops: [...] }`.
+	 */
+	async getPops({ options = {} } = {}) {
+		return this.client(`/voice/sip-trunks/pops`, { method: "GET", ...options });
+	}
+}

package/src/domains/voice/Tokens.js

@@ -0,0 +1,64 @@
+/**
+ * @typedef {Object} VoiceGrants
+ * @property {Object} [voice] - Voice grants object.
+ * @property {Object} [voice.incoming] - Inbound call grants.
+ * @property {boolean} [voice.incoming.allow] - Allow inbound calls to this identity.
+ * @property {Object} [voice.outgoing] - Outbound call grants.
+ * @property {string[]} [voice.outgoing.allowedNumbers] - E.164 numbers this identity may present as caller ID.
+ */
+
+/**
+ * @typedef {Object} CreateTokenData
+ * @property {string} [identity] - Customer-facing logical identity name (e.g. "alice"). Persisted as `requested_identity` so server-initiated `calls.create({to_identity: "alice"})` can resolve it later. Defaults to "anonymous".
+ * @property {number} [ttl] - Token TTL in seconds. Clamped to the server's max. Defaults to VOICE_TOKEN_DEFAULT_TTL_SEC.
+ * @property {VoiceGrants} [grants] - Capability grants attached to the token.
+ */
+
+/**
+ * @typedef {Object} SipCredentials
+ * @property {string} username - Server-generated SIP username (e.g. "wrtc_<hex>"). Use for the SIP-over-WSS registration.
+ * @property {string} password - Plaintext SIP password — sent ONCE, never recoverable. Use for digest auth on REGISTER + INVITE.
+ * @property {string} domain - SIP domain to register against (the part after `@` in the URI).
+ * @property {string} wss_url - WebSocket Secure URL the SDK opens to send SIP traffic.
+ */
+
+/**
+ * @typedef {Object} CreateTokenResponse
+ * @property {string} token - JWT to pass to the SignalHouse browser voice SDK.
+ * @property {string} identity - The server-generated SIP username (wrtc_<hex>). Distinct from the logical `requested_identity` passed in.
+ * @property {string} expires_at - ISO-8601 expiry timestamp.
+ * @property {SipCredentials} sip_credentials - Ephemeral SIP creds embedded in the token; surfaced separately for direct SIP clients.
+ */
+
+/**
+ * WebRTC voice tokens. Mints ephemeral SIP identities the browser/mobile voice
+ * SDK uses to register against the SignalHouse voice fabric. Wraps voice-
+ * backend's `/voice/tokens` endpoint. Accessed via `sdk.voice.tokens`.
+ *
+ * Customer flow:
+ * 1. Backend calls `sdk.voice.tokens.create({ identity: "alice", ttl: 1800 })`
+ *    and returns the resulting `token` to the customer's browser/app.
+ * 2. Browser SDK registers using the embedded `sip_credentials`.
+ * 3. Outbound calls from the SDK go through OpenSIPS → Asterisk → carrier;
+ *    the server-side `calls.create({ to_identity: "alice", ... })` flow can
+ *    also ring this identity for click-to-call patterns.
+ */
+export class Tokens {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Mint an ephemeral voice token + SIP credentials.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {CreateTokenData} [params.tokenData] - Token mint options (identity, ttl, grants). All fields optional.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<CreateTokenResponse>} The token + embedded SIP credentials.
+	 */
+	async create({ tokenData = {}, options = {} } = {}) {
+		return this.client(`/voice/tokens`, { method: "POST", body: tokenData, ...options });
+	}
+}

package/src/domains/voice/browser/Call.js

@@ -0,0 +1,266 @@
+/**
+ * @typedef {"inbound"|"outbound"} CallDirection
+ * @typedef {"initial"|"ringing"|"in_progress"|"ended"|"failed"} CallStatus
+ */
+
+/**
+ * Wraps a single SIP session — outbound or inbound — and exposes a
+ * Twilio-shape Call API on top of the underlying JsSIP RTCSession.
+ *
+ * Lifecycle (outbound):
+ *   new (status="initial") → ringing → in_progress → ended | failed
+ *
+ * Lifecycle (inbound, before .accept()):
+ *   new (status="ringing") → in_progress (on accept) → ended | failed
+ *
+ * Custom SIP headers from inbound INVITEs are exposed on the instance
+ * (notably `initiatorId` from `X-SignalHouse-Initiator`) so the host app
+ * can correlate a server-initiated callback to its triggering REST call.
+ *
+ * Methods reject when the session is no longer in a state that supports
+ * them (e.g., `.accept()` on an already-accepted call).
+ */
+export class Call {
+	/**
+	 * @param {Object} init - Initializer.
+	 * @param {Object} init.session - The JsSIP RTCSession.
+	 * @param {CallDirection} init.direction
+	 * @param {Object} [init.request] - Inbound INVITE request, when direction === "inbound".
+	 */
+	constructor({ session, direction, request }) {
+		this._session = session;
+		this._listeners = new Map();
+		this._remoteAudio = null;
+
+		this.direction = direction;
+		this.id = session.id || session._request?.call_id || null;
+		this.status = direction === "inbound" ? "ringing" : "initial";
+
+		// From / To URIs. For inbound the session._request carries them; for
+		// outbound JsSIP populates from session.remote_identity / local_identity
+		// once the dialog is established.
+		this.from = session.remote_identity?.uri?.toString?.() ?? request?.from?.uri?.toString?.() ?? null;
+		this.to   = session.local_identity?.uri?.toString?.()  ?? request?.to?.uri?.toString?.()   ?? null;
+
+		// Surface useful inbound headers. Most important: X-SignalHouse-Initiator,
+		// which carries the call_id of the REST POST /v1/calls that triggered a
+		// server-side two-leg-with-bridge ring. Host app can compare against its
+		// pending dial set to decide whether to auto-accept.
+		this.headers = {};
+		if (request && typeof request.getHeader === "function") {
+			for (const name of [
+				"X-SignalHouse-Initiator",
+				"X-Call-UUID",
+				"X-Call-Type",
+				"X-Route-Type",
+				"X-Dest",
+			]) {
+				const v = request.getHeader(name);
+				if (v) this.headers[name] = v;
+			}
+		}
+		this.initiatorId = this.headers["X-SignalHouse-Initiator"] || null;
+		this.callUuid   = this.headers["X-Call-UUID"] || null;
+
+		this._wireSessionEvents();
+	}
+
+	// ─── Public API ─────────────────────────────────────────────────────────
+
+	/**
+	 * Accept an inbound call. No-op (warning) if outbound or already accepted.
+	 * @param {Object} [opts]
+	 * @param {MediaStream} [opts.mediaStream] - Pre-acquired stream from getUserMedia.
+	 *   If omitted, the SDK calls getUserMedia({audio: true}) and uses the result.
+	 * @param {RTCConfiguration} [opts.pcConfig] - WebRTC peer-connection config.
+	 *   Falls back to {iceServers: [{urls: "stun:stun.l.google.com:19302"}]}.
+	 * @returns {Promise<void>}
+	 */
+	async accept({ mediaStream, pcConfig } = {}) {
+		if (this.direction !== "inbound") {
+			console.warn("[Call.accept] no-op: only inbound calls can be accepted");
+			return;
+		}
+		if (this.status !== "ringing") {
+			console.warn(`[Call.accept] no-op: call is not ringing (status=${this.status})`);
+			return;
+		}
+		const stream = mediaStream || (await navigator.mediaDevices.getUserMedia({ audio: true, video: false }));
+		this._session.answer({
+			mediaConstraints: { audio: true, video: false },
+			mediaStream: stream,
+			// Default: no STUN (rtpengine trust-address handles NAT). Override via pcConfig.
+			pcConfig: pcConfig || { iceServers: [] },
+		});
+	}
+
+	/**
+	 * Reject an inbound call with 486 Busy (or supplied SIP code).
+	 * @param {Object} [opts]
+	 * @param {number} [opts.statusCode=486]
+	 * @param {string} [opts.reason="Busy Here"]
+	 */
+	reject({ statusCode = 486, reason = "Busy Here" } = {}) {
+		if (this.direction !== "inbound" || this.status !== "ringing") {
+			console.warn("[Call.reject] no-op: only ringing inbound calls can be rejected");
+			return;
+		}
+		try {
+			this._session.terminate({ status_code: statusCode, reason_phrase: reason });
+		} catch (err) {
+			// JsSIP throws if the session is already gone — non-fatal here
+			console.warn(`[Call.reject] terminate threw: ${err?.message || err}`);
+		}
+	}
+
+	/**
+	 * Hang up an in-progress or ringing outbound call. Idempotent.
+	 */
+	hangup() {
+		if (this.status === "ended" || this.status === "failed") return;
+		try {
+			this._session.terminate();
+		} catch (err) {
+			console.warn(`[Call.hangup] terminate threw: ${err?.message || err}`);
+		}
+	}
+
+	/**
+	 * Send DTMF digits during an in-progress call. Accepts 0-9, *, #, w (wait).
+	 * @param {string} digits
+	 */
+	sendDigits(digits) {
+		if (this.status !== "in_progress") {
+			console.warn(`[Call.sendDigits] no-op: call is not in_progress (status=${this.status})`);
+			return;
+		}
+		try {
+			this._session.sendDTMF(String(digits));
+		} catch (err) {
+			console.warn(`[Call.sendDigits] sendDTMF threw: ${err?.message || err}`);
+		}
+	}
+
+	/**
+	 * Attach an event listener. Events:
+	 *   "accepted"  — 200 OK received (outbound) or sent (inbound after accept)
+	 *   "confirmed" — ACK exchanged, media flowing
+	 *   "ended"     — normal hangup; payload: {cause}
+	 *   "failed"    — error before/during; payload: {cause, status_code, reason}
+	 *   "track"     — remote MediaStreamTrack added; payload: {track, streams}
+	 * @param {string} event
+	 * @param {Function} handler
+	 */
+	on(event, handler) {
+		if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+		this._listeners.get(event).add(handler);
+	}
+
+	/**
+	 * Remove a previously-registered listener.
+	 */
+	off(event, handler) {
+		this._listeners.get(event)?.delete(handler);
+	}
+
+	// ─── Internal: wire JsSIP RTCSession events to Call events ───────────────
+
+	_emit(event, payload) {
+		for (const fn of this._listeners.get(event) || []) {
+			try { fn(payload); }
+			catch (err) { console.error(`[Call.${event} handler]`, err); }
+		}
+	}
+
+	_wireSessionEvents() {
+		const s = this._session;
+
+		// Attach the RTCPeerConnection "track" listener as soon as the PC
+		// exists. The browser can fire `track` when the remote SDP is applied,
+		// which happens BEFORE JsSIP emits "confirmed" — waiting until then
+		// can drop the event entirely (call connects, no audio).
+		//
+		// For outbound calls JsSIP creates the PC inside `ua.call()`, so
+		// session.connection may already exist by the time our Call is
+		// constructed — handle that synchronously. For inbound calls the PC
+		// is created inside session.answer(); JsSIP emits "peerconnection"
+		// when it's ready — attach there.
+		if (s.connection) this._attachTrackListener(s.connection);
+		s.on("peerconnection", (e) => {
+			const pc = e?.peerconnection || s.connection;
+			if (pc) this._attachTrackListener(pc);
+		});
+
+		s.on("progress", (e) => {
+			this.status = "ringing";
+			this._emit("progress", { response: e.response });
+		});
+
+		s.on("accepted", () => {
+			this.status = "in_progress";
+			this._emit("accepted");
+		});
+
+		s.on("confirmed", () => {
+			this.status = "in_progress";
+			// Defensive: in case "peerconnection" never fired but a PC exists by now.
+			if (this._session.connection) this._attachTrackListener(this._session.connection);
+			this._emit("confirmed");
+		});
+
+		s.on("ended", (e) => {
+			this.status = "ended";
+			this._cleanupRemoteAudio();
+			this._emit("ended", { cause: e?.cause });
+		});
+
+		s.on("failed", (e) => {
+			this.status = "failed";
+			this._cleanupRemoteAudio();
+			this._emit("failed", {
+				cause: e?.cause,
+				statusCode: e?.message?.status_code,
+				reason: e?.message?.reason_phrase,
+			});
+		});
+	}
+
+	/**
+	 * Idempotent — wires the RTCPeerConnection "track" handler. Uses
+	 * addEventListener (not pc.ontrack) so host apps can attach their own
+	 * track listener without clobbering ours, and vice versa.
+	 *
+	 * When a remote track arrives:
+	 *   - Emit "track" so the host app can route audio anywhere it wants.
+	 *   - If `call.disableDefaultAudioOutput` is falsy, attach the stream to
+	 *     a hidden <audio> element so the user just hears the call. Host
+	 *     apps that want custom audio routing should set
+	 *     `call.disableDefaultAudioOutput = true` before accepting/connecting.
+	 */
+	_attachTrackListener(pc) {
+		if (this._trackListenerAttached) return;
+		this._trackListenerAttached = true;
+
+		pc.addEventListener("track", (evt) => {
+			this._emit("track", { track: evt.track, streams: evt.streams });
+			if (this.disableDefaultAudioOutput) return;
+			if (!this._remoteAudio) {
+				this._remoteAudio = document.createElement("audio");
+				this._remoteAudio.autoplay = true;
+				this._remoteAudio.setAttribute("data-signalhouse-call", this.id || "");
+				document.body.appendChild(this._remoteAudio);
+			}
+			this._remoteAudio.srcObject = evt.streams[0];
+		});
+	}
+
+	_cleanupRemoteAudio() {
+		if (this._remoteAudio) {
+			try {
+				this._remoteAudio.srcObject = null;
+				this._remoteAudio.remove();
+			} catch {}
+			this._remoteAudio = null;
+		}
+	}
+}

package/src/domains/voice/browser/Device.js

@@ -0,0 +1,226 @@
+import JsSIP from "jssip";
+import { Call } from "./Call.js";
+
+/**
+ * @typedef {Object} SipCredentials
+ * @property {string} username - SIP username (e.g. "wrtc_<hex>"); from /voice/tokens response.
+ * @property {string} password - Plaintext SIP password.
+ * @property {string} domain - SIP domain (e.g. "webrtc.signalhouse.io").
+ * @property {string} wss_url - WebSocket Secure URL to OpenSIPS.
+ */
+
+/**
+ * @typedef {Object} VoiceTokenResponse
+ * @property {string} token - JWT (informational; SDK does not currently re-send it).
+ * @property {string} identity - The wrtc_<hex> SIP username.
+ * @property {string} expires_at - ISO timestamp.
+ * @property {SipCredentials} sip_credentials
+ */
+
+/**
+ * @typedef {Object} ConnectParams
+ * @property {string} to - Destination — E.164 ("+15551234") or full SIP URI.
+ * @property {string} [from] - Caller ID to present (must be an account-owned DID).
+ *   Sent as a P-Preferred-Identity header per RFC 3325; OpenSIPS validates
+ *   ownership and uses it as the carrier-bound From. If omitted, OpenSIPS
+ *   falls back to the account's default outbound DID.
+ * @property {MediaStream} [mediaStream] - Pre-acquired stream from getUserMedia.
+ *   When absent the SDK calls getUserMedia({audio: true}) itself.
+ * @property {RTCConfiguration} [pcConfig] - WebRTC peer-connection config.
+ * @property {string[]} [extraHeaders] - Additional SIP headers to attach to
+ *   the outbound INVITE (advanced).
+ */
+
+/**
+ * Browser-side SignalHouse voice client. Wraps JsSIP behind a Twilio-shape
+ * Device + Call API.
+ *
+ *   const device = new Device(tokenResponse);
+ *   await device.register();
+ *   const call = await device.connect({ to: "+15551234", from: "+15559999" });
+ *   device.on("incoming", call => call.accept());
+ *
+ * Token shape mirrors what `POST /voice/tokens` returns from the SignalHouse
+ * voice-backend. You can also hand in the inner `sip_credentials` object
+ * directly if your app already unwrapped the response.
+ *
+ * Events: "registered", "unregistered", "registrationFailed", "incoming",
+ * "connected" (WSS established), "disconnected", "error".
+ */
+export class Device {
+	/**
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 * @param {Object} [opts]
+	 * @param {number} [opts.registerExpires=600] - REGISTER expires interval, in seconds.
+	 * @param {string} [opts.userAgent="SignalHouse-Voice-SDK/0.1"]
+	 * @param {boolean} [opts.autoRegister=false] - Call register() on construct.
+	 */
+	constructor(tokenOrCreds, opts = {}) {
+		const creds = tokenOrCreds?.sip_credentials || tokenOrCreds;
+		if (!creds?.username || !creds?.password || !creds?.domain || !creds?.wss_url) {
+			throw new Error("Device: token/credentials missing required fields (username, password, domain, wss_url)");
+		}
+
+		this.identity = tokenOrCreds?.identity || creds.username;
+		this.expiresAt = tokenOrCreds?.expires_at || null;
+
+		this._credentials = creds;
+		this._opts = {
+			registerExpires: opts.registerExpires ?? 600,
+			userAgent: opts.userAgent ?? "SignalHouse-Voice-SDK/0.1",
+		};
+
+		this._ua = null;
+		this._listeners = new Map();
+		this._registered = false;
+
+		if (opts.autoRegister) this.register().catch(() => { /* surfaced via "registrationFailed" event */ });
+	}
+
+	// ─── Public API ─────────────────────────────────────────────────────────
+
+	/**
+	 * Open the WSS connection and REGISTER. Resolves on first "registered"
+	 * event, rejects on first "registrationFailed".
+	 * @returns {Promise<void>}
+	 */
+	register() {
+		if (this._registered) return Promise.resolve();
+		if (!this._ua) this._initUA();
+
+		return new Promise((resolve, reject) => {
+			const onOk = () => {
+				this._ua.removeListener("registered", onOk);
+				this._ua.removeListener("registrationFailed", onFail);
+				resolve();
+			};
+			const onFail = (e) => {
+				this._ua.removeListener("registered", onOk);
+				this._ua.removeListener("registrationFailed", onFail);
+				reject(new Error(`registrationFailed: ${e?.cause || "unknown"}`));
+			};
+			this._ua.on("registered", onOk);
+			this._ua.on("registrationFailed", onFail);
+			this._ua.start();
+		});
+	}
+
+	/**
+	 * Unregister and close the WSS connection. Idempotent.
+	 * @returns {Promise<void>}
+	 */
+	unregister() {
+		if (!this._ua) return Promise.resolve();
+		return new Promise((resolve) => {
+			const done = () => { try { this._ua.stop(); } catch {} resolve(); };
+			if (!this._registered) return done();
+			this._ua.once("unregistered", done);
+			try { this._ua.unregister(); }
+			catch { done(); }
+		});
+	}
+
+	/**
+	 * Place an outbound call. Returns a Call once the INVITE is sent.
+	 * The returned Call fires "progress" → "accepted" → "confirmed" as
+	 * the dialog establishes; listen for those before assuming audio is live.
+	 *
+	 * @param {ConnectParams} params
+	 * @returns {Promise<Call>}
+	 */
+	async connect({ to, from, mediaStream, pcConfig, extraHeaders = [] } = {}) {
+		if (!this._ua || !this._registered) {
+			throw new Error("Device.connect: not registered yet — call register() first");
+		}
+		if (!to) throw new Error("Device.connect: 'to' is required");
+
+		const target = /^sip:/i.test(to)
+			? to
+			: `sip:${String(to).replace(/^\+?/, "")}@${this._credentials.domain}`;
+
+		// P-Preferred-Identity (RFC 3325) — OpenSIPS validates this is an
+		// account-owned DID, then uses it as the carrier From header. If
+		// not supplied, OpenSIPS falls back to the account's default DID.
+		const headers = [...extraHeaders];
+		if (from) {
+			headers.push(`P-Preferred-Identity: <sip:${from}@${this._credentials.domain}>`);
+		}
+
+		const stream = mediaStream || (await navigator.mediaDevices.getUserMedia({ audio: true, video: false }));
+
+		// Default to no STUN servers — SignalHouse's rtpengine is configured
+		// with `trust-address` (uses the actual source IP from incoming RTP
+		// packets rather than the SDP), so host candidates are enough and
+		// ICE gathering completes in milliseconds instead of waiting on
+		// public STUN. Customers behind restrictive NATs can override via
+		// `pcConfig: { iceServers: [{urls: "stun:..."}] }`.
+		const session = this._ua.call(target, {
+			mediaConstraints: { audio: true, video: false },
+			mediaStream: stream,
+			pcConfig: pcConfig || { iceServers: [] },
+			rtcOfferConstraints: { offerToReceiveAudio: 1, offerToReceiveVideo: 0 },
+			extraHeaders: headers,
+		});
+
+		return new Call({ session, direction: "outbound" });
+	}
+
+	/**
+	 * Attach event listener. See class JSDoc for event list.
+	 */
+	on(event, handler) {
+		if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+		this._listeners.get(event).add(handler);
+	}
+
+	/**
+	 * Remove a previously-registered listener.
+	 */
+	off(event, handler) {
+		this._listeners.get(event)?.delete(handler);
+	}
+
+	/** True iff currently REGISTERED. */
+	get isRegistered() { return this._registered; }
+
+	// ─── Internal ───────────────────────────────────────────────────────────
+
+	_emit(event, payload) {
+		for (const fn of this._listeners.get(event) || []) {
+			try { fn(payload); }
+			catch (err) { console.error(`[Device.${event} handler]`, err); }
+		}
+	}
+
+	_initUA() {
+		const socket = new JsSIP.WebSocketInterface(this._credentials.wss_url);
+		this._ua = new JsSIP.UA({
+			sockets: [socket],
+			uri: `sip:${this._credentials.username}@${this._credentials.domain}`,
+			password: this._credentials.password,
+			register: true,
+			register_expires: this._opts.registerExpires,
+			user_agent: this._opts.userAgent,
+		});
+
+		this._ua.on("connecting", () => this._emit("connecting"));
+		this._ua.on("connected",  () => this._emit("connected"));
+		this._ua.on("disconnected", (e) => this._emit("disconnected", { reason: e?.reason }));
+		this._ua.on("registered", () => { this._registered = true;  this._emit("registered"); });
+		this._ua.on("unregistered", () => { this._registered = false; this._emit("unregistered"); });
+		this._ua.on("registrationFailed", (e) => {
+			this._registered = false;
+			this._emit("registrationFailed", {
+				cause: e?.cause,
+				statusCode: e?.response?.status_code,
+				reason: e?.response?.reason_phrase,
+			});
+		});
+
+		this._ua.on("newRTCSession", (e) => {
+			if (e.originator !== "remote") return; // outbound: we already wrap in connect()
+			const call = new Call({ session: e.session, direction: "inbound", request: e.request });
+			this._emit("incoming", call);
+		});
+	}
+}

package/src/domains/voice/browser/index.js

@@ -0,0 +1,17 @@
+/**
+ * Browser-only entry point for the SignalHouse voice SDK.
+ *
+ * Imported as a subpath:
+ *
+ *   import { Device } from "@signalhousellc/sdk/voice-browser";
+ *
+ * Loads JsSIP transitively. Node-only consumers should NOT import this
+ * subpath; the REST surface (`sdk.voice.calls`, `sdk.voice.tokens`, etc.)
+ * is exported from the package root and is JsSIP-free.
+ *
+ * Pairs with `sdk.voice.tokens.create()` from the REST surface — call that
+ * server-side to mint a token, hand the response to `new Device(token)`
+ * in the browser.
+ */
+export { Device } from "./Device.js";
+export { Call } from "./Call.js";