@subiz/wsclient 4.0.34 → 4.0.36

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/thanh/Developer/wsclient log --oneline -5 -- '*webphone*')",
+      "Bash(node --check /Users/thanh/Developer/wsclient/webphone.js)",
+      "Bash(npx prettier *)",
+      "Bash(node --check realtime.js)",
+      "Bash(git *)",
+      "Bash(node *)"
+    ]
+  }
+}

package/README.md

@@ -1,23 +1,26 @@
 # Subiz wsclient
 
-This library implements subiz long polling protocol
+This library implements the Subiz long polling protocol. It keeps a realtime
+connection to the Subiz realtime server, lets you subscribe to event topics and
+delivers new events to you as fast as possible.
 
-## Method
+It also ships a `WebPhone` client (built on top of the realtime connection and
+WebRTC) for making and answering calls in the browser.
 
-### subscribe
+## Install
 
-### onEvent
-
-### stop
+```sh
+npm install @subiz/wsclient
+```
 
-## Example
+## Realtime
 
 ```js
 var Realtime = require('@subiz/wsclient')
-var realtime = new Realtime('https://realtime-0.subiz.net/', {
+
+var realtime = new Realtime('https://api.subiz.com.vn/rt/0/', {
 	account_id: 'ac1234',
-	getAccessToken: () => '333344',
-	user_mask: 'mask123',
+	getAccessToken: () => Promise.resolve('333344'),
 })
 
 realtime.onEvent((ev) => console.log(ev))
@@ -28,3 +31,112 @@ console.log(realtime.getStatus()) // 'active'
 
 realtime.stop()
 ```
