yoto-nodejs-client 0.0.1 → 0.0.2

package/bin/lib/cli-helpers.d.ts

@@ -1,5 +1,20 @@
+/**
+ * Get common CLI option definitions shared across all tools
+ * @returns {ArgscloptsParseArgsOptionsConfig}
+ */
 export function getCommonOptions(): ArgscloptsParseArgsOptionsConfig;
+/**
+ * Load .env file from specified path or default to .env in cwd
+ * @param {string} [envFile] - Optional path to .env file
+ * @returns {string} The path that was loaded (or attempted)
+ */
 export function loadEnvFile(envFile?: string): string;
+/**
+ * Load and validate tokens from environment
+ * @param {{ values: Record<string, string | boolean | undefined> }} args - Parsed arguments from parseArgs
+ * @returns {{ clientId: string, refreshToken: string, accessToken: string, envFile: string }}
+ * @throws Exits process if tokens are missing
+ */
 export function loadTokensFromEnv(args: {
     values: Record<string, string | boolean | undefined>;
 }): {
@@ -8,13 +23,30 @@ export function loadTokensFromEnv(args: {
     accessToken: string;
     envFile: string;
 };
+/**
+ * Create YotoClient with standard token persistence callbacks
+ * @param {object} options
+ * @param {string} options.clientId - OAuth client ID
+ * @param {string} options.refreshToken - OAuth refresh token
+ * @param {string} options.accessToken - OAuth access token
+ * @param {string} [options.outputFile='.env'] - File to save refreshed tokens to
+ * @returns {YotoClient}
+ */
 export function createYotoClient({ clientId, refreshToken, accessToken, outputFile }: {
     clientId: string;
     refreshToken: string;
     accessToken: string;
     outputFile?: string | undefined;
 }): YotoClient;
+/**
+ * Standard error handler for CLI tools
+ * @param {any} error
+ */
 export function handleCliError(error: any): void;
+/**
+ * Print CLI tool header with title
+ * @param {string} title - The title to display
+ */
 export function printHeader(title: string): void;
 import type { ArgscloptsParseArgsOptionsConfig } from 'argsclopts';
 import { YotoClient } from '../../index.js';

package/bin/lib/cli-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-helpers.d.ts","sourceRoot":"","sources":["cli-helpers.js"],"names":[],"mappings":"AAYA,oCAFa,gCAAgC,CAoB5C;AAOD,sCAHW,MAAM,GACJ,MAAM,CAUlB;AAQD,wCAJW;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;CAAE,GACtD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoB5F;AAWD,sFANG;IAAwB,QAAQ,EAAxB,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,WAAW,EAA3B,MAAM;IACW,UAAU;CACnC,GAAU,UAAU,CAsBtB;AAMD,sCAFW,GAAG,QAyBb;AAMD,mCAFW,MAAM,QAKhB;sDA1IoD,YAAY;2BAGtC,gBAAgB"}
+{"version":3,"file":"cli-helpers.d.ts","sourceRoot":"","sources":["cli-helpers.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,oCAFa,gCAAgC,CAoB5C;AAED;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;GAKG;AACH,wCAJW;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;CAAE,GACtD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoB5F;AAED;;;;;;;;GAQG;AACH,sFANG;IAAwB,QAAQ,EAAxB,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,WAAW,EAA3B,MAAM;IACW,UAAU;CACnC,GAAU,UAAU,CAsBtB;AAED;;;GAGG;AACH,sCAFW,GAAG,QAyBb;AAED;;;GAGG;AACH,mCAFW,MAAM,QAKhB;sDA1IoD,YAAY;2BAGtC,gBAAgB"}

package/bin/lib/token-helpers.d.ts

@@ -1,14 +1,46 @@
+/**
+ * Format timestamp
+ * @param {number} timestamp
+ * @returns {string}
+ */
 export function formatTimestamp(timestamp: number): string;
+/**
+ * Check if token is expired
+ * @param {number} exp
+ * @param {number} bufferSeconds
+ * @returns {{expired: boolean, message: string}}
+ */
 export function checkExpiration(exp: number, bufferSeconds?: number): {
     expired: boolean;
     message: string;
 };
+/**
+ * Check if a JWT token is expired or about to expire
+ * @param {string} token - JWT token to check
+ * @param {number} bufferSeconds - Seconds before expiration to consider expired
+ * @returns {{expired: boolean, message: string}}
+ */
 export function checkTokenExpiration(token: string, bufferSeconds?: number): {
     expired: boolean;
     message: string;
 };
+/**
+ * Decode a JWT token without verification
+ * @param {string} token
+ * @returns {any}
+ */
 export function decodeJwt(token: string): any;
+/**
+ * Save tokens to .env file
+ * @param {string} filename
+ * @param {YotoTokenResponse} tokens
+ * @param {string} clientId
+ */
 export function saveTokensToEnv(filename: string, tokens: YotoTokenResponse, clientId: string): Promise<void>;
+/**
+ * Sleep for a specified number of milliseconds
+ * @param {number} ms
+ */
 export function sleep(ms: number): Promise<any>;
 import type { YotoTokenResponse } from '../../lib/api-endpoints/auth.js';
 //# sourceMappingURL=token-helpers.d.ts.map

package/bin/lib/token-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-helpers.d.ts","sourceRoot":"","sources":["token-helpers.js"],"names":[],"mappings":"AAaA,2CAHW,MAAM,GACJ,MAAM,CAKlB;AAQD,qCAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAmB/C;AAQD,4CAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAa/C;AAOD,iCAHW,MAAM,GACJ,GAAG,CASf;AAQD,0CAJW,MAAM,UACN,iBAAiB,YACjB,MAAM,iBA8DhB;AAMD,0BAFW,MAAM,gBAIhB;uCArJmC,iCAAiC"}
+{"version":3,"file":"token-helpers.d.ts","sourceRoot":"","sources":["token-helpers.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;GAKG;AACH,qCAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAmB/C;AAED;;;;;GAKG;AACH,4CAJW,MAAM,kBACN,MAAM,GACJ;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAa/C;AAED;;;;GAIG;AACH,iCAHW,MAAM,GACJ,GAAG,CASf;AAED;;;;;GAKG;AACH,0CAJW,MAAM,UACN,iBAAiB,YACjB,MAAM,iBA8DhB;AAED;;;GAGG;AACH,0BAFW,MAAM,gBAIhB;uCArJmC,iCAAiC"}

package/index.d.ts

@@ -1,4 +1,44 @@
+/**
+ * @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
+ */
+/**
+ * @typedef {Object} YotoClientConstructorOptions
+ * @property {string} clientId - OAuth client ID
+ * @property {string} refreshToken - OAuth refresh token
+ * @property {string} accessToken - Initial OAuth access token (JWT)
+ * @property {(event: RefreshSuccessEvent) => void | Promise<void>} onTokenRefresh - **REQUIRED** Callback invoked when tokens are refreshed. You MUST persist these tokens (to file, database, etc.) as the refresh can happen at any time during API calls. The refresh token may be rotated by the auth server. **DO NOT STUB THIS CALLBACK** - always implement proper persistence logic.
+ * @property {number} [bufferSeconds=30] - Seconds before expiration to consider token expired
+ * @property {() => void | Promise<void>} [onRefreshStart] - Optional callback invoked when token refresh starts. Defaults to console.log.
+ * @property {(error: Error) => void | Promise<void>} [onRefreshError] - Optional callback invoked when token refresh fails with a transient error. Defaults to console.warn.
+ * @property {(error: Error) => void | Promise<void>} [onInvalid] - Optional callback invoked when refresh token is permanently invalid. Defaults to console.error.
+ * @property {string} [userAgent] - Optional user agent string to identify your application
+ * @property {RequestOptions} [defaultRequestOptions] - Default undici request options for all requests (dispatcher, timeouts, etc.)
+ */
+/**
+ * Yoto API Client with automatic token refresh
+ */
 export class YotoClient {
+    /**
+     * Get authorization URL for browser-based OAuth flow
+     * @see https://yoto.dev/api/get-authorize/
+     * @param {object} params
+     * @param {string} params.clientId - OAuth client ID
+     * @param {string} params.redirectUri - Redirect URI after authorization
+     * @param {'code' | 'token' | 'id_token' | 'code token' | 'code id_token' | 'token id_token' | 'code token id_token'} params.responseType - OAuth response type
+     * @param {string} params.state - State parameter for CSRF protection
+     * @param {string} [params.audience] - Audience for the token
+     * @param {string} [params.scope] - Requested scopes
+     * @param {string} [params.nonce] - Nonce for replay attack prevention
+     * @param {'none' | 'login' | 'consent' | 'select_account'} [params.prompt] - Authorization prompt behavior
+     * @param {number} [params.maxAge] - Maximum authentication age in seconds
+     * @param {string} [params.codeChallenge] - PKCE code challenge
+     * @param {'S256' | 'plain'} [params.codeChallengeMethod] - PKCE code challenge method
+     * @returns {string} Authorization URL
+     */
     static getAuthorizeUrl(params: {
         clientId: string;
         redirectUri: string;
@@ -12,6 +52,22 @@ export class YotoClient {
         codeChallenge?: string | undefined;
         codeChallengeMethod?: "S256" | "plain" | undefined;
     }): string;
+    /**
+     * Exchange authorization code or refresh token for access tokens
+     * @see https://yoto.dev/api/post-oauth-token/
+     * @param {object} params
+     * @param {'authorization_code' | 'refresh_token' | 'client_credentials' | 'urn:ietf:params:oauth:grant-type:device_code'} params.grantType - OAuth grant type
+     * @param {string} [params.code] - Authorization code (required for authorization_code grant)
+     * @param {string} [params.redirectUri] - Redirect URI (required for authorization_code grant if used in authorize request)
+     * @param {string} [params.refreshToken] - Refresh token (required for refresh_token grant)
+     * @param {string} [params.clientId] - OAuth client ID
+     * @param {string} [params.clientSecret] - OAuth client secret
+     * @param {string} [params.scope] - Requested scope
+     * @param {string} [params.codeVerifier] - PKCE code verifier
+     * @param {string} [params.deviceCode] - Device code (required for device_code grant)
+     * @param {string} [params.audience] - Audience for the token
+     * @returns {Promise<YotoTokenResponse>}
+     */
     static exchangeToken(params: {
         grantType: "authorization_code" | "refresh_token" | "client_credentials" | "urn:ietf:params:oauth:grant-type:device_code";
         code?: string | undefined;
@@ -24,13 +80,41 @@ export class YotoClient {
         deviceCode?: string | undefined;
         audience?: string | undefined;
     }): Promise<Auth.YotoTokenResponse>;
+    /**
+     * Request device code for device authorization flow
+     * @see https://yoto.dev/api/post-oauth-device-code/
+     * @param {object} params
+     * @param {string} params.clientId - OAuth client ID
+     * @param {string} [params.scope] - Requested scopes
+     * @param {string} [params.audience] - Audience for the token
+     * @returns {Promise<YotoDeviceCodeResponse>}
+     */
     static requestDeviceCode(params: {
         clientId: string;
         scope?: string | undefined;
         audience?: string | undefined;
     }): Promise<Auth.YotoDeviceCodeResponse>;
+    /**
+     * Create a new Yoto API client
+     * @param {YotoClientConstructorOptions} options
+     */
     constructor({ clientId, refreshToken, accessToken, onTokenRefresh, bufferSeconds, onRefreshStart, onRefreshError, onInvalid, userAgent, defaultRequestOptions }: YotoClientConstructorOptions);
+    /**
+     * Get the underlying RefreshableToken instance
+     * @returns {RefreshableToken}
+     */
     get token(): RefreshableToken;
+    /**
+     * Get content/card details
+     * @see https://yoto.dev/api/getcontent/
+     * @param {object} params
+     * @param {string} params.cardId - The card/content ID
+     * @param {string} [params.timezone] - Timezone for schedule-based content
+     * @param {'full' | 'pre'} [params.signingType] - Type of URL signing
+     * @param {boolean} [params.playable] - Whether to include playback URLs
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoContentResponse>}
+     */
     getContent({ cardId, timezone, signingType, playable, requestOptions }: {
         cardId: string;
         timezone?: string | undefined;
@@ -40,41 +124,97 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Content.YotoContentResponse>;
+    /**
+     * Get user's MYO (Make Your Own) content
+     * @see https://yoto.dev/api/getusersmyocontent/
+     * @param {object} [params]
+     * @param {boolean} [params.showDeleted=false] - Include deleted content
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoMyoContentResponse>}
+     */
     getUserMyoContent({ showDeleted, requestOptions }?: {
         showDeleted?: boolean | 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<Content.YotoMyoContentResponse>;
+    /**
+     * Create or update content/card
+     * @see https://yoto.dev/api/createorupdatecontent/
+     * @param {object} params
+     * @param {YotoCreateOrUpdateContentRequest} params.content - Content data to create/update
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoCreateOrUpdateContentResponse>}
+     */
     createOrUpdateContent({ content, requestOptions }: {
         content: Content.YotoCreateOrUpdateContentRequest;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Content.YotoCreateOrUpdateContentResponse>;
+    /**
+     * Delete content/card
+     * @see https://yoto.dev/api/deletecontent/
+     * @param {object} params
+     * @param {string} params.cardId - The card/content ID to delete
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDeleteContentResponse>}
+     */
     deleteContent({ cardId, requestOptions }: {
         cardId: string;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Content.YotoDeleteContentResponse>;
+    /**
+     * Get all devices for authenticated user
+     * @see https://yoto.dev/api/getdevices/
+     * @param {object} [params]
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDevicesResponse>}
+     */
     getDevices({ requestOptions }?: {
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoDevicesResponse>;
+    /**
+     * Get device status
+     * @see https://yoto.dev/api/getdevicestatus/
+     * @param {object} params
+     * @param {string} params.deviceId - Device ID
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDeviceStatusResponse>}
+     */
     getDeviceStatus({ deviceId, requestOptions }: {
         deviceId: string;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoDeviceStatusResponse>;
+    /**
+     * Get device configuration
+     * @see https://yoto.dev/api/getdeviceconfig/
+     * @param {object} params
+     * @param {string} params.deviceId - Device ID
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDeviceConfigResponse>}
+     */
     getDeviceConfig({ deviceId, requestOptions }: {
         deviceId: string;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoDeviceConfigResponse>;
+    /**
+     * Update device configuration
+     * @see https://yoto.dev/api/updatedeviceconfig/
+     * @param {object} params
+     * @param {string} params.deviceId - Device ID
+     * @param {YotoUpdateDeviceConfigRequest} params.configUpdate - Config updates
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUpdateDeviceConfigResponse>}
+     */
     updateDeviceConfig({ deviceId, configUpdate, requestOptions }: {
         deviceId: string;
         configUpdate: Devices.YotoUpdateDeviceConfigRequest;
@@ -82,6 +222,15 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoUpdateDeviceConfigResponse>;
+    /**
+     * Update device shortcuts
+     * @see https://yoto.dev/api/updateshortcutsbeta/
+     * @param {object} params
+     * @param {string} params.deviceId - Device ID
+     * @param {YotoUpdateShortcutsRequest} params.shortcutsUpdate - Shortcuts config
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUpdateShortcutsResponse>}
+     */
     updateDeviceShortcuts({ deviceId, shortcutsUpdate, requestOptions }: {
         deviceId: string;
         shortcutsUpdate: Devices.YotoUpdateShortcutsRequest;
@@ -89,6 +238,16 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoUpdateShortcutsResponse>;
+    /**
+     * Send command to device
+     * @see https://yoto.dev/api/senddevicecommand/
+     * @see https://yoto.dev/players-mqtt/mqtt-docs/
+     * @param {object} params
+     * @param {string} params.deviceId - Device ID
+     * @param {YotoDeviceCommand} params.command - Command to send
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDeviceCommandResponse>}
+     */
     sendDeviceCommand({ deviceId, command, requestOptions }: {
         deviceId: string;
         command: Devices.YotoDeviceCommand;
@@ -96,23 +255,55 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Devices.YotoDeviceCommandResponse>;
+    /**
+     * Get all family library groups
+     * @see https://yoto.dev/api/getgroups/
+     * @param {object} [params]
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoGroup[]>}
+     */
     getGroups({ requestOptions }?: {
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<FamilyLibraryGroups.YotoGroup[]>;
+    /**
+     * Create a family library group
+     * @see https://yoto.dev/api/createagroup/
+     * @param {object} params
+     * @param {YotoCreateGroupRequest} params.group - Group data
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoGroup>}
+     */
     createGroup({ group, requestOptions }: {
         group: FamilyLibraryGroups.YotoCreateGroupRequest;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<FamilyLibraryGroups.YotoGroup>;
+    /**
+     * Get a specific family library group
+     * @see https://yoto.dev/api/getgroup/
+     * @param {object} params
+     * @param {string} params.groupId - Group ID
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoGroup>}
+     */
     getGroup({ groupId, requestOptions }: {
         groupId: string;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<FamilyLibraryGroups.YotoGroup>;
+    /**
+     * Update a family library group
+     * @see https://yoto.dev/api/updateagroup/
+     * @param {object} params
+     * @param {string} params.groupId - Group ID
+     * @param {YotoUpdateGroupRequest} params.group - Updated group data
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoGroup>}
+     */
     updateGroup({ groupId, group, requestOptions }: {
         groupId: string;
         group: FamilyLibraryGroups.YotoUpdateGroupRequest;
@@ -120,17 +311,41 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<FamilyLibraryGroups.YotoGroup>;
+    /**
+     * Delete a family library group
+     * @see https://yoto.dev/api/deleteagroup/
+     * @param {object} params
+     * @param {string} params.groupId - Group ID
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoDeleteGroupResponse>}
+     */
     deleteGroup({ groupId, requestOptions }: {
         groupId: string;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<FamilyLibraryGroups.YotoDeleteGroupResponse>;
+    /**
+     * Get all family images
+     * @see https://yoto.dev/api/getfamilyimages/
+     * @param {object} [params]
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoFamilyImagesResponse>}
+     */
     getFamilyImages({ requestOptions }?: {
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Family.YotoFamilyImagesResponse>;
+    /**
+     * Get a specific family image
+     * @see https://yoto.dev/api/getafamilyimage/
+     * @param {object} params
+     * @param {string} params.imageId - Image ID
+     * @param {'640x480' | '320x320'} params.size - Image size
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoFamilyImageResponse>}
+     */
     getAFamilyImage({ imageId, size, requestOptions }: {
         imageId: string;
         size: "640x480" | "320x320";
@@ -138,22 +353,54 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Family.YotoFamilyImageResponse>;
+    /**
+     * Upload a family image
+     * @see https://yoto.dev/api/uploadafamilyimage/
+     * @param {object} params
+     * @param {Buffer} params.imageData - Image binary data
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUploadFamilyImageResponse>}
+     */
     uploadAFamilyImage({ imageData, requestOptions }: {
         imageData: Buffer;
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Family.YotoUploadFamilyImageResponse>;
+    /**
+     * Get public Yoto icons
+     * @see https://yoto.dev/api/getpublicicons/
+     * @param {object} [params]
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoPublicIconsResponse>}
+     */
     getPublicIcons({ requestOptions }?: {
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Icons.YotoPublicIconsResponse>;
+    /**
+     * Get user's custom icons
+     * @see https://yoto.dev/api/getusericons/
+     * @param {object} [params]
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUserIconsResponse>}
+     */
     getUserIcons({ requestOptions }?: {
         requestOptions?: ({
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Icons.YotoUserIconsResponse>;
+    /**
+     * Upload a custom icon
+     * @see https://yoto.dev/api/uploadicon/
+     * @param {object} params
+     * @param {Buffer} params.imageData - Image binary data
+     * @param {boolean} [params.autoConvert=true] - Auto-convert to proper format
+     * @param {string} [params.filename] - Optional filename
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUploadIconResponse>}
+     */
     uploadIcon({ imageData, autoConvert, filename, requestOptions }: {
         imageData: Buffer;
         autoConvert?: boolean | undefined;
@@ -162,6 +409,15 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Icons.YotoUploadIconResponse>;
+    /**
+     * Get audio upload URL
+     * @see https://yoto.dev/api/getaudiouploadurl/
+     * @param {object} params
+     * @param {string} params.sha256 - SHA256 hash of audio file
+     * @param {string} [params.filename] - Optional filename
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoAudioUploadUrlResponse>}
+     */
     getAudioUploadUrl({ sha256, filename, requestOptions }: {
         sha256: string;
         filename?: string | undefined;
@@ -169,6 +425,18 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Media.YotoAudioUploadUrlResponse>;
+    /**
+     * Upload a cover image
+     * @see https://yoto.dev/api/uploadcoverimage/
+     * @param {object} params
+     * @param {Buffer} [params.imageData] - Image binary data
+     * @param {string} [params.imageUrl] - URL to image
+     * @param {boolean} [params.autoConvert] - Auto-convert to proper format
+     * @param {YotoCoverType} [params.coverType] - Cover image type
+     * @param {string} [params.filename] - Optional filename
+     * @param {RequestOptions} [params.requestOptions] - Request options that override defaults
+     * @returns {Promise<YotoUploadCoverImageResponse>}
+     */
     uploadCoverImage({ imageData, imageUrl, autoConvert, coverType, filename, requestOptions }: {
         imageData?: Buffer<ArrayBufferLike> | undefined;
         imageUrl?: string | undefined;
@@ -179,6 +447,64 @@ export class YotoClient {
             dispatcher?: import("undici").Dispatcher;
         } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
     }): Promise<Media.YotoUploadCoverImageResponse>;
+    /**
+     * Create an MQTT client for a specific device
+     *
+     * The MQTT client provides real-time communication with Yoto devices:
+     * - Subscribe to device events (playback, volume, card changes)
+     * - Subscribe to device status (battery, temperature, network)
+     * - Send commands (volume, card playback, ambient lights, etc.)
+     *
+     * @see https://yoto.dev/players-mqtt/
+     * @param {object} params
+     * @param {string} params.deviceId - The device ID to connect to
+     * @param {object} [params.options] - MQTT client options
+     * @param {boolean} [params.options.autoSubscribe=true] - Auto-subscribe to device topics on connect
+     * @returns {Promise<YotoMqttClient>} MQTT client instance
+     *
+     * @example
+     * // Create YotoClient with token refresh callback
+     * const client = new YotoClient({
+     *   clientId: 'your-client-id',
+     *   refreshToken: 'your-refresh-token',
+     *   accessToken: 'your-access-token',
+     *   onTokenRefresh: async (event) => {
+     *     // Save tokens to file/database
+     *     await saveTokens(event.accessToken, event.refreshToken)
+     *   }
+     * })
+     *
+     * // Get an online device
+     * const devices = await client.getDevices()
+     * const device = devices.devices.find(d => d.online)
+     *
+     * // Create MQTT client for the device
+     * const mqttClient = await client.createMqttClient({ deviceId: device.deviceId })
+     *
+     * // Setup event handlers
+     * mqttClient.on('events', (message) => {
+     *   console.log('Playback event:', message.playbackStatus)
+     *   console.log('Volume:', message.volume)
+     * })
+     *
+     * mqttClient.on('status', (message) => {
+     *   console.log('Battery:', message.status.batteryLevel)
+     *   console.log('Temperature:', message.status.temp)
+     * })
+     *
+     * mqttClient.on('response', (message) => {
+     *   console.log('Command acknowledged:', message.status)
+     * })
+     *
+     * // Connect and send commands
+     * await mqttClient.connect()
+     * await mqttClient.requestStatus()
+     * await mqttClient.setVolume(50)
+     * await mqttClient.startCard({ uri: 'https://yoto.io/cardId123' })
+     *
+     * // Cleanup
+     * await mqttClient.disconnect()
+     */
     createMqttClient({ deviceId, options }: {
         deviceId: string;
         options?: {
@@ -188,21 +514,63 @@ export class YotoClient {
     #private;
 }
 export type RefreshSuccessEvent = {
+    /**
+     * - The OAuth client ID
+     */
     clientId: string;
+    /**
+     * - The new access token
+     */
     accessToken: string;
+    /**
+     * - The refresh token (may be updated)
+     */
     refreshToken: string;
+    /**
+     * - Unix timestamp in seconds when token expires
+     */
     expiresAt: number;
 };
 export type YotoClientConstructorOptions = {
+    /**
+     * - OAuth client ID
+     */
     clientId: string;
+    /**
+     * - OAuth refresh token
+     */
     refreshToken: string;
+    /**
+     * - Initial OAuth access token (JWT)
+     */
     accessToken: string;
+    /**
+     * - **REQUIRED** Callback invoked when tokens are refreshed. You MUST persist these tokens (to file, database, etc.) as the refresh can happen at any time during API calls. The refresh token may be rotated by the auth server. **DO NOT STUB THIS CALLBACK** - always implement proper persistence logic.
+     */
     onTokenRefresh: (event: RefreshSuccessEvent) => void | Promise<void>;
+    /**
+     * - Seconds before expiration to consider token expired
+     */
     bufferSeconds?: number;
+    /**
+     * - Optional callback invoked when token refresh starts. Defaults to console.log.
+     */
     onRefreshStart?: () => void | Promise<void>;
+    /**
+     * - Optional callback invoked when token refresh fails with a transient error. Defaults to console.warn.
+     */
     onRefreshError?: (error: Error) => void | Promise<void>;
+    /**
+     * - Optional callback invoked when refresh token is permanently invalid. Defaults to console.error.
+     */
     onInvalid?: (error: Error) => void | Promise<void>;
+    /**
+     * - Optional user agent string to identify your application
+     */
     userAgent?: string;
+    /**
+     * - Default undici request options for all requests (dispatcher, timeouts, etc.)
+     */
     defaultRequestOptions?: RequestOptions;
 };
 import { RefreshableToken } from './lib/token.js';