@signalhousellc/sdk 1.0.64 → 1.0.66

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

@@ -11,9 +11,14 @@ import { Call } from "./Call.js";
 
 /**
  * @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 {string} token - JWT (informational). Tokens are ephemeral: refresh
+ *   before `expires_at` (see updateToken()) so the softphone keeps a valid
+ *   registration.
+ * @property {string} identity - The wrtc_<hex> SIP username. The refresh
+ *   endpoint (POST /voice/tokens/refresh) keeps this identity stable; a fresh
+ *   mint (POST /voice/tokens) returns a new one.
+ * @property {string} expires_at - ISO timestamp. The Device schedules a
+ *   `tokenWillExpire` event at this minus `tokenRefreshMs`.
  * @property {SipCredentials} sip_credentials
  */
 
@@ -40,12 +45,33 @@ import { Call } from "./Call.js";
  *   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.
+ * Token refresh (REQUIRED for long-lived sessions): voice tokens are short-
+ * lived — a token's SIP credential authenticates only until `expires_at`. If
+ * you let it lapse, the softphone can no longer re-register and inbound calls
+ * stop arriving (they go to voicemail). The Device raises a `tokenWillExpire`
+ * event shortly before expiry so you can keep it alive. Mirrors Twilio's
+ * Device.updateToken() model:
+ *
+ *   // Manual — fetch a fresh token from your backend and hand it back:
+ *   device.on("tokenWillExpire", async () => {
+ *     const fresh = await fetch("/my/backend/voice-token").then((r) => r.json());
+ *     await device.updateToken(fresh);
+ *   });
+ *
+ *   // Automatic — let the Device refresh itself:
+ *   const device = new Device(tokenResponse, {
+ *     tokenProvider: () => fetch("/my/backend/voice-token").then((r) => r.json()),
+ *   });
+ *
+ * Preferred: have your backend call POST /voice/tokens/refresh, which extends
+ * the SAME identity in place — the Device then just reschedules and keeps its
+ * existing registration (no re-register, seamless). If instead you mint a fresh
+ * token (new identity), the Device re-registers under it (break-before-make,
+ * deferred while a call is active).
  *
  * Events: "registered", "unregistered", "registrationFailed", "incoming",
- * "connected" (WSS established), "disconnected", "error".
+ * "connected" (WSS established), "disconnected", "tokenWillExpire",
+ * "tokenRefreshFailed", "error".
  */
 export class Device {
 	/**
@@ -54,25 +80,36 @@ export class Device {
 	 * @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.
+	 * @param {number} [opts.tokenRefreshMs=30000] - How long before `expires_at`
+	 *   to raise `tokenWillExpire` (and auto-refresh, when `tokenProvider` is set).
+	 * @param {() => (VoiceTokenResponse|Promise<VoiceTokenResponse>)} [opts.tokenProvider]
+	 *   Optional. A function YOU supply that returns a fresh token — ideally by
+	 *   calling POST /voice/tokens/refresh through your backend (identity-
+	 *   preserving), or a fresh mint. When set, the Device calls it on
+	 *   `tokenWillExpire` and applies the result via updateToken() automatically.
 	 */
 	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._credentials = this._parseCreds(tokenOrCreds, "Device");
+		this.identity = tokenOrCreds?.identity || this._credentials.username;
 		this.expiresAt = tokenOrCreds?.expires_at || null;
 
-		this._credentials = creds;
 		this._opts = {
 			registerExpires: opts.registerExpires ?? 600,
 			userAgent: opts.userAgent ?? "SignalHouse-Voice-SDK/0.1",
+			tokenRefreshMs: opts.tokenRefreshMs ?? 30000,
+			tokenProvider: typeof opts.tokenProvider === "function" ? opts.tokenProvider : null,
 		};
 
 		this._ua = null;
 		this._listeners = new Map();
 		this._registered = false;
+		this._stopped = false;             // set by unregister(); guards in-flight refreshes
+
+		// Token-refresh state.
+		this._refreshTimer = null;         // fires `tokenWillExpire` before expiry
+		this._activeSessions = new Set();  // in-flight calls; defer an identity swap while busy
+		this._pendingToken = null;         // identity-change token handed to updateToken() while busy
+		this._refreshPendingAuto = false;  // tokenProvider refresh deferred while busy
 
 		if (opts.autoRegister) this.register().catch(() => { /* surfaced via "registrationFailed" event */ });
 	}
