yoto-nodejs-client 0.0.4 → 0.0.6

package/lib/mqtt/factory.js

@@ -7,6 +7,7 @@
 
 /**
  * @import { IClientOptions } from 'mqtt'
+ * @import { RefreshableToken } from '../token.js'
  */
 
 // ============================================================================
@@ -21,12 +22,13 @@
 /**
  * @typedef {Object} YotoMqttOptions
  * @property {string} deviceId - Device ID to connect to
- * @property {string} accessToken - JWT access token for authentication
+ * @property {RefreshableToken} token - RefreshableToken instance used to supply the current JWT. Enables auto-updating auth on reconnect via transformWsUrl.
+ * @property {string} [sessionId=randomUUID()] - Stable unique session ID suffix used to avoid collisions across multiple clients/processes. Used to build the MQTT clientId: DASH${deviceId}${sessionId} (non-alphanumeric characters are stripped). (MQTT calls this clientId, but we call it sessionId to not confuse it with the oauth clientId)
  * @property {string} [clientIdPrefix='DASH'] - Prefix for MQTT client ID (default: 'DASH')
  * @property {string} [brokerUrl='wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com'] - MQTT broker URL
  * @property {number} [port=443] - MQTT broker port
  * @property {boolean} [autoSubscribe=true] - Auto-subscribe to device topics on connect
- * @property {MqttClientOptions} [mqttOptions] - Additional MQTT.js client options (defaults: reconnectPeriod=5000, keepalive=300; cannot override: clientId, username, password, protocol, ALPNProtocols)
+ * @property {MqttClientOptions} [mqttOptions] - Additional MQTT.js client options (defaults: reconnectPeriod=5000, reconnectOnConnackError=true, keepalive=300, clean=false; cannot override: clientId, username, password, protocol, ALPNProtocols; transformWsUrl is wrapped to keep auth current)
  */
 
 import mqtt from 'mqtt'
@@ -39,6 +41,7 @@ import {
   MQTT_KEEPALIVE,
   MQTT_ALPN_PROTOCOLS
 } from './topics.js'
+import { randomUUID } from 'node:crypto'
 
 /**
  * Create a configured MQTT client for a Yoto device
@@ -52,7 +55,8 @@ import {
  *
  * const client = createYotoMqttClient({
  *   deviceId: 'abc123',
- *   accessToken: 'eyJhbGc...'
+ *   token,
+ *   clientId: 'my-unique-client-id'
  * })
  *
  * client.on('events', (message) => {
@@ -67,7 +71,8 @@ import {
  * // Disable automatic reconnection
  * const client = createYotoMqttClient({
  *   deviceId: 'abc123',
- *   accessToken: 'token',
+ *   token,
+ *   clientId: 'my-unique-client-id',
  *   mqttOptions: {
  *     reconnectPeriod: 0,     // Disable auto-reconnect (default is 5000ms)
  *     connectTimeout: 30000   // 30 second connection timeout
@@ -81,14 +86,15 @@ export function createYotoMqttClient (options) {
     throw new Error('deviceId is required')
   }
 
-  if (!options.accessToken) {
-    throw new Error('accessToken is required')
+  if (!options.token) {
+    throw new Error('token is required')
   }
 
   // Extract options with defaults
   const {
     deviceId,
-    accessToken,
+    token,
+    sessionId = randomUUID(),
     clientIdPrefix = 'DASH',
     brokerUrl = MQTT_BROKER_URL,
     port = MQTT_PORT,
@@ -97,26 +103,48 @@ export function createYotoMqttClient (options) {
   } = options
 
   // Build MQTT client ID
-  const clientId = `${clientIdPrefix}${deviceId}`
+  const mqttSessionId = (`${clientIdPrefix}${deviceId}${sessionId}`).replace(/[^a-zA-Z0-9]/g, '')
 
   // Build username with authorizer
   const username = `${deviceId}?x-amz-customauthorizer-name=${MQTT_AUTH_NAME}`
 
+  const userTransformWsUrl = additionalMqttOptions.transformWsUrl
+
+  /** @type {IClientOptions['transformWsUrl']} */
+  const transformWsUrl = (url, mqttOptions, client) => {
+    // Ensure the CONNECT auth uses the latest access token for every websocket (re)connect.
+    const latestAccessToken = token.accessToken
+    client.options.password = latestAccessToken
+
+    let nextUrl = url
+    if (typeof userTransformWsUrl === 'function') {
+      nextUrl = userTransformWsUrl(url, mqttOptions, client)
+    }
+
+    // Re-apply in case user hook mutated it.
+    client.options.password = latestAccessToken
+
+    return nextUrl
+  }
+
   // Create MQTT connection options
   // Merge additional options first, then override with required Yoto settings
   /** @type {IClientOptions} */
   const mqttOptions = {
     // Defaults (can be overridden by additionalMqttOptions)
     reconnectPeriod: 5000, // Default: auto-reconnect after 5 seconds
+    reconnectOnConnackError: true, // Default: keep reconnecting after CONNACK auth errors (token refresh may fix it)
     keepalive: MQTT_KEEPALIVE, // Default: 300 seconds (5 minutes)
+    clean: false, // Default: persistent session for stable subscriptions on the broker
     ...additionalMqttOptions, // Allow overriding defaults
     // Required Yoto-specific settings (cannot be overridden)
-    clientId,
+    clientId: mqttSessionId,
     username,
-    password: accessToken,
+    password: token.accessToken,
     port,
     protocol: MQTT_PROTOCOL,
-    ALPNProtocols: MQTT_ALPN_PROTOCOLS
+    ALPNProtocols: MQTT_ALPN_PROTOCOLS,
+    transformWsUrl
   }
 
   // Create underlying MQTT client (not connected yet)

