@signalhousellc/sdk 1.0.67 → 1.0.68

package/src/domains/voice/SipTrunks.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} SipTrunkHost
  * @property {string} host - IP address, hostname, FQDN, or CIDR.
@@ -43,8 +49,8 @@ export class SipTrunks {
 	 * @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: [...] }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} The list of SIP trunks: `{ sipTrunks: [...] }`.
 	 */
 	async list({ options = {} } = {}) {
 		return this.client(`/voice/sip-trunks`, { method: "GET", ...options });
@@ -56,9 +62,9 @@ export class SipTrunks {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} The SIP trunk: `{ sipTrunk: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} The SIP trunk: `{ sipTrunk: {...} }`.
 	 */
 	async get({ id, options = {} }) {
 		this.client._require({ id });
@@ -72,9 +78,9 @@ export class SipTrunks {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If trunkData is missing.
-	 * @returns {Promise<Object>} The created SIP trunk: `{ sipTrunk: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} The created SIP trunk: `{ sipTrunk: {...} }`.
 	 */
 	async create({ trunkData, options = {} }) {
 		this.client._require({ trunkData });
@@ -88,9 +94,9 @@ export class SipTrunks {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or updateData is missing.
-	 * @returns {Promise<Object>} The updated SIP trunk: `{ sipTrunk: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} The updated SIP trunk: `{ sipTrunk: {...} }`.
 	 */
 	async update({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -104,9 +110,9 @@ export class SipTrunks {
 	 * @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.
+	 * @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 delete({ id, options = {} }) {
 		this.client._require({ id });
@@ -120,9 +126,9 @@ export class SipTrunks {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} The updated SIP trunk: `{ sipTrunk: {...} }`.
+	 * @returns {Promise<SdkResponse<any>>} The updated SIP trunk: `{ sipTrunk: {...} }`.
 	 */
 	async toggleActive({ id, options = {} }) {
 		this.client._require({ id });
@@ -136,9 +142,9 @@ export class SipTrunks {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id is missing.
-	 * @returns {Promise<Object>} `{ password: string }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ password: string }`.
 	 */
 	async regeneratePassword({ id, options = {} }) {
 		this.client._require({ id });
@@ -151,8 +157,8 @@ export class SipTrunks {
 	 * @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: [...] }`.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} `{ sipPops: [...] }`.
 	 */
 	async getPops({ options = {} } = {}) {
 		return this.client(`/voice/sip-trunks/pops`, { method: "GET", ...options });
@@ -167,9 +173,9 @@ export class SipTrunks {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP trunk UUID.
 	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or phoneNumbers is missing.
-	 * @returns {Promise<Object>} `{ assigned: string[], skipped: { e164, reason }[] }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ assigned: string[], skipped: { e164, reason }[] }`.
 	 */
 	async assignNumbers({ id, phoneNumbers, options = {} }) {
 		this.client._require({ id, phoneNumbers });
@@ -185,9 +191,9 @@ export class SipTrunks {
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP trunk UUID.
 	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
 	 * @throws {Error} If id or phoneNumbers is missing.
-	 * @returns {Promise<Object>} `{ unassigned: string[] }`.
+	 * @returns {Promise<SdkResponse<any>>} `{ unassigned: string[] }`.
 	 */
 	async unassignNumbers({ id, phoneNumbers, options = {} }) {
 		this.client._require({ id, phoneNumbers });

package/src/domains/voice/Tokens.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} VoiceGrants
  * @property {Object} [voice] - Voice grants object.
@@ -55,8 +61,8 @@ export class Tokens {
 	 * @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.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<CreateTokenResponse>>} The token + embedded SIP credentials.
 	 */
 	async create({ tokenData = {}, options = {} } = {}) {
 		return this.client(`/voice/tokens`, { method: "POST", body: tokenData, ...options });
@@ -77,8 +83,8 @@ export class Tokens {
 	 * @param {string} [params.token] - The current voice token (JWT) whose identity to extend.
 	 * @param {string} [params.identity] - The wrtc_ identity to extend, if held directly (from a prior mint/refresh response).
 	 * @param {number} [params.ttl] - New TTL in seconds. Defaults to the server default, capped at the server maximum.
-	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<CreateTokenResponse>} The refreshed token + embedded SIP credentials (same shape as create()).
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<CreateTokenResponse>>} The refreshed token + embedded SIP credentials (same shape as create()).
 	 */
 	async refresh({ token, identity, ttl, options = {} } = {}) {
 		const body = {};

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

@@ -31,6 +31,8 @@ export class Call {
 		this._session = session;
 		this._listeners = new Map();
 		this._remoteAudio = null;
+		/** @type {boolean} Set true before accept/connect to route remote audio yourself instead of the hidden <audio>. */
+		this.disableDefaultAudioOutput = false;
 
 		this.direction = direction;
 		this.id = session.id || session._request?.call_id || null;

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

@@ -73,6 +73,15 @@ import { Call } from "./Call.js";
  * "connected" (WSS established), "disconnected", "tokenWillExpire",
  * "tokenRefreshFailed", "error".
  */
+/**
+ * Narrow a token-or-credentials argument: a VoiceTokenResponse wraps its SIP credentials under `sip_credentials`.
+ * @param {VoiceTokenResponse | SipCredentials} value - The argument to inspect.
+ * @returns {value is VoiceTokenResponse} - True when the value is a token response.
+ */
+function isTokenResponse(value) {
+	return !!value && typeof value === "object" && "sip_credentials" in value;
+}
+
 export class Device {
 	/**
 	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
@@ -90,8 +99,9 @@ export class Device {
 	 */
 	constructor(tokenOrCreds, opts = {}) {
 		this._credentials = this._parseCreds(tokenOrCreds, "Device");
-		this.identity = tokenOrCreds?.identity || this._credentials.username;
-		this.expiresAt = tokenOrCreds?.expires_at || null;
+		const token = isTokenResponse(tokenOrCreds) ? tokenOrCreds : null;
+		this.identity = token?.identity || this._credentials.username;
+		this.expiresAt = token?.expires_at || null;
 
 		this._opts = {
 			registerExpires: opts.registerExpires ?? 600,
@@ -179,12 +189,13 @@ export class Device {
 	 */
 	async updateToken(tokenOrCreds) {
 		const creds = this._parseCreds(tokenOrCreds, "Device.updateToken");
-		const newIdentity = tokenOrCreds?.identity || creds.username;
+		const token = isTokenResponse(tokenOrCreds) ? tokenOrCreds : null;
+		const newIdentity = token?.identity || creds.username;
 
 		// Identity-preserving fast path — same credential, just extended expiry.
 		if (this._ua && this._registered && !this._stopped &&
 			newIdentity === this.identity && creds.password === this._credentials.password) {
-			this.expiresAt = tokenOrCreds?.expires_at || this.expiresAt;
+			this.expiresAt = token?.expires_at || this.expiresAt;
 			this._scheduleTokenRefresh();
 			return;
 		}
@@ -205,7 +216,7 @@ export class Device {
 	 * @param {ConnectParams} params
 	 * @returns {Promise<Call>}
 	 */
-	async connect({ to, from, mediaStream, pcConfig, extraHeaders = [] } = {}) {
+	async connect({ to, from, mediaStream, pcConfig, extraHeaders = [] } = /** @type {ConnectParams} */ ({})) {
 		if (!this._ua || !this._registered) {
 			throw new Error("Device.connect: not registered yet — call register() first");
 		}
@@ -235,7 +246,7 @@ export class Device {
 			mediaConstraints: { audio: true, video: false },
 			mediaStream: stream,
 			pcConfig: pcConfig || { iceServers: [] },
-			rtcOfferConstraints: { offerToReceiveAudio: 1, offerToReceiveVideo: 0 },
+			rtcOfferConstraints: { offerToReceiveAudio: true, offerToReceiveVideo: false },
 			extraHeaders: headers,
 		});
 
@@ -279,7 +290,7 @@ export class Device {
 	 * @throws {Error} when a required field is missing.
 	 */
 	_parseCreds(tokenOrCreds, ctx) {
-		const creds = tokenOrCreds?.sip_credentials || tokenOrCreds;
+		const creds = /** @type {SipCredentials} */ (isTokenResponse(tokenOrCreds) ? tokenOrCreds.sip_credentials : tokenOrCreds);
 		if (!creds?.username || !creds?.password || !creds?.domain || !creds?.wss_url) {
 			throw new Error(`${ctx}: token/credentials missing required fields (username, password, domain, wss_url)`);
 		}
@@ -320,8 +331,9 @@ export class Device {
 		this._ua = null;
 		this._registered = false;
 		this._credentials = creds;
-		this.identity = tokenOrCreds?.identity || creds.username;
-		this.expiresAt = tokenOrCreds?.expires_at || null;
+		const token = isTokenResponse(tokenOrCreds) ? tokenOrCreds : null;
+		this.identity = token?.identity || creds.username;
+		this.expiresAt = token?.expires_at || null;
 
 		try {
 			await this.register(); // rebuilds the UA + reschedules the refresh timer
@@ -345,11 +357,11 @@ export class Device {
 	 * True if the given token has too little life left to safely apply (would
 	 * expire within tokenRefreshMs). Tokens with no parseable expiry are treated
 	 * as usable.
-	 * @param {VoiceTokenResponse} tokenOrCreds
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
 	 * @returns {boolean}
 	 */
 	_isTokenStale(tokenOrCreds) {
-		const exp = Date.parse(tokenOrCreds?.expires_at || "");
+		const exp = Date.parse((isTokenResponse(tokenOrCreds) && tokenOrCreds.expires_at) || "");
 		if (!Number.isFinite(exp)) return false;
 		return exp - Date.now() <= this._opts.tokenRefreshMs;
 	}