yoto-nodejs-client 0.0.1

package/lib/mqtt/topics.d.ts

@@ -0,0 +1,34 @@
+export function getEventsTopic(deviceId: string): string[];
+export function getStatusTopic(deviceId: string): string[];
+export function getResponseTopic(deviceId: string): string;
+export function getSubscriptionTopics(deviceId: string): string[];
+export function getCommandTopic(deviceId: string, resource: string, action?: string): string;
+export function parseTopic(topic: string): {
+    deviceId: string;
+    messageType: YotoMqttTopicType | "unknown";
+};
+export function getEventsRequestTopic(deviceId: string): string;
+export function getStatusRequestTopic(deviceId: string): string;
+export function getVolumeSetTopic(deviceId: string): string;
+export function getAmbientsSetTopic(deviceId: string): string;
+export function getSleepTimerSetTopic(deviceId: string): string;
+export function getRebootTopic(deviceId: string): string;
+export function getCardStartTopic(deviceId: string): string;
+export function getCardStopTopic(deviceId: string): string;
+export function getCardPauseTopic(deviceId: string): string;
+export function getCardResumeTopic(deviceId: string): string;
+export function getBluetoothOnTopic(deviceId: string): string;
+export function getBluetoothOffTopic(deviceId: string): string;
+export function getBluetoothDeleteBondsTopic(deviceId: string): string;
+export function getBluetoothConnectTopic(deviceId: string): string;
+export function getBluetoothDisconnectTopic(deviceId: string): string;
+export function getBluetoothStateTopic(deviceId: string): string;
+export function getDisplayPreviewTopic(deviceId: string): string;
+export const MQTT_BROKER_URL: "wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com";
+export const MQTT_AUTH_NAME: "PublicJWTAuthorizer";
+export const MQTT_PORT: 443;
+export const MQTT_PROTOCOL: "wss";
+export const MQTT_KEEPALIVE: 300;
+export const MQTT_ALPN_PROTOCOLS: string[];
+export type YotoMqttTopicType = "events" | "status" | "response";
+//# sourceMappingURL=topics.d.ts.map

package/lib/mqtt/topics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["topics.js"],"names":[],"mappings":"AAoDA,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAQD,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAOD,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAcD,gDAHW,MAAM,GACJ,MAAM,EAAE,CAQpB;AASD,0CALW,MAAM,YACN,MAAM,WACN,MAAM,GACJ,MAAM,CAKlB;AAOD,kCAHW,MAAM,GACJ;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAuB5E;AASD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,yCAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,6CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,+CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,uDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,mDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAnRD,8BAA+B,qDAAqD,CAAA;AAKpF,6BAA8B,qBAAqB,CAAA;AAKnD,wBAAyB,GAAG,CAAA;AAK5B,4BAA6B,KAAK,CAAA;AAKlC,6BAA8B,GAAG,CAAA;AAKjC,2CAAqD;gCA/BxC,QAAQ,GAAG,QAAQ,GAAG,UAAU"}

package/lib/mqtt/topics.js

