yoto-nodejs-client 0.0.1 → 0.0.3

package/lib/api-endpoints/auth.d.ts

@@ -1,18 +1,80 @@
+/**
+ * OAuth2 response type for authorization requests
+ * @typedef {'code' | 'token' | 'id_token' | 'code token' | 'code id_token' | 'token id_token' | 'code token id_token'} YotoOAuthResponseType
+ */
+/**
+ * OAuth2 prompt parameter for authorization requests
+ * @typedef {'none' | 'login' | 'consent' | 'select_account'} YotoOAuthPromptType
+ */
+/**
+ * PKCE code challenge method for authorization requests
+ * @typedef {'S256' | 'plain'} YotoOAuthCodeChallengeMethod
+ */
+/**
+ * OAuth2 grant type for token exchange requests
+ * @typedef {'authorization_code' | 'refresh_token' | 'client_credentials' | typeof DEVICE_CODE_GRANT_TYPE} YotoOAuthGrantType
+ */
+/**
+ * Redirects the user to Yoto's login page to begin the OAuth2 Authorization Code flow.
+ * @see https://yoto.dev/api/get-authorize/
+ * @param  {object} options
+ * @param  {string} [options.audience='https://api.yotoplay.com']    Audience for the token
+ * @param  {string} [options.scope='openid profile offline_access']       Requested scopes
+ * @param  {YotoOAuthResponseType} options.responseType  Required response type
+ * @param  {string} options.clientId    Required client ID
+ * @param  {string} options.redirectUri Required redirect URI
+ * @param  {string} options.state       Required opaque value for preventing CSRF attacks
+ * @param  {string} [options.nonce]     String value to prevent replay attacks
+ * @param  {YotoOAuthPromptType} [options.prompt]  Authorization server prompt behavior
+ * @param  {number} [options.maxAge]    Maximum authentication age in seconds
+ * @param  {string} [options.codeChallenge]  PKCE code challenge
+ * @param  {YotoOAuthCodeChallengeMethod} [options.codeChallengeMethod]  PKCE code challenge method
+ * @return {string} The authorization URL to redirect the user to
+ */
 export function getAuthorizeUrl({ audience, scope, responseType, clientId, redirectUri, state, nonce, prompt, maxAge, codeChallenge, codeChallengeMethod }: {
     audience?: string | undefined;
     scope?: string | undefined;
-    responseType: "code" | "token" | "id_token" | "code token" | "code id_token" | "token id_token" | "code token id_token";
+    responseType: YotoOAuthResponseType;
     clientId: string;
     redirectUri: string;
     state: string;
     nonce?: string | undefined;
-    prompt?: "none" | "login" | "consent" | "select_account" | undefined;
+    prompt?: YotoOAuthPromptType | undefined;
     maxAge?: number | undefined;
     codeChallenge?: string | undefined;
-    codeChallengeMethod?: "S256" | "plain" | undefined;
+    codeChallengeMethod?: YotoOAuthCodeChallengeMethod | undefined;
 }): string;
