yoto-nodejs-client 0.0.5 → 0.0.7

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/test-helpers/device-model-test-helpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @param {Promise<unknown>} promise
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @returns {Promise<unknown>}
+ */
+export function withTimeout(promise: Promise<unknown>, timeoutMs: number, label: string): Promise<unknown>;
+/**
+ * @param {YotoDeviceModel} model
+ * @returns {Promise<void>}
+ */
+export function waitForModelReady(model: YotoDeviceModel): Promise<void>;
+/**
+ * @param {YotoDeviceModelConfig} config
+ */
+export function assertConfigShape(config: YotoDeviceModelConfig): void;
+/**
+ * @param {YotoPlaybackState} playback
+ */
+export function assertPlaybackShape(playback: YotoPlaybackState): void;
+/**
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+export function toLower(value: string | undefined): string;
+import type { YotoDeviceModel } from '../yoto-device.js';
+import type { YotoDeviceModelConfig } from '../yoto-device.js';
+import type { YotoPlaybackState } from '../yoto-device.js';
+//# sourceMappingURL=device-model-test-helpers.d.ts.map

package/lib/test-helpers/device-model-test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-model-test-helpers.d.ts","sourceRoot":"","sources":["device-model-test-helpers.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,qCALW,OAAO,CAAC,OAAO,CAAC,aAChB,MAAM,SACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAS5B;AAED;;;GAGG;AACH,yCAHW,eAAe,GACb,OAAO,CAAC,IAAI,CAAC,CAUzB;AAED;;GAEG;AACH,0CAFW,qBAAqB,QAkD/B;AAED;;GAEG;AACH,8CAFW,iBAAiB,QAkB3B;AAED;;;GAGG;AACH,+BAHW,MAAM,GAAG,SAAS,GAChB,MAAM,CAIlB;qCAnH8E,mBAAmB;2CAAnB,mBAAmB;uCAAnB,mBAAmB"}

package/lib/test-helpers/device-model-test-helpers.js

@@ -0,0 +1,116 @@
+/** @import { YotoDeviceModel, YotoDeviceModelConfig, YotoPlaybackState } from '../yoto-device.js' */
+
+import assert from 'node:assert/strict'
+import { once } from 'node:events'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+/**
+ * @param {Promise<unknown>} promise
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @returns {Promise<unknown>}
+ */
+export function withTimeout (promise, timeoutMs, label) {
+  return Promise.race([
+    promise,
+    sleep(timeoutMs).then(() => {
+      throw new Error(`${label} timed out after ${timeoutMs}ms`)
+    })
+  ])
+}
+
+/**
+ * @param {YotoDeviceModel} model
+ * @returns {Promise<void>}
+ */
+export async function waitForModelReady (model) {
+  const started = withTimeout(once(model, 'started'), 15000, 'started')
+  const statusUpdated = withTimeout(once(model, 'statusUpdate'), 15000, 'statusUpdate')
+  const configUpdated = withTimeout(once(model, 'configUpdate'), 15000, 'configUpdate')
+
+  await model.start()
+  await Promise.all([started, statusUpdated, configUpdated])
+  await sleep(1500)
+}
+
+/**
+ * @param {YotoDeviceModelConfig} config
+ */
+export function assertConfigShape (config) {
+  assert.ok(Array.isArray(config.alarms), 'alarms should be an array')
+  assert.equal(typeof config.ambientColour, 'string', 'ambientColour should be string')
+  assert.equal(typeof config.bluetoothEnabled, 'boolean', 'bluetoothEnabled should be boolean')
+  assert.equal(typeof config.btHeadphonesEnabled, 'boolean', 'btHeadphonesEnabled should be boolean')
+  assert.equal(typeof config.clockFace, 'string', 'clockFace should be string')
+  assert.equal(typeof config.dayDisplayBrightnessAuto, 'boolean', 'dayDisplayBrightnessAuto should be boolean')
+  if (config.dayDisplayBrightnessAuto) {
+    assert.equal(config.dayDisplayBrightness, null, 'dayDisplayBrightness should be null when auto')
+  } else {
+    assert.equal(typeof config.dayDisplayBrightness, 'number', 'dayDisplayBrightness should be number when not auto')
+  }
+  assert.equal(typeof config.dayTime, 'string', 'dayTime should be string')
+  assert.equal(typeof config.dayYotoDaily, 'string', 'dayYotoDaily should be string')
+  assert.equal(typeof config.dayYotoRadio, 'string', 'dayYotoRadio should be string')
+  assert.equal(typeof config.daySoundsOff, 'boolean', 'daySoundsOff should be boolean')
+  assert.equal(typeof config.displayDimBrightness, 'number', 'displayDimBrightness should be number')
+  assert.equal(typeof config.displayDimTimeout, 'number', 'displayDimTimeout should be number')
+  assert.equal(typeof config.headphonesVolumeLimited, 'boolean', 'headphonesVolumeLimited should be boolean')
+  assert.ok(config.hourFormat === 12 || config.hourFormat === 24, 'hourFormat should be 12 or 24')
+  assert.equal(typeof config.locale, 'string', 'locale should be string')
+  assert.equal(typeof config.logLevel, 'string', 'logLevel should be string')
+  assert.equal(typeof config.maxVolumeLimit, 'number', 'maxVolumeLimit should be number')
+  assert.equal(typeof config.nightAmbientColour, 'string', 'nightAmbientColour should be string')
+  assert.equal(typeof config.nightDisplayBrightnessAuto, 'boolean', 'nightDisplayBrightnessAuto should be boolean')
+  if (config.nightDisplayBrightnessAuto) {
+    assert.equal(config.nightDisplayBrightness, null, 'nightDisplayBrightness should be null when auto')
+  } else {
+    assert.equal(typeof config.nightDisplayBrightness, 'number', 'nightDisplayBrightness should be number when not auto')
+  }
+  assert.equal(typeof config.nightMaxVolumeLimit, 'number', 'nightMaxVolumeLimit should be number')
+  assert.equal(typeof config.nightTime, 'string', 'nightTime should be string')
+  assert.equal(typeof config.nightYotoDaily, 'string', 'nightYotoDaily should be string')
+  assert.equal(typeof config.nightYotoRadioEnabled, 'boolean', 'nightYotoRadioEnabled should be boolean')
+  if (config.nightYotoRadioEnabled) {
+    assert.equal(typeof config.nightYotoRadio, 'string', 'nightYotoRadio should be string when enabled')
+  } else {
+    assert.equal(config.nightYotoRadio, null, 'nightYotoRadio should be null when disabled')
+  }
+  assert.equal(typeof config.nightSoundsOff, 'boolean', 'nightSoundsOff should be boolean')
+  assert.equal(typeof config.pausePowerButton, 'boolean', 'pausePowerButton should be boolean')
+  assert.equal(typeof config.pauseVolumeDown, 'boolean', 'pauseVolumeDown should be boolean')
+  assert.equal(typeof config.repeatAll, 'boolean', 'repeatAll should be boolean')
+  assert.equal(typeof config.showDiagnostics, 'boolean', 'showDiagnostics should be boolean')
+  assert.equal(typeof config.shutdownTimeout, 'number', 'shutdownTimeout should be number')
+  assert.equal(typeof config.systemVolume, 'number', 'systemVolume should be number')
+  assert.equal(typeof config.timezone, 'string', 'timezone should be string')
+  assert.equal(typeof config.volumeLevel, 'string', 'volumeLevel should be string')
+}
+
+/**
+ * @param {YotoPlaybackState} playback
+ */
+export function assertPlaybackShape (playback) {
+  assert.ok(playback, 'playback should exist')
+  assert.equal(typeof playback.updatedAt, 'string', 'playback.updatedAt should be string')
+
+  assert.ok(playback.cardId === null || typeof playback.cardId === 'string', 'playback.cardId should be string or null')
+  assert.ok(playback.source === null || typeof playback.source === 'string', 'playback.source should be string or null')
+  assert.ok(playback.playbackStatus === null || typeof playback.playbackStatus === 'string', 'playback.playbackStatus should be string or null')
+  assert.ok(playback.trackTitle === null || typeof playback.trackTitle === 'string', 'playback.trackTitle should be string or null')
+  assert.ok(playback.trackKey === null || typeof playback.trackKey === 'string', 'playback.trackKey should be string or null')
+  assert.ok(playback.chapterTitle === null || typeof playback.chapterTitle === 'string', 'playback.chapterTitle should be string or null')
+  assert.ok(playback.chapterKey === null || typeof playback.chapterKey === 'string', 'playback.chapterKey should be string or null')
+  assert.ok(playback.position === null || typeof playback.position === 'number', 'playback.position should be number or null')
+  assert.ok(playback.trackLength === null || typeof playback.trackLength === 'number', 'playback.trackLength should be number or null')
+  assert.ok(playback.streaming === null || typeof playback.streaming === 'boolean', 'playback.streaming should be boolean or null')
+  assert.ok(playback.sleepTimerActive === null || typeof playback.sleepTimerActive === 'boolean', 'playback.sleepTimerActive should be boolean or null')
+  assert.ok(playback.sleepTimerSeconds === null || typeof playback.sleepTimerSeconds === 'number', 'playback.sleepTimerSeconds should be number or null')
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+export function toLower (value) {
+  return typeof value === 'string' ? value.toLowerCase() : ''
+}

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