@@ -0,0 +1,295 @@
+/**
+ * MQTT Topics for Yoto Players
+ *
+ * Topic builders and constants for Yoto MQTT communication
+ * @see https://yoto.dev/players-mqtt/
+ */
+
+// ============================================================================
+// MQTT Topics: Topic builders and constants
+// ============================================================================
+
+/**
+ * MQTT topic type for subscriptions
+ * @typedef {'events' | 'status' | 'response'} YotoMqttTopicType
+ */
+
+/**
+ * MQTT broker URL for Yoto devices
+ */
+export const MQTT_BROKER_URL = 'wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com'
+
+/**
+ * MQTT authorizer name for Yoto authentication
+ */
+export const MQTT_AUTH_NAME = 'PublicJWTAuthorizer'
+
+/**
+ * MQTT connection port
+ */
+export const MQTT_PORT = 443
+
+/**
+ * MQTT protocol
+ */
+export const MQTT_PROTOCOL = 'wss'
+
+/**
+ * MQTT keepalive interval in seconds
+ */
+export const MQTT_KEEPALIVE = 300
+
+/**
+ * ALPN protocols for AWS IoT
+ */
+export const MQTT_ALPN_PROTOCOLS = ['x-amzn-mqtt-ca']
+
+/**
+ * Get the events topics for a device (both old and new formats)
+ * Devices publish to both paths, so both are returned
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Events topics [old format, new format]
+ */
+export function getEventsTopic (deviceId) {
+  return [
+    `device/${deviceId}/events`,           // Old path (still published)
+    `device/${deviceId}/data/events`       // New path (also published)
+  ]
+}
+
+/**
+ * Get the status topics for a device (both old and new formats)
+ * Devices publish to both paths, so both are returned
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Status topics [old format, new format]
+ */
+export function getStatusTopic (deviceId) {
+  return [
+    `device/${deviceId}/status`,           // Old path (still published)
+    `device/${deviceId}/data/status`       // New path (also published)
+  ]
+}
+
+/**
+ * Get the response topic for a device (subscribe)
+ * @param {string} deviceId - Device ID
+ * @returns {string} Response topic
+ */
+export function getResponseTopic (deviceId) {
+  return `device/${deviceId}/response`
+}
+
+/**
+ * Get all subscription topics for a device
+ *
+ * Subscribes to both old and new topic formats because Yoto devices publish to both:
+ * - Old format: device/{id}/events, device/{id}/status
+ * - New format: device/{id}/data/events, device/{id}/data/status
+ *
+ * This ensures all messages are received regardless of which path the device uses.
+ *
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Array of topics to subscribe to (includes both old and new formats)
+ */
+export function getSubscriptionTopics (deviceId) {
+  return [
+    ...getEventsTopic(deviceId),           // Both events topics
+    ...getStatusTopic(deviceId),           // Both status topics
+    getResponseTopic(deviceId)             // Response topic (no old/new variants)
+  ]
+}
+
+/**
+ * Get a command topic for a device (publish)
+ * @param {string} deviceId - Device ID
+ * @param {string} resource - Command resource (e.g., 'volume', 'ambients', 'card')
+ * @param {string} [action] - Command action (e.g., 'set', 'start', 'stop')
+ * @returns {string} Command topic
+ */
+export function getCommandTopic (deviceId, resource, action) {
+  const base = `device/${deviceId}/command/${resource}`
+  return action ? `${base}/${action}` : base
+}
+
+/**
+ * Parse a topic string to extract device ID and message type
+ * @param {string} topic - Full MQTT topic string
+ * @returns {{ deviceId: string, messageType: YotoMqttTopicType | 'unknown' }} Parsed topic info
+ */
+export function parseTopic (topic) {
+  const parts = topic.split('/')
+
+  if (parts.length < 3 || parts[0] !== 'device') {
+    return { deviceId: '', messageType: 'unknown' }
+  }
+
+  const deviceId = parts[1] || ''
+
+  // Handle both old format (device/{id}/events) and new format (device/{id}/data/events)
+  let messageType = parts[2]
+  if (messageType === 'data' && parts.length >= 4) {
+    messageType = parts[3] // Get the actual message type after /data/
+  }
+
+  // Validate message type
+  if (messageType !== 'events' && messageType !== 'status' && messageType !== 'response') {
+    return { deviceId, messageType: 'unknown' }
+  }
+
+  return { deviceId, messageType: /** @type {YotoMqttTopicType} */ (messageType) }
+}
+
+// Command topic builders for specific commands
+
+/**
+ * Get the events request command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Events request topic
+ */
+export function getEventsRequestTopic (deviceId) {
+  return getCommandTopic(deviceId, 'events', 'request')
+}
+
+/**
+ * Get the status request command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Status request topic
+ */
+export function getStatusRequestTopic (deviceId) {
+  return getCommandTopic(deviceId, 'status', 'request')
+}
+
+/**
+ * Get the volume set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Volume set topic
+ */
+export function getVolumeSetTopic (deviceId) {
+  return getCommandTopic(deviceId, 'volume', 'set')
+}
+
+/**
+ * Get the ambients set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Ambients set topic
+ */
+export function getAmbientsSetTopic (deviceId) {
+  return getCommandTopic(deviceId, 'ambients', 'set')
+}
+
+/**
+ * Get the sleep timer set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Sleep timer set topic
+ */
+export function getSleepTimerSetTopic (deviceId) {
+  return getCommandTopic(deviceId, 'sleep-timer', 'set')
+}
+
+/**
+ * Get the reboot command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Reboot topic
+ */
+export function getRebootTopic (deviceId) {
+  return getCommandTopic(deviceId, 'reboot')
+}
+
+/**
+ * Get the card start command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card start topic
+ */
+export function getCardStartTopic (deviceId) {
+  return getCommandTopic(deviceId, 'card', 'start')
+}
+
+/**
+ * Get the card stop command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card stop topic
+ */
+export function getCardStopTopic (deviceId) {
+  return getCommandTopic(deviceId, 'card', 'stop')
+}
+
+/**
+ * Get the card pause command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card pause topic
+ */
+export function getCardPauseTopic (deviceId) {
+  return getCommandTopic(deviceId, 'card', 'pause')
+}
+
+/**
+ * Get the card resume command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card resume topic
+ */
+export function getCardResumeTopic (deviceId) {
+  return getCommandTopic(deviceId, 'card', 'resume')
+}
+
+/**
+ * Get the bluetooth on command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth on topic
+ */
+export function getBluetoothOnTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'on')
+}
+
+/**
+ * Get the bluetooth off command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth off topic
+ */
+export function getBluetoothOffTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'off')
+}
+
+/**
+ * Get the bluetooth delete bonds command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth delete bonds topic
+ */
+export function getBluetoothDeleteBondsTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'delete-bonds')
+}
+
+/**
+ * Get the bluetooth connect command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth connect topic
+ */
+export function getBluetoothConnectTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'connect')
+}
+
+/**
+ * Get the bluetooth disconnect command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth disconnect topic
+ */
+export function getBluetoothDisconnectTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'disconnect')
+}
+
+/**
+ * Get the bluetooth state command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth state topic
+ */
+export function getBluetoothStateTopic (deviceId) {
+  return getCommandTopic(deviceId, 'bluetooth', 'state')
+}
+
+/**
+ * Get the display preview command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Display preview topic
+ */
+export function getDisplayPreviewTopic (deviceId) {
+  return getCommandTopic(deviceId, 'display', 'preview')
+}