+
+### new Realtime(apiUrls, credential, [callAPI], [accid], [skipautoreconnect])
+
+- `apiUrls`: a realtime endpoint (string) or a list of endpoints, each must end
+  with `/`. When a list is given, one endpoint is picked at random per
+  connection.
+- `credential`: `{account_id, getAccessToken, user_ref, user_mask}`.
+  `getAccessToken` should return a Promise resolving to the access token
+  (returning a plain string also works). `user_ref` or `user_mask` are used
+  instead of the access token when present.
+- `callAPI` (optional): custom HTTP function `(method, url, body, cb)` used
+  instead of the built-in XHR, mainly for testing.
+- `accid` (optional): account id, defaults to `credential.account_id`.
+- `skipautoreconnect` (optional): when true, the connection is not recreated
+  automatically after it dies.
+
+The connection auto-reconnects 2 seconds after it dies and resubscribes all
+previously subscribed topics. Polling is throttled to at most 4 requests per
+second even if the server misbehaves and answers instantly.
+
+### subscribe(topics)
+
+Tells the server we are listening for those topics. `topics` is a string or an
+array of strings. Already-subscribed topics are skipped, so it is safe to call
+multiple times. Calls are batched (up to 50 topics per request).
+
+Returns a Promise resolving to `{}` on success or `{error}` on failure.
+
+### onEvent(callback)
+
+Registers a callback that is called with each incoming event.
+
+### onInterrupted(callback)
+
+Registers a callback that is called whenever the connection dies (before an
+automatic reconnect) or is stopped.
+
+### getStatus()
+
+Returns the current connection status: `'active'`, `'connecting'` (having
+trouble reaching the server, retrying) or `'dead'`.
+
+### stop()
+
+Kills the connection and disables auto-reconnect. Call `reconnect()` to start
+a new connection again.
+
+### reconnect()
+
+Drops the current connection (if any), creates a new one and resubscribes all
+topics. Returns the resubscribe Promise.
+
+## WebPhone
+
+```js
+var WebPhone = require('@subiz/wsclient/webphone.js')
+
+var phone = new WebPhone('ac1234_ag5678_...') // agent access token
+
+phone.onEvent((ev) => console.log(ev.type, ev.data.call_info))
+
+// outbound call, the from-number is picked from the account's activated
+// call integrations, and automatically falls back to the next number when
+// the call fails
+var call = await phone.makeCall('84900000000')
+
+// or force specific from-numbers
+await phone.makeCall('84900000000', ['84911111111', '84922222222'])
+
+phone.sendDtmf('1', callid)
+phone.transferCall('84933333333', callid)
+phone.hangupCall(callid)
+
+// inbound: answer a ringing call
+await phone.answerWebCall(callid)
+```
+
+### new WebPhone(access_token, [realtime])
+
+`access_token` must be an agent token of the form `ac..._ag..._...`. A
+`Realtime` instance is created automatically unless you pass your own.
+An invisible `<audio>` tag is appended to the document to play the remote
+audio.
+
+### Methods
+
+- `makeCall(number, [fromnumbers], [streamPm])`: starts an outbound call and
+  returns a Promise resolving to the ended call object. `fromnumbers` is a
+  number, a string or an array of numbers to call from (defaults to all
+  activated call integrations). On `terminated`/`failure`/`congestion` the
+  call is retried with the next from-number until none is left (then it
+  resolves with the last failed result, or `error: 'out_of_number'` when
+  there was no number to call from at all).
+- `answerWebCall(callid)`: asks for microphone permission and answers an
+  incoming call.
+- `hangupCall([callid])`: hangs up the given call, defaults to the current
+  call.
+- `sendDtmf(key, callid)`: sends a DTMF key press.
+- `transferCall(number, callid)`: transfers the call to another number.
+- `onEvent(callback)`: subscribes to call events (`call_ringing`,
+  `call_ended`, ...).
+- `getCall(callid)` / `getCurrentCall()` / `getCurrentCallId()`: look up call
+  state.
+- `isMicAllowed()`: resolves to `true`/`false` whether microphone access is
+  granted.
+- `checkMic()`: returns `{timeout, result}` promises for microphone
+  permission, `timeout` resolves with `'Not_authorized'` after 500ms if the
+  user has not decided yet.
+- `getMicroStream()`: returns the current microphone `MediaStream` if any.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@subiz/wsclient",
-	"version": "4.0.34",
+	"version": "4.0.36",
 	"main": "realtime.js",
 	"scripts": {
 		"dev": "vite",
@@ -15,8 +15,8 @@
 	"homepage": "https://github.com/subiz/wsclient#readme",
 	"description": "",
 	"devDependencies": {
-		"tape": "^5.9.0",
-		"vite": "^6.3.5",
+		"tape": "^5.10.2",
+		"vite": "^8.2.1",
 		"vite-plugin-commonjs": "^0.10.4"
 	},
 	"dependencies": {

package/realtime.js

@@ -28,13 +28,24 @@ function Conn(apiUrl, credential, onDead, onEvents, callAPI, accid) {
 	// using an exponential backoff strategy. It will terminate if an unretryable
 	// error is encountered.
 	// The first loop begins after the first subscription call completes successfully
+	var MIN_POLL_INTERVAL = 250 // max 4 req/s, in case the server returns instantly instead of holding the long poll
+	var last_poll_at = 0
+	var polling_started = false // make sure only one polling loop is running
+	var startPolling = function () {
+		if (polling_started) return
+		polling_started = true
+		polling(0)
+	}
 	var polling = function (backoff) {
 		if (is_dead) return
+		last_poll_at = Date.now()
 		callAPI('get', apiUrl + 'poll?token=' + lastToken + '&v=5&account-id=' + accid, undefined, function (body, code) {
 			if (is_dead) return
+			var wait = MIN_POLL_INTERVAL - (Date.now() - last_poll_at)
+			if (wait < 0) wait = 0
 			if (retryable(code)) {
 				is_polling_stuck = true
-				return setTimeout(polling, calcNextBackoff(backoff), backoff + 1)
+				return setTimeout(polling, Math.max(calcNextBackoff(backoff), wait), backoff + 1)
 			}
 
 			if (code !== 200) {
@@ -53,6 +64,7 @@ function Conn(apiUrl, credential, onDead, onEvents, callAPI, accid) {
 			if (!seqToken) return kill('poll')
 			lastToken = seqToken
 			onEvents(body.events || [])
+			if (wait > 0) return setTimeout(polling, wait, 0)
 			return polling(0)
 		})
 	}
@@ -89,64 +101,73 @@ function Conn(apiUrl, credential, onDead, onEvents, callAPI, accid) {
 				}
 
 				var query = '?token=' + lastToken
-				credential.getAccessToken().then(function (access_token) {
-					if (is_dead) {
-						resolve(repeat('dead', topics.length))
-						return rs(false) // break loop
-					}
-
-					if (credential.user_ref) query += '&user_ref=' + encodeURIComponent(credential.user_ref)
-					else if (credential.user_mask) query += '&user-mask=' + encodeURIComponent(credential.user_mask)
-					else if (access_token) query += '&access-token=' + access_token
-
-					var fullurl =
-						apiUrl + 'subs' + query + '&v=5&account-id=' + encodeURIComponent(accid || credential.account_id)
-					callAPI('post', fullurl, JSON.stringify({events: topics}), function (body, code) {
-						if (done) return
+				Promise.resolve()
+					.then(function () {
+						return credential.getAccessToken()
+					})
+					.then(function (access_token) {
 						if (is_dead) {
 							resolve(repeat('dead', topics.length))
 							return rs(false) // break loop
 						}
 
-						if (retryable(code)) {
-							is_sub_stuck = true
-							return setTimeout(rs, 3000, true)
-						}
-
-						// unretryable error
-						if (code !== 200) {
-							// we are unable to start the communication with the realtime server.
-							// Must notify the user by killing the connection
-							kill('subs')
-							resolve(repeat('dead', topics.length))
-							return rs(false)
-						}
-						is_sub_stuck = false
-						done = true
-						if (lastToken) {
+						if (credential.user_ref) query += '&user_ref=' + encodeURIComponent(credential.user_ref)
+						else if (credential.user_mask) query += '&user-mask=' + encodeURIComponent(credential.user_mask)
+						else if (access_token) query += '&access-token=' + access_token
+
+						var fullurl =
+							apiUrl + 'subs' + query + '&v=5&account-id=' + encodeURIComponent(accid || credential.account_id)
+						callAPI('post', fullurl, JSON.stringify({events: topics}), function (body, code) {
+							if (done) return
+							if (is_dead) {
+								resolve(repeat('dead', topics.length))
+								return rs(false) // break loop
+							}
+
+							if (retryable(code)) {
+								is_sub_stuck = true
+								return setTimeout(rs, 3000, true)
+							}
+
+							// unretryable error
+							if (code !== 200) {
+								// we are unable to start the communication with the realtime server.
+								// Must notify the user by killing the connection
+								kill('subs')
+								resolve(repeat('dead', topics.length))
+								return rs(false)
+							}
+							is_sub_stuck = false
+							done = true
+							if (lastToken) {
+								resolve(topics)
+								return rs(false)
+							}
+
+							// first time sub, should grab the initial token
+							body = parseJSON(body) || {}
+							var initialToken = body.initial_token
+							// the server returns a malform payload. We should end
+							if (!initialToken) {
+								kill('subs')
+								resolve(repeat('dead', topics.length))
+								return rs(false) // break loop
+							}
+
+							// learn new host
+							if (body.host) apiUrl = absUrl(body.host)
+
+							lastToken = initialToken
+							startPolling()
 							resolve(topics)
-							return rs(false)
-						}
-
-						// first time sub, should grab the initial token
-						body = parseJSON(body) || {}
-						var initialToken = body.initial_token
-						// the server returns a malform payload. We should end
-						if (!initialToken) {
-							kill('subs')
-							resolve(repeat('dead', topics.length))
-							return rs(false) // break loop
-						}
-
-						// learn new host
-						if (body.host) apiUrl = absUrl(body.host)
-
-						lastToken = initialToken
-						polling(0)
-						resolve(topics)
-						return rs(false) // to break the loop
+							return rs(false) // to break the loop
+						})
+					})
+					.catch(function () {
+						// getAccessToken failed, retry instead of hanging the loop
+						is_sub_stuck = true
+						setTimeout(rs, 3000, true)
 					})
-				})
 			})
 		})
 
@@ -192,8 +213,11 @@ function Realtime(apiUrls, credential, callAPI, accid, skipautoreconnect) {
 	// stop the connection
 	this.stop = function () {
 		if (!conn) return
-		conn.kill()
+		// detach before killing so onDead knows this is intentional and
+		// doesn't schedule a reconnect
+		var oldconn = conn
 		conn = undefined
+		oldconn.kill()
 		pubsub.emit('interrupted')
 	}
 
@@ -237,7 +261,14 @@ function Realtime(apiUrls, credential, callAPI, accid, skipautoreconnect) {
 	var conn
 	var reconnect = function () {
 		var randomUrl = apiUrls[Math.floor(Math.random() * apiUrls.length)]
-		if (conn) conn.kill() // kill old connection
+		if (conn) {
+			// detach before killing so the old conn's onDead doesn't
+			// schedule another reconnect (which would kill this new conn,
+			// schedule another one, and churn forever)
+			var oldconn = conn
+			conn = undefined
+			oldconn.kill()
+		}
 		var myconn = new Conn(
 			randomUrl,
 			credential,

package/webphone.js

@@ -34,7 +34,7 @@ function WebPhone(access_token, realtime) {
 					rs(access_token)
 				})
 			},
-		})
+		}, undefined, accid)
 
 	var webrtcconn = new WebRTCConn({
 		accid: accid,
@@ -52,6 +52,7 @@ function WebPhone(access_token, realtime) {
 		},
 		onTrack: function (event) {
 			if (event.track.kind != 'audio') return
+			if (!$audio) return
 			$audio.srcObject = event.streams[0]
 		},
 	})
@@ -100,8 +101,8 @@ function WebPhone(access_token, realtime) {
 
 	var me = this
 	this.isMicAllowed = function () {
-		return me.checkMic().then(function (out) {
-			return out.result
+		return me.checkMic().result.then(function (stream) {
+			return !!stream
 		})
 	}
 
@@ -117,7 +118,7 @@ function WebPhone(access_token, realtime) {
 		var microPermission = getMicroPermissions()
 		return {
 			timeout: Promise.race([timeout, microPermission]),
-			result: getMicroPermissions(),
+			result: microPermission,
 		}
 	}
 
@@ -142,8 +143,8 @@ function WebPhone(access_token, realtime) {
 			getMicroPermissions().then(function (stream) {
 				current_call_id = callid
 				webrtcconn.answerCall(callid, stream).then(function (out) {
-					if (out.error) return rs({error})
-					rs(body)
+					if (out.error) return rs({error: out.error})
+					rs(out.body)
 				})
 			})
 		})
@@ -163,7 +164,7 @@ function WebPhone(access_token, realtime) {
 			fromnumbers = _numbers
 		}
 
-		if (typeof fromnumbers === 'string' || fromnumbers instanceof String || typeof value === 'number') {
+		if (typeof fromnumbers === 'string' || fromnumbers instanceof String || typeof fromnumbers === 'number') {
 			fromnumbers = [fromnumbers + '']
 		}
 
@@ -176,7 +177,7 @@ function WebPhone(access_token, realtime) {
 
 		let callnumber = chooseCallNumber(fromnumbers, _state.called)
 		if (!callnumber)
-			return (
+			return Promise.resolve(
 				_state.last_result || {
 					start: Date.now(),
 					ended: Date.now(),
@@ -198,7 +199,7 @@ function WebPhone(access_token, realtime) {
 				if (!_state.called) _state.called = {}
 				_state.called[callnumber] = true
 				_state.last_result = out
-				return this.makeCall(number, fromnumbers, streamPm, _a, _b, _state)
+				return me.makeCall(number, fromnumbers, streamPm, _a, _b, _state)
 			}
 			return out
 		})