@signalhousellc/sdk 1.0.51 → 1.0.53

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