package/lib/pkg.cjs

@@ -0,0 +1,3 @@
+const pkg = require('../package.json')
+
+module.exports.pkg = pkg

package/lib/pkg.d.cts

@@ -0,0 +1,70 @@
+export const pkg: {
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    bugs: {
+        url: string;
+    };
+    dependencies: {
+        "jwt-decode": string;
+        mqtt: string;
+        undici: string;
+    };
+    devDependencies: {
+        "@types/node": string;
+        "@voxpelli/tsconfig": string;
+        argsclopts: string;
+        "auto-changelog": string;
+        c8: string;
+        "gh-release": string;
+        neostandard: string;
+        "npm-run-all2": string;
+        typescript: string;
+    };
+    engines: {
+        node: string;
+        npm: string;
+    };
+    homepage: string;
+    keywords: string[];
+    license: string;
+    type: string;
+    module: string;
+    main: string;
+    types: string;
+    files: string[];
+    bin: {
+        "yoto-auth": string;
+        "yoto-token-info": string;
+    };
+    repository: {
+        type: string;
+        url: string;
+    };
+    scripts: {
+        prepublishOnly: string;
+        postpublish: string;
+        test: string;
+        "test:lint": string;
+        "test:tsc": string;
+        "test:node-test": string;
+        version: string;
+        "version:changelog": string;
+        "version:git": string;
+        build: string;
+        "build:declaration": string;
+        clean: string;
+        "clean:declarations-top": string;
+        "clean:declarations-lib": string;
+        "clean:declarations-bin": string;
+    };
+    funding: {
+        type: string;
+        url: string;
+    };
+    c8: {
+        reporter: string[];
+    };
+};
+//# sourceMappingURL=pkg.d.cts.map

package/lib/pkg.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkg.d.cts","sourceRoot":"","sources":["pkg.cjs"],"names":[],"mappings":""}

package/lib/token.d.ts