package/lib/mqtt/index.js

@@ -10,7 +10,8 @@
  *
  * const client = createYotoMqttClient({
  *   deviceId: 'abc123',
- *   accessToken: 'eyJhbGc...'
+ *   token,
+ *   clientId: 'my-unique-client-id'
  * })
  *
  * client.on('events', (message) => {

package/lib/mqtt/mqtt.test.js

@@ -1,15 +1,17 @@
 import test from 'node:test'
 import assert from 'node:assert'
+import { randomUUID } from 'node:crypto'
 import { getDevices } from '../api-endpoints/devices.js'
 import { loadTestTokens, logResponse } from '../api-endpoints/endpoint-test-helpers.js'
 import { createYotoMqttClient } from './index.js'
 
-const { accessToken } = loadTestTokens()
+const { token } = loadTestTokens()
 
 test('MQTT client', async (t) => {
   await t.test('should connect, request status/events, and receive response and events messages (status-legacy is optional)', async () => {
     // Get an online device
-    const response = await getDevices({ accessToken })
+
+    const response = await getDevices({ accessToken: await token.getAccessToken() })
     assert.ok(response.devices.length > 0, 'Should have at least one device')
 
     const onlineDevice = response.devices.find(d => d.online)
@@ -20,7 +22,8 @@ test('MQTT client', async (t) => {
     // Create MQTT client
     const mqttClient = createYotoMqttClient({
       deviceId,
-      accessToken
+      token,
+      sessionId: randomUUID()
     })
 
     // Track received messages
@@ -39,15 +42,15 @@ test('MQTT client', async (t) => {
       try {
         // Validate events message structure
         assert.ok(payload, 'Events message should exist')
-        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.equal(typeof topic, 'string', 'Topic should be a string')
         assert.ok(topic.includes('/data/events'), 'Topic should contain /data/events')
 
         // Events messages are partial - not all fields are always present
         if (payload.playbackStatus !== undefined) {
-          assert.ok(typeof payload.playbackStatus === 'string', 'playbackStatus should be string')
+          assert.equal(typeof payload.playbackStatus, 'string', 'playbackStatus should be string')
         }
         if (payload.cardId !== undefined) {
-          assert.ok(typeof payload.cardId === 'string', 'cardId should be string')
+          assert.equal(typeof payload.cardId, 'string', 'cardId should be string')
         }
 
         eventsMessageReceived = true
@@ -62,14 +65,14 @@ test('MQTT client', async (t) => {
       try {
         // Validate status message structure
         assert.ok(payload, 'Status message should exist')
-        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.equal(typeof topic, 'string', 'Topic should be a string')
         assert.ok(topic.includes('/data/status'), 'Topic should contain /data/status')
         assert.ok(payload.status, 'Status message should have status object')
-        assert.ok(typeof payload.status.statusVersion === 'number', 'Should have statusVersion number')
-        assert.ok(typeof payload.status.fwVersion === 'string', 'Should have fwVersion string')
-        assert.ok(typeof payload.status.productType === 'string', 'Should have productType string')
-        assert.ok(typeof payload.status.batteryLevel === 'number', 'Should have batteryLevel number')
-        assert.ok(typeof payload.status.volume === 'number', 'Should have volume number')
+        assert.equal(typeof payload.status.statusVersion, 'number', 'Should have statusVersion number')
+        assert.equal(typeof payload.status.fwVersion, 'string', 'Should have fwVersion string')
+        assert.equal(typeof payload.status.productType, 'string', 'Should have productType string')
+        assert.equal(typeof payload.status.batteryLevel, 'number', 'Should have batteryLevel number')
+        assert.equal(typeof payload.status.volume, 'number', 'Should have volume number')
 
         statusMessageReceived = true
       } catch (err) {
@@ -83,33 +86,33 @@ test('MQTT client', async (t) => {
       try {
         // Validate legacy status message structure
         assert.ok(payload, 'Legacy status message should exist')
-        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.equal(typeof topic, 'string', 'Topic should be a string')
         assert.ok(!topic.includes('/data/'), 'Legacy topic should NOT contain /data/')
         assert.ok(payload.status, 'Legacy status message should have status object')
 
         // Validate lifecycle fields unique to legacy format
-        assert.ok(typeof payload.status.statusVersion === 'number', 'Should have statusVersion number')
-        assert.ok(typeof payload.status.fwVersion === 'string', 'Should have fwVersion string')
+        assert.equal(typeof payload.status.statusVersion, 'number', 'Should have statusVersion number')
+        assert.equal(typeof payload.status.fwVersion, 'string', 'Should have fwVersion string')
 
         // shutDown field is the key field for lifecycle events
         if (payload.status.shutDown !== undefined) {
-          assert.ok(typeof payload.status.shutDown === 'string', 'shutDown should be string')
+          assert.equal(typeof payload.status.shutDown, 'string', 'shutDown should be string')
         }
 
         // upTime and utcTime are key for startup detection
         if (payload.status.upTime !== undefined) {
-          assert.ok(typeof payload.status.upTime === 'number', 'upTime should be number')
+          assert.equal(typeof payload.status.upTime, 'number', 'upTime should be number')
         }
         if (payload.status.utcTime !== undefined) {
-          assert.ok(typeof payload.status.utcTime === 'number', 'utcTime should be number')
+          assert.equal(typeof payload.status.utcTime, 'number', 'utcTime should be number')
         }
 
         // Hardware diagnostic fields unique to legacy
         if (payload.status.battery !== undefined) {
-          assert.ok(typeof payload.status.battery === 'number', 'battery should be number')
+          assert.equal(typeof payload.status.battery, 'number', 'battery should be number')
         }
         if (payload.status.wifiStrength !== undefined) {
-          assert.ok(typeof payload.status.wifiStrength === 'number', 'wifiStrength should be number')
+          assert.equal(typeof payload.status.wifiStrength, 'number', 'wifiStrength should be number')
         }
 
         statusLegacyMessageReceived = true
@@ -124,10 +127,10 @@ test('MQTT client', async (t) => {
       try {
         // Validate response message structure
         assert.ok(payload, 'Response message should exist')
-        assert.ok(typeof topic === 'string', 'Topic should be a string')
+        assert.equal(typeof topic, 'string', 'Topic should be a string')
         assert.ok(topic.includes('/response'), 'Topic should contain /response')
         assert.ok(payload.status, 'Response should have status object')
-        assert.ok(typeof payload.status.req_body === 'string', 'Response should have req_body string')
+        assert.equal(typeof payload.status.req_body, 'string', 'Response should have req_body string')
 
         // Check if status request was acknowledged (field name is 'status/request')
         if (payload.status['status/request']) {

package/lib/token.d.ts

@@ -3,8 +3,16 @@
  * @property {string} clientId - OAuth client ID
  * @property {string} refreshToken - OAuth refresh token
  * @property {string} accessToken - Initial OAuth access token (JWT)
+ * @property {OnTokenRefreshHandler} onTokenRefresh - A function that will receive the refreshed token info and perisist it for future use
  * @property {number} [bufferSeconds=30] - Seconds before expiration to consider token expired
  */
+/**
+ * This is a REQUIRED function. It gets called after the token is refreshed with new tokens.
+ * It should save the new tokens somewhere. When starting back up, re-use the newly perissted tokens.
+ * If you loose track of these new tokens, you will effectively be logged out.
+ *
+ * @typedef {(refreshSuccessEvent: RefreshSuccessEvent) => void | Promise<void>} OnTokenRefreshHandler
+ */
 /**
  * @typedef {Object} RefreshSuccessEvent
  * @property {string} clientId - The OAuth client ID
@@ -30,7 +38,7 @@
  *
  * Events:
  * - 'refresh:start' - Emitted when token refresh begins
- * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, accessToken, refreshToken, expiresAt }
+ * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken, prevExpiresAt }
  * - 'refresh:error' - Emitted when token refresh fails (transient errors), passes error
  * - 'invalid' - Emitted when refresh token is permanently invalid, passes error
  *
@@ -40,13 +48,37 @@ export class RefreshableToken extends EventEmitter<RefreshableTokenEventMap> {
     /**
      * @param {RefreshableTokenOpts} opts
      */
-    constructor({ clientId, refreshToken, accessToken, bufferSeconds }: RefreshableTokenOpts);
+    constructor({ clientId, refreshToken, accessToken, bufferSeconds, onTokenRefresh }: RefreshableTokenOpts);
     /**
      * Get a valid access token, refreshing if necessary.
      * @returns {Promise<string>} Valid access token
      * @throws {Error} If token is invalid or refresh fails
      */
     getAccessToken(): Promise<string>;
+    /**
+     * Stop background token refresh scheduling.
+     */
+    stopAutoRefresh(): void;
+    /**
+     * Start background token refresh scheduling (enabled by default).
+     */
+    startAutoRefresh(): void;
+    /**
+     * Check if background token refresh scheduling is enabled.
+     * @returns {boolean}
+     */
+    isAutoRefreshEnabled(): boolean;
+    /**
+     * Get the current OAuth client ID (synchronous).
+     * @returns {string}
+     */
+    get clientId(): string;
+    /**
+     * Get the latest access token value (synchronous).
+     * Prefer getAccessToken() if you need a guaranteed-valid token in async contexts.
+     * @returns {string}
+     */
+    get accessToken(): string;
     /**
      * Check if the token is currently valid (not expired and not marked invalid).
      * @returns {boolean} True if token is valid
@@ -84,11 +116,21 @@ export type RefreshableTokenOpts = {
      * - Initial OAuth access token (JWT)
      */
     accessToken: string;
+    /**
+     * - A function that will receive the refreshed token info and perisist it for future use
+     */
+    onTokenRefresh: OnTokenRefreshHandler;
     /**
      * - Seconds before expiration to consider token expired
      */
     bufferSeconds?: number;
 };
+/**
+ * This is a REQUIRED function. It gets called after the token is refreshed with new tokens.
+ * It should save the new tokens somewhere. When starting back up, re-use the newly perissted tokens.
+ * If you loose track of these new tokens, you will effectively be logged out.
+ */
+export type OnTokenRefreshHandler = (refreshSuccessEvent: RefreshSuccessEvent) => void | Promise<void>;
 export type RefreshSuccessEvent = {
     /**
      * - The OAuth client ID

package/lib/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["token.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH;IAgBE;;OAEG;IACH,oEAFW,oBAAoB,EAoB9B;IAED;;;;OAIG;IACH,kBAHa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAkGD;;;OAGG;IACH,WAFa,OAAO,CASnB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,WAHa,OAAO,CAAC,mBAAmB,CAAC,CAUxC;;CACF;;;;;cAhPa,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;oBACN,MAAM;;;;;;cAKN,MAAM;;;;wBACN,MAAM;;;;yBACN,MAAM;;;;sBACN,MAAM;;;;qBACN,MAAM;;;;sBACN,MAAM;;;;mBACN,MAAM;;;;;uCAKP;IACZ,eAAmB,EAAE,EAAE,CAAC;IACxB,iBAAqB,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC7C,eAAmB,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B,SAAa,EAAE,CAAC,KAAK,CAAC,CAAA;CACnB;6BA9ByB,aAAa"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["token.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AAEH;IAwBE;;OAEG;IACH,oFAFW,oBAAoB,EAuB9B;IAED;;;;OAIG;IACH,kBAHa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAyGD;;OAEG;IACH,wBAGC;IAED;;OAEG;IACH,yBAQC;IAED;;;OAGG;IACH,wBAFa,OAAO,CAInB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,mBAFa,MAAM,CAIlB;IAiED;;;OAGG;IACH,WAFa,OAAO,CASnB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,WAHa,OAAO,CAAC,mBAAmB,CAAC,CAUxC;;CACF;;;;;cAzXa,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;oBACN,qBAAqB;;;;oBACrB,MAAM;;;;;;;oCAQP,CAAC,mBAAmB,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;;;;;cAKjE,MAAM;;;;wBACN,MAAM;;;;yBACN,MAAM;;;;sBACN,MAAM;;;;qBACN,MAAM;;;;sBACN,MAAM;;;;mBACN,MAAM;;;;;uCAKP;IACZ,eAAmB,EAAE,EAAE,CAAC;IACxB,iBAAqB,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC7C,eAAmB,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B,SAAa,EAAE,CAAC,KAAK,CAAC,CAAA;CACnB;6BA1CyB,aAAa"}

package/lib/token.js

@@ -2,14 +2,26 @@ import { EventEmitter } from 'node:events'
 import { jwtDecode } from 'jwt-decode'
 import { exchangeToken } from './api-endpoints/auth.js'
 
+const AUTO_REFRESH_RETRY_BASE_SECONDS = 5
+const AUTO_REFRESH_RETRY_MAX_SECONDS = 300
+
 /**
  * @typedef {Object} RefreshableTokenOpts
  * @property {string} clientId - OAuth client ID
  * @property {string} refreshToken - OAuth refresh token
  * @property {string} accessToken - Initial OAuth access token (JWT)
+ * @property {OnTokenRefreshHandler} onTokenRefresh - A function that will receive the refreshed token info and perisist it for future use
  * @property {number} [bufferSeconds=30] - Seconds before expiration to consider token expired
  */
 
+/**
+ * This is a REQUIRED function. It gets called after the token is refreshed with new tokens.
+ * It should save the new tokens somewhere. When starting back up, re-use the newly perissted tokens.
+ * If you loose track of these new tokens, you will effectively be logged out.
+ *
+ * @typedef {(refreshSuccessEvent: RefreshSuccessEvent) => void | Promise<void>} OnTokenRefreshHandler
+ */
+
 /**
  * @typedef {Object} RefreshSuccessEvent
  * @property {string} clientId - The OAuth client ID
@@ -37,12 +49,13 @@ import { exchangeToken } from './api-endpoints/auth.js'
  *
  * Events:
  * - 'refresh:start' - Emitted when token refresh begins
- * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, accessToken, refreshToken, expiresAt }
+ * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken, prevExpiresAt }
  * - 'refresh:error' - Emitted when token refresh fails (transient errors), passes error
  * - 'invalid' - Emitted when refresh token is permanently invalid, passes error
  *
  * @extends {EventEmitter<RefreshableTokenEventMap>}
  */
+
 export class RefreshableToken extends EventEmitter {
   /** @type {string} */
   #clientId
@@ -58,16 +71,25 @@ export class RefreshableToken extends EventEmitter {
   #invalid = false
   /** @type {Promise<RefreshSuccessEvent> | null} */
   #inFlightRefresh = null
+  /** @type {boolean} */
+  #autoRefreshEnabled = true
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  #autoRefreshTimeout = null
+  /** @type {number} */
+  #autoRefreshRetryAttempt = 0
+  /** @type {OnTokenRefreshHandler} */
+  #onTokenRefresh
 
   /**
    * @param {RefreshableTokenOpts} opts
    */
-  constructor ({ clientId, refreshToken, accessToken, bufferSeconds = 30 }) {
+  constructor ({ clientId, refreshToken, accessToken, bufferSeconds = 30, onTokenRefresh }) {
     super()
     this.#clientId = clientId
     this.#refreshToken = refreshToken
     this.#accessToken = accessToken
     this.#bufferSeconds = bufferSeconds
+    this.#onTokenRefresh = onTokenRefresh
 
     // Decode the JWT to get expiration
     try {
@@ -80,6 +102,8 @@ export class RefreshableToken extends EventEmitter {
       const error = /** @type {Error} */ (err)
       throw new Error(`Failed to decode access token: ${error.message}`)
     }
+
+    this.#scheduleAutoRefresh()
   }
 
   /**
@@ -170,8 +194,13 @@ export class RefreshableToken extends EventEmitter {
         prevExpiresAt,
       }
 
+      await this.#onTokenRefresh(eventPayload)
+
       this.emit('refresh:success', eventPayload)
 
+      this.#autoRefreshRetryAttempt = 0
+      this.#scheduleAutoRefresh()
+
       return eventPayload
     } catch (err) {
       const error = /** @type {any} */ (err)
@@ -188,6 +217,7 @@ export class RefreshableToken extends EventEmitter {
       if (error.body?.error && invalidRefreshErrors.includes(error.body.error)) {
         // Mark this token as permanently invalid
         this.#invalid = true
+        this.#clearAutoRefreshTimeout()
         const statusCode = error.statusCode ? ` (${error.statusCode})` : ''
         const invalidError = new Error(`Refresh token is invalid or expired${statusCode}: ${error.body.error}${error.body.error_description ? ` - ${error.body.error_description}` : ''}`)
         this.emit('invalid', invalidError)
@@ -196,10 +226,120 @@ export class RefreshableToken extends EventEmitter {
 
       // For other errors, rethrow without marking as invalid (might be transient)
       this.emit('refresh:error', error)
+      this.#scheduleAutoRefreshRetry()
       throw error
     }
   }
 
+  /**
+   * Stop background token refresh scheduling.
+   */
+  stopAutoRefresh () {
+    this.#autoRefreshEnabled = false
+    this.#clearAutoRefreshTimeout()
+  }
+
+  /**
+   * Start background token refresh scheduling (enabled by default).
+   */
+  startAutoRefresh () {
+    if (this.#invalid) {
+      return
+    }
+
+    this.#autoRefreshEnabled = true
+    this.#autoRefreshRetryAttempt = 0
+    this.#scheduleAutoRefresh()
+  }
+
+  /**
+   * Check if background token refresh scheduling is enabled.
+   * @returns {boolean}
+   */
+  isAutoRefreshEnabled () {
+    return this.#autoRefreshEnabled
+  }
+
+  /**
+   * Get the current OAuth client ID (synchronous).
+   * @returns {string}
+   */
+  get clientId () {
+    return this.#clientId
+  }
+
+  /**
+   * Get the latest access token value (synchronous).
+   * Prefer getAccessToken() if you need a guaranteed-valid token in async contexts.
+   * @returns {string}
+   */
+  get accessToken () {
+    return this.#accessToken
+  }
+
+  /**
+   * Schedule the next refresh for when the token becomes stale (expiresAt - bufferSeconds).
+   * Uses an unref'd timer so it doesn't keep the process alive.
+   */
+  #scheduleAutoRefresh () {
+    if (!this.#autoRefreshEnabled || this.#invalid) {
+      return
+    }
+
+    const now = Math.floor(Date.now() / 1000)
+    const refreshAt = this.#expiresAt - this.#bufferSeconds
+    const delayMs = Math.max(0, (refreshAt - now) * 1000)
+
+    this.#clearAutoRefreshTimeout()
+    this.#autoRefreshTimeout = setTimeout(() => {
+      this.#autoRefreshTimeout = null
+      if (this.#invalid) {
+        return
+      }
+
+      this.#refreshAccessToken().catch(() => {
+        // Errors are emitted by #performRefresh; retries are scheduled there as well.
+      })
+    }, delayMs)
+
+    this.#autoRefreshTimeout.unref?.()
+  }
+
+  #clearAutoRefreshTimeout () {
+    if (!this.#autoRefreshTimeout) {
+      return
+    }
+
+    clearTimeout(this.#autoRefreshTimeout)
+    this.#autoRefreshTimeout = null
+  }
+
+  #scheduleAutoRefreshRetry () {
+    if (!this.#autoRefreshEnabled || this.#invalid) {
+      return
+    }
+
+    this.#autoRefreshRetryAttempt += 1
+    const retrySeconds = Math.min(
+      AUTO_REFRESH_RETRY_MAX_SECONDS,
+      AUTO_REFRESH_RETRY_BASE_SECONDS * (2 ** (this.#autoRefreshRetryAttempt - 1))
+    )
+
+    this.#clearAutoRefreshTimeout()
+    this.#autoRefreshTimeout = setTimeout(() => {
+      this.#autoRefreshTimeout = null
+      if (this.#invalid) {
+        return
+      }
+
+      this.#refreshAccessToken().catch(() => {
+        // Errors are emitted by #performRefresh; retries are scheduled there as well.
+      })
+    }, retrySeconds * 1000)
+
+    this.#autoRefreshTimeout.unref?.()
+  }
+
   /**
    * Check if the token is currently valid (not expired and not marked invalid).
    * @returns {boolean} True if token is valid