@@ -81,10 +118,12 @@ export class Device {
 
 	/**
 	 * Open the WSS connection and REGISTER. Resolves on first "registered"
-	 * event, rejects on first "registrationFailed".
+	 * event, rejects on first "registrationFailed". On success, schedules the
+	 * `tokenWillExpire` refresh timer from the current token's `expires_at`.
 	 * @returns {Promise<void>}
 	 */
 	register() {
+		this._stopped = false; // an intentional (re)start re-arms the device
 		if (this._registered) return Promise.resolve();
 		if (!this._ua) this._initUA();
 
@@ -92,6 +131,7 @@ export class Device {
 			const onOk = () => {
 				this._ua.removeListener("registered", onOk);
 				this._ua.removeListener("registrationFailed", onFail);
+				this._scheduleTokenRefresh();
 				resolve();
 			};
 			const onFail = (e) => {
@@ -106,18 +146,55 @@ export class Device {
 	}
 
 	/**
-	 * Unregister and close the WSS connection. Idempotent.
+	 * Unregister and close the WSS connection. Idempotent. Marks the device
+	 * stopped so any in-flight token refresh cannot bring it back online, and
+	 * cancels the refresh timer + pending state.
 	 * @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(); }
-		});
+		this._stopped = true;
+		this._clearTokenRefresh();
+		this._pendingToken = null;
+		this._refreshPendingAuto = false;
+		return this._teardownUA();
+	}
+
+	/**
+	 * Apply a fresh token so the registration never lapses — call this in
+	 * response to `tokenWillExpire` (or let `tokenProvider` do it).
+	 *
+	 * Identity-preserving fast path: if the token carries the SAME identity +
+	 * password as the current one (i.e. your backend called POST
+	 * /voice/tokens/refresh to extend in place), the existing registration is
+	 * still valid, so the Device just updates `expires_at` and reschedules — no
+	 * re-register, fully seamless, safe even mid-call.
+	 *
+	 * Identity change (a fresh mint): the Device re-registers under the new
+	 * identity (break-before-make), deferred while a call is active and applied
+	 * once the last call ends, so live audio is never disrupted.
+	 *
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 * @returns {Promise<void>} resolves once applied (or immediately when a swap
+	 *   is deferred behind an active call).
+	 */
+	async updateToken(tokenOrCreds) {
+		const creds = this._parseCreds(tokenOrCreds, "Device.updateToken");
+		const newIdentity = tokenOrCreds?.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._scheduleTokenRefresh();
+			return;
+		}
+
+		// Identity changed → full re-register; defer while a call is active.
+		if (this._activeSessions.size > 0) {
+			this._pendingToken = tokenOrCreds;
+			return;
+		}
+		await this._applyToken(tokenOrCreds);
 	}
 
 	/**
@@ -162,6 +239,7 @@ export class Device {
 			extraHeaders: headers,
 		});
 
+		this._trackSession(session);
 		return new Call({ session, direction: "outbound" });
 	}
 
@@ -192,6 +270,173 @@ export class Device {
 		}
 	}
 
+	/**
+	 * Unwrap `sip_credentials` from a token response (or accept a bare creds
+	 * object) and validate the four required SIP fields.
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 * @param {string} ctx - Caller label used in the error message.
+	 * @returns {SipCredentials}
+	 * @throws {Error} when a required field is missing.
+	 */
+	_parseCreds(tokenOrCreds, ctx) {
+		const creds = 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)`);
+		}
+		return creds;
+	}
+
+	/**
+	 * Stop the current UA and close its WSS, without touching lifecycle flags —
+	 * used both by unregister() and by _applyToken()'s break-before-make swap.
+	 * @returns {Promise<void>}
+	 */
+	_teardownUA() {
+		if (!this._ua) return Promise.resolve();
+		return new Promise((resolve) => {
+			const ua = this._ua;
+			const done = () => { try { ua.stop(); } catch {} resolve(); };
+			if (!this._registered) return done();
+			ua.once("unregistered", done);
+			try { ua.unregister(); }
+			catch { done(); }
+		});
+	}
+
+	/**
+	 * Re-register under fresh credentials when the identity changed
+	 * (break-before-make). Only invoked when no call is active (updateToken
+	 * defers while busy). Bails if the app tore the device down mid-swap; if the
+	 * new registration fails, surfaces `tokenRefreshFailed` and re-arms a short
+	 * retry so the device recovers rather than sitting unregistered.
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 */
+	async _applyToken(tokenOrCreds) {
+		const creds = this._parseCreds(tokenOrCreds, "Device.updateToken");
+		this._clearTokenRefresh();
+		try { await this._teardownUA(); } catch { /* ignore — tearing down anyway */ }
+		if (this._stopped) return; // unregister() ran while we were tearing down
+
+		this._ua = null;
+		this._registered = false;
+		this._credentials = creds;
+		this.identity = tokenOrCreds?.identity || creds.username;
+		this.expiresAt = tokenOrCreds?.expires_at || null;
+
+		try {
+			await this.register(); // rebuilds the UA + reschedules the refresh timer
+		} catch (err) {
+			this._emit("tokenRefreshFailed", { error: err });
+			if (!this._stopped) {
+				this._clearTokenRefresh();
+				this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), 5000);
+			}
+			throw err; // propagate to a manual updateToken() caller
+		}
+	}
+
+	/** `expires_at` as epoch ms, or null when unparseable/absent. */
+	_expiresAtMs() {
+		const t = Date.parse(this.expiresAt || "");
+		return Number.isFinite(t) ? t : null;
+	}
+
+	/**
+	 * 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
+	 * @returns {boolean}
+	 */
+	_isTokenStale(tokenOrCreds) {
+		const exp = Date.parse(tokenOrCreds?.expires_at || "");
+		if (!Number.isFinite(exp)) return false;
+		return exp - Date.now() <= this._opts.tokenRefreshMs;
+	}
+
+	/** Arm the one-shot `tokenWillExpire` timer for tokenRefreshMs before expiry. */
+	_scheduleTokenRefresh() {
+		this._clearTokenRefresh();
+		const expMs = this._expiresAtMs();
+		if (expMs === null) return; // no expiry info → caller manages refresh manually
+		const delay = Math.max(0, expMs - Date.now() - this._opts.tokenRefreshMs);
+		this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), delay);
+	}
+
+	/** Cancel the pending `tokenWillExpire` timer, if any. */
+	_clearTokenRefresh() {
+		if (this._refreshTimer) { clearTimeout(this._refreshTimer); this._refreshTimer = null; }
+	}
+
+	/**
+	 * Fired shortly before the current token expires. Emits `tokenWillExpire`
+	 * for manual handlers; if a `tokenProvider` is configured, also fetches a
+	 * fresh token and applies it. Deferred while a call is active (the fetch
+	 * happens only once idle, so a fetched token can't go stale in hand). Bails
+	 * if the device was torn down while the fetch was in flight.
+	 */
+	async _onTokenWillExpire() {
+		if (this._stopped) return;
+		this._emit("tokenWillExpire", { identity: this.identity, expiresAt: this.expiresAt });
+		if (!this._opts.tokenProvider) return; // app handles it via updateToken()
+		if (this._activeSessions.size > 0) {
+			this._refreshPendingAuto = true; // fetch + apply once the call ends
+			return;
+		}
+		try {
+			const fresh = await this._opts.tokenProvider();
+			if (this._stopped) return; // torn down while the provider fetch was pending
+			if (!fresh) throw new Error("tokenProvider returned no token");
+			await this.updateToken(fresh);
+		} catch (err) {
+			if (this._stopped) return;
+			this._emit("tokenRefreshFailed", { error: err });
+			// Retry shortly so a transient failure doesn't strand us, provided
+			// there's still time before the current token expires.
+			const expMs = this._expiresAtMs();
+			if (expMs !== null && expMs - Date.now() > 5000) {
+				this._clearTokenRefresh();
+				this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), 5000);
+			}
+		}
+	}
+
+	/** Track a call session so an identity swap can be deferred until it ends. */
+	_trackSession(session) {
+		if (!session) return;
+		this._activeSessions.add(session);
+		const done = () => this._untrackSession(session);
+		try { session.on("ended", done); session.on("failed", done); }
+		catch { /* not a JsSIP session — best-effort tracking only */ }
+	}
+
+	/**
+	 * Stop tracking a finished session. When the line goes fully idle, apply any
+	 * token refresh that was deferred behind the call: a `tokenProvider` fetch
+	 * (fresh) or a stored identity-change token — re-fetching instead if that
+	 * stored token has gone stale while the call ran.
+	 * @param {object} session - The JsSIP session that ended/failed.
+	 */
+	_untrackSession(session) {
+		this._activeSessions.delete(session);
+		if (this._activeSessions.size > 0 || this._stopped) return;
+
+		if (this._refreshPendingAuto) {
+			this._refreshPendingAuto = false;
+			this._onTokenWillExpire();
+		} else if (this._pendingToken) {
+			const pending = this._pendingToken;
+			this._pendingToken = null;
+			// A long call can outlive the token we stashed — don't register with
+			// stale creds; get a fresh one the same way the timer would.
+			if (this._isTokenStale(pending)) {
+				this._onTokenWillExpire();
+			} else {
+				this._applyToken(pending).catch((err) => this._emit("tokenRefreshFailed", { error: err }));
+			}
+		}
+	}
+
 	_initUA() {
 		const socket = new JsSIP.WebSocketInterface(this._credentials.wss_url);
 		this._ua = new JsSIP.UA({
@@ -219,6 +464,7 @@ export class Device {
 
 		this._ua.on("newRTCSession", (e) => {
 			if (e.originator !== "remote") return; // outbound: we already wrap in connect()
+			this._trackSession(e.session);
 			const call = new Call({ session: e.session, direction: "inbound", request: e.request });
 			this._emit("incoming", call);
 		});