@@ -0,0 +1,29 @@
+export class RefreshableToken extends EventEmitter<RefreshableTokenEventMap> {
+    constructor({ clientId, refreshToken, accessToken, bufferSeconds }: RefreshableTokenOpts);
+    getAccessToken(): Promise<string>;
+    isValid(): boolean;
+    getExpiresAt(): number;
+    getTimeRemaining(): number;
+    refresh(): Promise<RefreshSuccessEvent>;
+    #private;
+}
+export type RefreshableTokenOpts = {
+    clientId: string;
+    refreshToken: string;
+    accessToken: string;
+    bufferSeconds?: number;
+};
+export type RefreshSuccessEvent = {
+    clientId: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+};
+export type RefreshableTokenEventMap = {
+    "refresh:start": [];
+    "refresh:success": [RefreshSuccessEvent];
+    "refresh:error": [Error];
+    "invalid": [Error];
+};
+import { EventEmitter } from 'node:events';
+//# sourceMappingURL=token.d.ts.map

package/lib/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["token.js"],"names":[],"mappings":"AA0CA;IAmBE,oEAFW,oBAAoB,EAoB9B;IAOD,kBAHa,OAAO,CAAC,MAAM,CAAC,CAiB3B;IA4FD,WAFa,OAAO,CASnB;IAMD,gBAFa,MAAM,CAIlB;IAMD,oBAFa,MAAM,CAKlB;IAQD,WAHa,OAAO,CAAC,mBAAmB,CAAC,CAiBxC;;CACF;;cAzOa,MAAM;kBACN,MAAM;iBACN,MAAM;oBACN,MAAM;;;cAKN,MAAM;iBACN,MAAM;kBACN,MAAM;eACN,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;6BA3ByB,aAAa"}

package/lib/token.js

