@signalhousellc/sdk 1.0.51 → 1.0.53

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