@signalhousellc/sdk 1.0.67 → 1.0.69

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;
 	}

package/src/webhooks/verifySignature.js

@@ -0,0 +1,66 @@
+import crypto from "node:crypto";
+
+// Node-only helpers for receiving Signal House webhooks (SHGHL-3486). Kept out of the main entry point,
+// which also runs in browsers, because it depends on node:crypto. Import from "@signalhousellc/sdk/webhooks".
+
+const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+
+/**
+ * Verify that a webhook delivery came from Signal House and is recent.
+ *
+ * Checks `X-SignalHouse-Signature-V1` (`t=<ms>,v1=<hex>[,v1=<hex>]`, which carries every currently valid
+ * signature during a secret rotation) when present, otherwise the original `X-SignalHouse-Signature` +
+ * `X-SignalHouse-Timestamp` pair. Each signature is a hex HMAC-SHA256 of `${timestamp}.${rawBody}`. Comparisons
+ * are constant-time.
+ *
+ * @param {Object} params
+ * @param {string|Buffer} params.rawBody - The exact request body as received, before any JSON parsing.
+ * @param {Object} params.headers - Request headers (any casing; e.g. Express `req.headers`).
+ * @param {string} [params.secret] - Your endpoint's signing secret.
+ * @param {string[]} [params.secrets] - Several secrets to accept, e.g. old and new while you roll over.
+ * @param {number} [params.toleranceMs=300000] - Reject deliveries whose timestamp is further than this from now.
+ * @param {number} [params.now=Date.now()] - Current time in ms (for tests).
+ * @returns {{valid: boolean, reason?: string}} - `valid` true when a signature matches within the time window;
+ *   otherwise `reason` is one of `no_secret`, `no_signature`, `bad_timestamp`, `stale_timestamp`, `bad_signature`.
+ */
+export function verifyWebhookSignature({ rawBody, headers, secret, secrets, toleranceMs = DEFAULT_TOLERANCE_MS, now = Date.now() }) {
+	const candidates = (secrets ?? (secret ? [secret] : [])).filter(Boolean);
+	if (candidates.length === 0) return { valid: false, reason: "no_secret" };
+
+	const header = (name) => {
+		if (!headers) return undefined;
+		const match = Object.keys(headers).find((key) => key.toLowerCase() === name);
+		const value = match === undefined ? undefined : headers[match];
+		return Array.isArray(value) ? value[0] : value;
+	};
+
+	let timestamp;
+	let signatures = [];
+	const v1 = header("x-signalhouse-signature-v1");
+	if (v1) {
+		const parts = String(v1).split(",").map((part) => part.trim());
+		timestamp = parts.find((part) => part.startsWith("t="))?.slice(2);
+		signatures = parts.filter((part) => part.startsWith("v1=")).map((part) => part.slice(3)).filter(Boolean);
+	}
+	// No usable V1 (absent, or mangled by an intermediary): fall back to the original header pair
+	if (signatures.length === 0) {
+		timestamp = header("x-signalhouse-timestamp");
+		const legacy = header("x-signalhouse-signature");
+		signatures = legacy ? [String(legacy)] : [];
+	}
+	if (signatures.length === 0) return { valid: false, reason: "no_signature" };
+
+	const sentAt = Number(timestamp);
+	if (!timestamp || !Number.isFinite(sentAt)) return { valid: false, reason: "bad_timestamp" };
+	if (Math.abs(now - sentAt) > toleranceMs) return { valid: false, reason: "stale_timestamp" };
+
+	const body = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : String(rawBody ?? "");
+	for (const candidate of candidates) {
+		const expected = Buffer.from(crypto.createHmac("sha256", candidate).update(`${timestamp}.${body}`).digest("hex"), "utf8");
+		for (const signature of signatures) {
+			const given = Buffer.from(signature, "utf8");
+			if (given.length === expected.length && crypto.timingSafeEqual(given, expected)) return { valid: true };
+		}
+	}
+	return { valid: false, reason: "bad_signature" };
+}