+/**
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @typedef {Object} YotoTokenResponse
+ * @property {string} access_token
+ * @property {string} token_type
+ * @property {number} expires_in
+ * @property {string} [refresh_token]
+ * @property {string} [scope]
+ * @property {string} [id_token]
+ * @property {number} [expires_at]
+ */
+/**
+ * Exchange authorization code or refresh token for access tokens.
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @param  {object} options
+ * @param  {YotoOAuthGrantType} options.grantType  Required grant type
+ * @param  {string} [options.code]  Authorization code (required for authorization_code grant)
+ * @param  {string} [options.redirectUri]  Redirect URI (required for authorization_code grant if used in authorize request)
+ * @param  {string} [options.refreshToken]  Refresh token (required for refresh_token grant)
+ * @param  {string} [options.clientId]  Client ID
+ * @param  {string} [options.clientSecret]  Client secret
+ * @param  {string} [options.scope]  Requested scope
+ * @param  {string} [options.codeVerifier]  PKCE code verifier (if code_challenge was used)
+ * @param  {string} [options.deviceCode]  Device code (required for device_code grant)
+ * @param  {string} [options.audience='https://api.yotoplay.com']  Audience for the token
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoTokenResponse>} Token response
+ */
 export function exchangeToken({ grantType, code, redirectUri, refreshToken, clientId, clientSecret, scope, codeVerifier, deviceCode, audience, userAgent, requestOptions }: {
-    grantType: "authorization_code" | "refresh_token" | "client_credentials" | "urn:ietf:params:oauth:grant-type:device_code";
+    grantType: YotoOAuthGrantType;
     code?: string | undefined;
     redirectUri?: string | undefined;
     refreshToken?: string | undefined;
@@ -27,6 +89,27 @@ export function exchangeToken({ grantType, code, redirectUri, refreshToken, clie
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoTokenResponse>;
+/**
+ * @see https://yoto.dev/api/post-oauth-device-code/
+ * @typedef {Object} YotoDeviceCodeResponse
+ * @property {string} device_code - The device verification code
+ * @property {string} user_code - The code displayed to the user
+ * @property {string} verification_uri - The URL where the user should enter the user_code
+ * @property {string} [verification_uri_complete] - The verification URL with the code included
+ * @property {number} expires_in - The lifetime of the device code in seconds
+ * @property {number} interval - Minimum polling interval in seconds
+ */
+/**
+ * Start the OAuth2 Device Authorization flow for CLI/server-side applications.
+ * @see https://yoto.dev/api/post-oauth-device-code/
+ * @param  {object} options
+ * @param  {string} options.clientId  Required client ID
+ * @param  {string} [options.scope='openid profile offline_access']     Requested scopes
+ * @param  {string} [options.audience='https://api.yotoplay.com']  Audience for the token
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoDeviceCodeResponse>} Device code response with user_code and verification_uri
+ */
 export function requestDeviceCode({ clientId, scope, audience, userAgent, requestOptions }: {
     clientId: string;
     scope?: string | undefined;
@@ -36,6 +119,137 @@ export function requestDeviceCode({ clientId, scope, audience, userAgent, reques
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoDeviceCodeResponse>;
+/**
+ * Poll result when authorization is still pending
+ * @typedef {Object} YotoDevicePollPending
+ * @property {'pending'} status - Indicates polling should continue
+ * @property {number} interval - Current polling interval in milliseconds
+ */
+/**
+ * Poll result when polling needs to slow down
+ * @typedef {Object} YotoDevicePollSlowDown
+ * @property {'slow_down'} status - Indicates polling interval should be increased
+ * @property {number} interval - New polling interval in milliseconds
+ */
+/**
+ * Poll result when authorization is successful
+ * @typedef {Object} YotoDevicePollSuccess
+ * @property {'success'} status - Indicates successful authorization
+ * @property {YotoTokenResponse} tokens - OAuth tokens
+ */
+/**
+ * Poll result for device authorization flow
+ * @typedef {YotoDevicePollPending | YotoDevicePollSlowDown | YotoDevicePollSuccess} YotoDevicePollResult
+ */
+/**
+ * Poll for device authorization completion with automatic error handling (single poll attempt).
+ * This function handles common polling errors (authorization_pending, slow_down)
+ * and only throws for unrecoverable errors (expired_token, access_denied, etc).
+ *
+ * Non-blocking - returns immediately with poll result. Suitable for:
+ * - Manual polling loops in CLI applications
+ * - Server-side endpoints that poll on behalf of clients (e.g., Homebridge UI server)
+ * - Custom UI implementations with specific polling behavior
+ *
+ * For the simplest approach (automatic polling loop), use waitForDeviceAuthorization() instead.
+ *
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @param {object} options
+ * @param {string} options.deviceCode - Device code from requestDeviceCode()
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} [options.audience='https://api.yotoplay.com'] - Audience for the token
+ * @param {number} [options.currentInterval=5000] - Current polling interval in milliseconds
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @returns {Promise<YotoDevicePollResult>} Poll result with status and data
+ * @throws {YotoAPIError} For unrecoverable errors (expired_token, access_denied, invalid_grant, etc)
+ *
+ */
+export function pollForDeviceToken({ deviceCode, clientId, audience, currentInterval, userAgent, requestOptions }: {
+    deviceCode: string;
+    clientId: string;
+    audience?: string | undefined;
+    currentInterval?: number | undefined;
+    userAgent?: string | undefined;
+    requestOptions?: ({
+        dispatcher?: import("undici").Dispatcher;
+    } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
+}): Promise<YotoDevicePollResult>;
+/**
+ * Wait for device authorization to complete with automatic polling.
+ * This function wraps the entire polling loop - just call it and await the result.
+ * It handles all polling logic internally including interval adjustments.
+ *
+ * Designed for CLI usage where you want to block until authorization completes.
+ * For UI implementations with progress feedback, use pollForDeviceToken() directly.
+ *
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @param {object} options
+ * @param {string} options.deviceCode - Device code from requestDeviceCode()
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} [options.audience='https://api.yotoplay.com'] - Audience for the token
+ * @param {number} [options.initialInterval=5000] - Initial polling interval in milliseconds
+ * @param {number} [options.expiresIn] - Seconds until device code expires (for timeout calculation)
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @param {(result: YotoDevicePollResult) => void} [options.onPoll] - Optional callback invoked after each poll attempt
+ * @returns {Promise<YotoTokenResponse>} Token response on successful authorization
+ * @throws {YotoAPIError} For unrecoverable errors (expired_token, access_denied, invalid_grant, etc)
+ * @throws {Error} If device code expires (timeout)
+ *
+ * @example
+ * // Simple usage - just wait for tokens
+ * const deviceAuth = await requestDeviceCode({ clientId })
+ * console.log(`Visit: ${deviceAuth.verification_uri_complete}`)
+ *
+ * const tokens = await waitForDeviceAuthorization({
+ *   deviceCode: deviceAuth.device_code,
+ *   clientId,
+ *   initialInterval: deviceAuth.interval * 1000,
+ *   expiresIn: deviceAuth.expires_in
+ * })
+ *
+ * console.log('Got tokens:', tokens)
+ *
+ * @example
+ * // With progress callback
+ * const tokens = await waitForDeviceAuthorization({
+ *   deviceCode: deviceAuth.device_code,
+ *   clientId,
+ *   onPoll: (result) => {
+ *     if (result.status === 'pending') process.stdout.write('.')
+ *     if (result.status === 'slow_down') console.log('\nSlowing down...')
+ *   }
+ * })
+ */
+export function waitForDeviceAuthorization({ deviceCode, clientId, audience, initialInterval, expiresIn, userAgent, requestOptions, onPoll }: {
+    deviceCode: string;
+    clientId: string;
+    audience?: string | undefined;
+    initialInterval?: number | undefined;
+    expiresIn?: number | undefined;
+    userAgent?: string | undefined;
+    requestOptions?: ({
+        dispatcher?: import("undici").Dispatcher;
+    } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
+    onPoll?: ((result: YotoDevicePollResult) => void) | undefined;
+}): Promise<YotoTokenResponse>;
+/**
+ * OAuth2 response type for authorization requests
+ */
+export type YotoOAuthResponseType = "code" | "token" | "id_token" | "code token" | "code id_token" | "token id_token" | "code token id_token";
+/**
+ * OAuth2 prompt parameter for authorization requests
+ */
+export type YotoOAuthPromptType = "none" | "login" | "consent" | "select_account";
+/**
+ * PKCE code challenge method for authorization requests
+ */
+export type YotoOAuthCodeChallengeMethod = "S256" | "plain";
+/**
+ * OAuth2 grant type for token exchange requests
+ */
+export type YotoOAuthGrantType = "authorization_code" | "refresh_token" | "client_credentials" | typeof DEVICE_CODE_GRANT_TYPE;
 export type YotoTokenResponse = {
     access_token: string;
     token_type: string;
@@ -46,11 +260,73 @@ export type YotoTokenResponse = {
     expires_at?: number;
 };
 export type YotoDeviceCodeResponse = {
+    /**
+     * - The device verification code
+     */
     device_code: string;
+    /**
+     * - The code displayed to the user
+     */
     user_code: string;
+    /**
+     * - The URL where the user should enter the user_code
+     */
     verification_uri: string;
+    /**
+     * - The verification URL with the code included
+     */
     verification_uri_complete?: string;
+    /**
+     * - The lifetime of the device code in seconds
+     */
     expires_in: number;
+    /**
+     * - Minimum polling interval in seconds
+     */
     interval: number;
 };
+/**
+ * Poll result when authorization is still pending
+ */
+export type YotoDevicePollPending = {
+    /**
+     * - Indicates polling should continue
+     */
+    status: "pending";
+    /**
+     * - Current polling interval in milliseconds
+     */
+    interval: number;
+};
+/**
+ * Poll result when polling needs to slow down
+ */
+export type YotoDevicePollSlowDown = {
+    /**
+     * - Indicates polling interval should be increased
+     */
+    status: "slow_down";
+    /**
+     * - New polling interval in milliseconds
+     */
+    interval: number;
+};
+/**
+ * Poll result when authorization is successful
+ */
+export type YotoDevicePollSuccess = {
+    /**
+     * - Indicates successful authorization
+     */
+    status: "success";
+    /**
+     * - OAuth tokens
+     */
+    tokens: YotoTokenResponse;
+};
+/**
+ * Poll result for device authorization flow
+ */
+export type YotoDevicePollResult = YotoDevicePollPending | YotoDevicePollSlowDown | YotoDevicePollSuccess;
+import { DEVICE_CODE_GRANT_TYPE } from './constants.js';
 //# sourceMappingURL=auth.d.ts.map

package/lib/api-endpoints/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["auth.js"],"names":[],"mappings":"AA4BA,4JAbG;IAA0B,QAAQ;IACR,KAAK;IAC6F,YAAY,EAA/H,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,gBAAgB,GAAG,qBAAqB;IACzF,QAAQ,EAAxB,MAAM;IACU,WAAW,EAA3B,MAAM;IACU,KAAK,EAArB,MAAM;IACW,KAAK;IACoC,MAAM;IAC/C,MAAM;IACN,aAAa;IACH,mBAAmB;CACvD,GAAS,MAAM,CA+BjB;AAgCD,4KAdG;IAAiI,SAAS,EAAjI,oBAAoB,GAAG,eAAe,GAAG,oBAAoB,GAAG,8CAA8C;IAC7F,IAAI;IACJ,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,YAAY;IACZ,KAAK;IACL,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,iBAAiB,CAAC,CAoErC;AAwBD,4FAPG;IAAyB,QAAQ,EAAxB,MAAM;IACW,KAAK;IACL,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,sBAAsB,CAAC,CA+B1C;;kBAlJa,MAAM;gBACN,MAAM;gBACN,MAAM;oBACN,MAAM;YACN,MAAM;eACN,MAAM;iBACN,MAAM;;;iBA4FN,MAAM;eACN,MAAM;sBACN,MAAM;gCACN,MAAM;gBACN,MAAM;cACN,MAAM"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["auth.js"],"names":[],"mappings":"AAWA;;;GAGG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,4JAbG;IAA0B,QAAQ;IACR,KAAK;IACS,YAAY,EAA3C,qBAAqB;IACL,QAAQ,EAAxB,MAAM;IACU,WAAW,EAA3B,MAAM;IACU,KAAK,EAArB,MAAM;IACW,KAAK;IACQ,MAAM;IACnB,MAAM;IACN,aAAa;IACS,mBAAmB;CACnE,GAAS,MAAM,CA+BjB;AAED;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4KAdG;IAAqC,SAAS,EAArC,kBAAkB;IACD,IAAI;IACJ,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,YAAY;IACZ,KAAK;IACL,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,iBAAiB,CAAC,CAoErC;AAED;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,4FAPG;IAAyB,QAAQ,EAAxB,MAAM;IACW,KAAK;IACL,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,sBAAsB,CAAC,CA+B1C;AAED;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,mHAVG;IAAwB,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACW,QAAQ;IACR,eAAe;IACf,SAAS;IACD,cAAc;;;CAC/C,GAAU,OAAO,CAAC,oBAAoB,CAAC,CAuDzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,8IArCG;IAAwB,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACW,QAAQ;IACR,eAAe;IACf,SAAS;IACT,SAAS;IACD,cAAc;;;IACU,MAAM,aAA9C,oBAAoB,KAAK,IAAI;CAC9C,GAAU,OAAO,CAAC,iBAAiB,CAAC,CA0EtC;;;;oCA5ZY,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,gBAAgB,GAAG,qBAAqB;;;;kCAKzG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB;;;;2CAK/C,MAAM,GAAG,OAAO;;;;iCAKhB,oBAAoB,GAAG,eAAe,GAAG,oBAAoB,GAAG,OAAO,sBAAsB;;kBAsD5F,MAAM;gBACN,MAAM;gBACN,MAAM;oBACN,MAAM;YACN,MAAM;eACN,MAAM;iBACN,MAAM;;;;;;iBA4FN,MAAM;;;;eACN,MAAM;;;;sBACN,MAAM;;;;gCACN,MAAM;;;;gBACN,MAAM;;;;cACN,MAAM;;;;;;;;;YAgDN,SAAS;;;;cACT,MAAM;;;;;;;;;YAMN,WAAW;;;;cACX,MAAM;;;;;;;;;YAMN,SAAS;;;;YACT,iBAAiB;;;;;mCAKlB,qBAAqB,GAAG,sBAAsB,GAAG,qBAAqB;uCAxPK,gBAAgB"}

package/lib/api-endpoints/auth.js

@@ -3,27 +3,47 @@
  */
 import { request } from 'undici'
 import { defaultHeaders, handleBadResponse, mergeRequestOptions, YotoAPIError } from './helpers.js'
-import { DEFAULT_SCOPE, DEFAULT_AUDIENCE, YOTO_LOGIN_URL } from './constants.js'
+import { DEFAULT_SCOPE, DEFAULT_AUDIENCE, YOTO_LOGIN_URL, DEVICE_CODE_GRANT_TYPE } from './constants.js'
 
 // ============================================================================
 // Authentication: Authentication endpoints for browser-based and device flows
 // ============================================================================
 
+/**
+ * OAuth2 response type for authorization requests
+ * @typedef {'code' | 'token' | 'id_token' | 'code token' | 'code id_token' | 'token id_token' | 'code token id_token'} YotoOAuthResponseType
+ */
+
+/**
+ * OAuth2 prompt parameter for authorization requests
+ * @typedef {'none' | 'login' | 'consent' | 'select_account'} YotoOAuthPromptType
+ */
+
+/**
+ * PKCE code challenge method for authorization requests
+ * @typedef {'S256' | 'plain'} YotoOAuthCodeChallengeMethod
+ */
+
+/**
+ * OAuth2 grant type for token exchange requests
+ * @typedef {'authorization_code' | 'refresh_token' | 'client_credentials' | typeof DEVICE_CODE_GRANT_TYPE} YotoOAuthGrantType
+ */
+
 /**
  * Redirects the user to Yoto's login page to begin the OAuth2 Authorization Code flow.
  * @see https://yoto.dev/api/get-authorize/
  * @param  {object} options
  * @param  {string} [options.audience='https://api.yotoplay.com']    Audience for the token
  * @param  {string} [options.scope='openid profile offline_access']       Requested scopes
- * @param  {'code' | 'token' | 'id_token' | 'code token' | 'code id_token' | 'token id_token' | 'code token id_token'} options.responseType  Required response type
+ * @param  {YotoOAuthResponseType} options.responseType  Required response type
  * @param  {string} options.clientId    Required client ID
  * @param  {string} options.redirectUri Required redirect URI
  * @param  {string} options.state       Required opaque value for preventing CSRF attacks
  * @param  {string} [options.nonce]     String value to prevent replay attacks
- * @param  {'none' | 'login' | 'consent' | 'select_account'} [options.prompt]  Authorization server prompt behavior
+ * @param  {YotoOAuthPromptType} [options.prompt]  Authorization server prompt behavior
  * @param  {number} [options.maxAge]    Maximum authentication age in seconds
  * @param  {string} [options.codeChallenge]  PKCE code challenge
- * @param  {'S256' | 'plain'} [options.codeChallengeMethod]  PKCE code challenge method
+ * @param  {YotoOAuthCodeChallengeMethod} [options.codeChallengeMethod]  PKCE code challenge method
  * @return {string} The authorization URL to redirect the user to
  */
 export function getAuthorizeUrl ({
@@ -73,7 +93,7 @@ export function getAuthorizeUrl ({
  * Exchange authorization code or refresh token for access tokens.
  * @see https://yoto.dev/api/post-oauth-token/
  * @param  {object} options
- * @param  {'authorization_code' | 'refresh_token' | 'client_credentials' | 'urn:ietf:params:oauth:grant-type:device_code'} options.grantType  Required grant type
+ * @param  {YotoOAuthGrantType} options.grantType  Required grant type
  * @param  {string} [options.code]  Authorization code (required for authorization_code grant)
  * @param  {string} [options.redirectUri]  Redirect URI (required for authorization_code grant if used in authorize request)
  * @param  {string} [options.refreshToken]  Refresh token (required for refresh_token grant)
@@ -114,7 +134,7 @@ export async function exchangeToken ({
   } else if (grantType === 'refresh_token') {
     if (!refreshToken) throw new Error('refreshToken is required for refresh_token grant')
     formData.set('refresh_token', refreshToken)
-  } else if (grantType === 'urn:ietf:params:oauth:grant-type:device_code') {
+  } else if (grantType === DEVICE_CODE_GRANT_TYPE) {
     if (!deviceCode) throw new Error('deviceCode is required for device_code grant')
     formData.set('device_code', deviceCode)
   }
@@ -137,7 +157,7 @@ export async function exchangeToken ({
 
   // For device_code grant, always parse JSON first so error details are available
   // 403 errors with authorization_pending/slow_down are expected during polling
-  if (grantType === 'urn:ietf:params:oauth:grant-type:device_code') {
+  if (grantType === DEVICE_CODE_GRANT_TYPE) {
     /** @type {any} */
     const rawResponse = await response.body.json()
 
@@ -207,3 +227,200 @@ export async function requestDeviceCode ({
   const responseBody = /** @type {YotoDeviceCodeResponse} */ (await response.body.json())
   return responseBody
 }
+
+/**
+ * Poll result when authorization is still pending
+ * @typedef {Object} YotoDevicePollPending
+ * @property {'pending'} status - Indicates polling should continue
+ * @property {number} interval - Current polling interval in milliseconds
+ */
+
+/**
+ * Poll result when polling needs to slow down
+ * @typedef {Object} YotoDevicePollSlowDown
+ * @property {'slow_down'} status - Indicates polling interval should be increased
+ * @property {number} interval - New polling interval in milliseconds
+ */
+
+/**
+ * Poll result when authorization is successful
+ * @typedef {Object} YotoDevicePollSuccess
+ * @property {'success'} status - Indicates successful authorization
+ * @property {YotoTokenResponse} tokens - OAuth tokens
+ */
+
+/**
+ * Poll result for device authorization flow
+ * @typedef {YotoDevicePollPending | YotoDevicePollSlowDown | YotoDevicePollSuccess} YotoDevicePollResult
+ */
+
+/**
+ * Poll for device authorization completion with automatic error handling (single poll attempt).
+ * This function handles common polling errors (authorization_pending, slow_down)
+ * and only throws for unrecoverable errors (expired_token, access_denied, etc).
+ *
+ * Non-blocking - returns immediately with poll result. Suitable for:
+ * - Manual polling loops in CLI applications
+ * - Server-side endpoints that poll on behalf of clients (e.g., Homebridge UI server)
+ * - Custom UI implementations with specific polling behavior
+ *
+ * For the simplest approach (automatic polling loop), use waitForDeviceAuthorization() instead.
+ *
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @param {object} options
+ * @param {string} options.deviceCode - Device code from requestDeviceCode()
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} [options.audience='https://api.yotoplay.com'] - Audience for the token
+ * @param {number} [options.currentInterval=5000] - Current polling interval in milliseconds
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @returns {Promise<YotoDevicePollResult>} Poll result with status and data
+ * @throws {YotoAPIError} For unrecoverable errors (expired_token, access_denied, invalid_grant, etc)
+ *
+ */
+export async function pollForDeviceToken ({
+  deviceCode,
+  clientId,
+  audience = DEFAULT_AUDIENCE,
+  currentInterval = 5000,
+  userAgent,
+  requestOptions
+}) {
+  try {
+    const tokens = await exchangeToken({
+      grantType: DEVICE_CODE_GRANT_TYPE,
+      deviceCode,
+      clientId,
+      audience,
+      userAgent,
+      requestOptions
+    })
+
+    // Success - return tokens
+    return {
+      status: 'success',
+      tokens
+    }
+  } catch (err) {
+    const error = /** @type {any} */ (err)
+    const errorCode = error.body?.error
+
+    // Handle recoverable polling states
+    if (errorCode === 'authorization_pending') {
+      // User hasn't authorized yet - continue polling
+      return {
+        status: 'pending',
+        interval: currentInterval
+      }
+    }
+
+    if (errorCode === 'slow_down') {
+      // Polling too fast - increase interval by 5 seconds
+      return {
+        status: 'slow_down',
+        interval: currentInterval + 5000
+      }
+    }
+
+    // All other errors are unrecoverable - throw them
+    // Common unrecoverable errors:
+    // - expired_token: Device code expired
+    // - access_denied: User denied authorization
+    // - invalid_grant: Invalid device code or other grant issue
+    throw error
+  }
+}
+
+/**
+ * Wait for device authorization to complete with automatic polling.
+ * This function wraps the entire polling loop - just call it and await the result.
+ * It handles all polling logic internally including interval adjustments.
+ *
+ * Designed for CLI usage where you want to block until authorization completes.
+ * For UI implementations with progress feedback, use pollForDeviceToken() directly.
+ *
+ * @see https://yoto.dev/api/post-oauth-token/
+ * @param {object} options
+ * @param {string} options.deviceCode - Device code from requestDeviceCode()
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} [options.audience='https://api.yotoplay.com'] - Audience for the token
+ * @param {number} [options.initialInterval=5000] - Initial polling interval in milliseconds
+ * @param {number} [options.expiresIn] - Seconds until device code expires (for timeout calculation)
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @param {(result: YotoDevicePollResult) => void} [options.onPoll] - Optional callback invoked after each poll attempt
+ * @returns {Promise<YotoTokenResponse>} Token response on successful authorization
+ * @throws {YotoAPIError} For unrecoverable errors (expired_token, access_denied, invalid_grant, etc)
+ * @throws {Error} If device code expires (timeout)
+ *
+ * @example
+ * // Simple usage - just wait for tokens
+ * const deviceAuth = await requestDeviceCode({ clientId })
+ * console.log(`Visit: ${deviceAuth.verification_uri_complete}`)
+ *
+ * const tokens = await waitForDeviceAuthorization({
+ *   deviceCode: deviceAuth.device_code,
+ *   clientId,
+ *   initialInterval: deviceAuth.interval * 1000,
+ *   expiresIn: deviceAuth.expires_in
+ * })
+ *
+ * console.log('Got tokens:', tokens)
+ *
+ * @example
+ * // With progress callback
+ * const tokens = await waitForDeviceAuthorization({
+ *   deviceCode: deviceAuth.device_code,
+ *   clientId,
+ *   onPoll: (result) => {
+ *     if (result.status === 'pending') process.stdout.write('.')
+ *     if (result.status === 'slow_down') console.log('\nSlowing down...')
+ *   }
+ * })
+ */
+export async function waitForDeviceAuthorization ({
+  deviceCode,
+  clientId,
+  audience = DEFAULT_AUDIENCE,
+  initialInterval = 5000,
+  expiresIn,
+  userAgent,
+  requestOptions,
+  onPoll
+}) {
+  let interval = initialInterval
+  const startTime = Date.now()
+  const expiresAt = expiresIn ? startTime + (expiresIn * 1000) : null
+
+  while (true) {
+    // Check if we've exceeded the expiration time
+    if (expiresAt && Date.now() >= expiresAt) {
+      throw new Error('Device code has expired')
+    }
+
+    const result = await pollForDeviceToken({
+      deviceCode,
+      clientId,
+      audience,
+      currentInterval: interval,
+      userAgent,
+      requestOptions
+    })
+
+    // Invoke callback if provided
+    if (onPoll) {
+      onPoll(result)
+    }
+
+    if (result.status === 'success') {
+      return result.tokens
+    }
+
+    if (result.status === 'slow_down') {
+      interval = result.interval
+    }
+
+    // Wait before next poll
+    await new Promise(resolve => setTimeout(resolve, interval))
+  }
+}

package/lib/api-endpoints/auth.test.js

@@ -1,8 +1,8 @@
 import test from 'node:test'
 import assert from 'node:assert'
-import { exchangeToken } from './auth.js'
+import { exchangeToken, pollForDeviceToken } from './auth.js'
 import { YotoAPIError } from './helpers.js'
-import { loadTestTokens } from './test-helpers.js'
+import { loadTestTokens } from './endpoint-test-helpers.js'
 
 const { clientId } = loadTestTokens()
 
@@ -25,3 +25,55 @@ test('exchangeToken - refresh flow', async (t) => {
     )
   })
 })
+
+test('pollForDeviceToken', async (t) => {
+  await t.test('should throw invalid_grant for invalid device code', async () => {
+    // Invalid device codes throw invalid_grant error (unrecoverable)
+    await assert.rejects(
+      async () => {
+        await pollForDeviceToken({
+          deviceCode: 'invalid-device-code',
+          clientId,
+          currentInterval: 5000
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        // @ts-expect-error
+        assert.strictEqual(err.body?.error, 'invalid_grant', 'Should be invalid_grant error')
+        assert.ok(err.statusCode, 'Error should have statusCode')
+        return true
+      }
+    )
+  })
+
+  await t.test('should throw for expired_token error', async () => {
+    // The function should throw for expired_token (unrecoverable)
+    // We can't easily test this without a real flow, but we verify the error handling works
+    await assert.rejects(
+      async () => {
+        await pollForDeviceToken({
+          deviceCode: 'expired-device-code-xyz',
+          clientId,
+          currentInterval: 5000
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        // Will get invalid_grant for malformed codes
+        // @ts-expect-error
+        assert.ok(err.body?.error, 'Should have error code')
+        return true
+      }
+    )
+  })
+
+  // Note: Testing authorization_pending and slow_down states requires a real device flow
+  // These tests would need to:
+  // 1. Call requestDeviceCode() to get a valid device_code
+  // 2. Poll immediately (should get authorization_pending)
+  // 3. Poll rapidly (might get slow_down)
+  // 4. Complete auth in browser (would get success)
+  // This is too complex and flaky for unit tests, so we skip testing those paths
+  // The implementation is verified by the CLI tool usage in bin/auth.js
+})