@@ -0,0 +1,240 @@
+import { EventEmitter } from 'node:events'
+import { jwtDecode } from 'jwt-decode'
+import { exchangeToken } from './api-endpoints/auth.js'
+
+/**
+ * @typedef {Object} RefreshableTokenOpts
+ * @property {string} clientId - OAuth client ID
+ * @property {string} refreshToken - OAuth refresh token
+ * @property {string} accessToken - Initial OAuth access token (JWT)
+ * @property {number} [bufferSeconds=30] - Seconds before expiration to consider token expired
+ */
+
+/**
+ * @typedef {Object} RefreshSuccessEvent
+ * @property {string} clientId - The OAuth client ID
+ * @property {string} accessToken - The new access token
+ * @property {string} refreshToken - The refresh token (may be updated)
+ * @property {number} expiresAt - Unix timestamp in seconds when token expires
+ */
+
+/**
+ * Event map for RefreshableToken
+ * @typedef {{
+ *   'refresh:start': [],
+ *   'refresh:success': [RefreshSuccessEvent],
+ *   'refresh:error': [Error],
+ *   'invalid': [Error]
+ * }} RefreshableTokenEventMap
+ */
+
+/**
+ * A refreshable OAuth token that automatically refreshes when expired.
+ * Handles in-flight refresh deduplication to prevent multiple concurrent refresh requests.
+ *
+ * Events:
+ * - 'refresh:start' - Emitted when token refresh begins
+ * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, accessToken, refreshToken, expiresAt }
+ * - '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
+  /** @type {string} */
+  #refreshToken
+  /** @type {string} */
+  #accessToken
+  /** @type {number} - Unix timestamp in seconds (from JWT exp claim) */
+  #expiresAt
+  /** @type {number} - Buffer time in seconds before expiration */
+  #bufferSeconds
+  /** @type {boolean} */
+  #invalid = false
+  /** @type {Promise<string> | null} */
+  #inFlightRefresh = null
+
+  /**
+   * @param {RefreshableTokenOpts} opts
+   */
+  constructor ({ clientId, refreshToken, accessToken, bufferSeconds = 30 }) {
+    super()
+    this.#clientId = clientId
+    this.#refreshToken = refreshToken
+    this.#accessToken = accessToken
+    this.#bufferSeconds = bufferSeconds
+
+    // Decode the JWT to get expiration
+    try {
+      const decoded = jwtDecode(accessToken)
+      if (!decoded.exp) {
+        throw new Error('Access token does not contain expiration claim (exp)')
+      }
+      this.#expiresAt = decoded.exp
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      throw new Error(`Failed to decode access token: ${error.message}`)
+    }
+  }
+
+  /**
+   * Get a valid access token, refreshing if necessary.
+   * @returns {Promise<string>} Valid access token
+   * @throws {Error} If token is invalid or refresh fails
+   */
+  async getAccessToken () {
+    // Check if token has been marked invalid
+    if (this.#invalid) {
+      throw new Error('Token is invalid. Refresh token has expired or been revoked.')
+    }
+
+    const now = Math.floor(Date.now() / 1000)
+    const needsRefresh = now >= (this.#expiresAt - this.#bufferSeconds)
+
+    if (!needsRefresh) {
+      return this.#accessToken
+    }
+
+    return await this.#refreshAccessToken()
+  }
+
+  /**
+   * Refresh the access token using the refresh token.
+   * Handles in-flight request deduplication.
+   * @returns {Promise<string>} New access token
+   */
+  async #refreshAccessToken () {
+    // If a refresh is already in flight, await the existing one
+    if (this.#inFlightRefresh) {
+      return await this.#inFlightRefresh
+    }
+
+    // Create the refresh promise and set it on the class variable
+    try {
+      this.#inFlightRefresh = this.#performRefresh()
+      const newAccessToken = await this.#inFlightRefresh
+      return newAccessToken
+    } finally {
+      // Clear the in-flight refresh once done
+      this.#inFlightRefresh = null
+    }
+  }
+
+  /**
+   * Perform the actual token refresh.
+   * @returns {Promise<string>} New access token
+   */
+  async #performRefresh () {
+    this.emit('refresh:start')
+
+    try {
+      const tokens = await exchangeToken({
+        grantType: 'refresh_token',
+        refreshToken: this.#refreshToken,
+        clientId: this.#clientId
+      })
+
+      // Update the access token and expiration
+      this.#accessToken = tokens.access_token
+
+      // If we got a new refresh token, update it
+      if (tokens.refresh_token) {
+        this.#refreshToken = tokens.refresh_token
+      }
+
+      // Decode the new token to get expiration
+      const decoded = jwtDecode(tokens.access_token)
+      if (!decoded.exp) {
+        throw new Error('Refreshed access token does not contain expiration claim (exp)')
+      }
+      this.#expiresAt = decoded.exp
+
+      this.emit('refresh:success', {
+        clientId: this.#clientId,
+        accessToken: this.#accessToken,
+        refreshToken: this.#refreshToken,
+        expiresAt: this.#expiresAt
+      })
+
+      return this.#accessToken
+    } catch (err) {
+      const error = /** @type {any} */ (err)
+
+      // Check for errors that indicate the refresh token is invalid
+      const invalidRefreshErrors = [
+        'invalid_grant',
+        'invalid_token',
+        'expired_token',
+        'token_expired',
+        'refresh_token_expired'
+      ]
+
+      if (error.body?.error && invalidRefreshErrors.includes(error.body.error)) {
+        // Mark this token as permanently invalid
+        this.#invalid = true
+        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)
+        throw invalidError
+      }
+
+      // For other errors, rethrow without marking as invalid (might be transient)
+      this.emit('refresh:error', error)
+      throw error
+    }
+  }
+
+  /**
+   * Check if the token is currently valid (not expired and not marked invalid).
+   * @returns {boolean} True if token is valid
+   */
+  isValid () {
+    if (this.#invalid) {
+      return false
+    }
+
+    const now = Math.floor(Date.now() / 1000)
+    return now < (this.#expiresAt - this.#bufferSeconds)
+  }
+
+  /**
+   * Get the expiration timestamp of the current access token.
+   * @returns {number} Unix timestamp (seconds since epoch)
+   */
+  getExpiresAt () {
+    return this.#expiresAt
+  }
+
+  /**
+   * Get the time remaining until token expiration.
+   * @returns {number} Seconds until expiration (may be negative if expired)
+   */
+  getTimeRemaining () {
+    const now = Math.floor(Date.now() / 1000)
+    return this.#expiresAt - now
+  }
+
+  /**
+   * Manually trigger a token refresh, regardless of expiration status.
+   * Useful for proactive refresh or testing.
+   * @returns {Promise<RefreshSuccessEvent>} Token information including clientId, accessToken, refreshToken, and expiresAt
+   * @throws {Error} If token is invalid or refresh fails
+   */
+  async refresh () {
+    // Check if token has been marked invalid
+    if (this.#invalid) {
+      throw new Error('Token is invalid. Refresh token has expired or been revoked.')
+    }
+
+    await this.#refreshAccessToken()
+
+    return {
+      clientId: this.#clientId,
+      accessToken: this.#accessToken,
+      refreshToken: this.#refreshToken,
+      expiresAt: this.#expiresAt
+    }
+  }
+}