yoto-nodejs-client 0.0.1

package/lib/api-endpoints/icons.js

@@ -0,0 +1,201 @@
+/**
+ * @import { RequestOptions } from './helpers.js'
+ */
+import { request } from 'undici'
+import { defaultAuthHeaders, handleBadResponse, mergeRequestOptions } from './helpers.js'
+import { YOTO_API_URL } from './constants.js'
+
+// ============================================================================
+// Icons: Display icon endpoints for public and custom user icons
+// ============================================================================
+
+/**
+ * @see https://yoto.dev/api/getpublicicons/
+ * @typedef {Object} YotoPublicIconsResponse
+ * @property {YotoPublicIcon[]} displayIcons - Array of public display icons
+ */
+
+/**
+ * @see https://yoto.dev/api/getpublicicons/
+ * @typedef {Object} YotoPublicIcon
+ * @property {string} displayIconId - Unique identifier for the icon
+ * @property {string} mediaId - Unique identifier for the underlying icon file
+ * @property {string} userId - ID of the user who uploaded this icon (always "yoto" for public icons)
+ * @property {string} createdAt - ISO 8601 timestamp when icon record was created
+ * @property {string} title - Title of the display icon
+ * @property {string} url - URL of the display icon
+ * @property {boolean} public - Indicates if the icon is public (always true for public icons)
+ * @property {boolean} [new] - Indicates if this is a new icon (may not always be present)
+ * @property {string[]} publicTags - Public tags associated with the display icon
+ */
+
+/**
+ * Retrieves the list of public icons that are available to every user.
+ * @see https://yoto.dev/api/getpublicicons/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoPublicIconsResponse>} Public display icons
+ * @example
+ * import { getPublicIcons } from 'yoto-nodejs-client'
+ *
+ * const icons = await getPublicIcons({
+ *   accessToken
+ * })
+ *
+ * console.log(`Found ${icons.displayIcons.length} public icons`)
+ * icons.displayIcons.forEach(icon => {
+ *   console.log(`${icon.title} - Tags: ${icon.publicTags.join(', ')}`)
+ * })
+ */
+export async function getPublicIcons ({
+  accessToken,
+  userAgent,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/displayIcons/user/yoto', YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoPublicIconsResponse} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @see https://yoto.dev/api/getusericons/
+ * @typedef {Object} YotoUserIconsResponse
+ * @property {YotoUserIcon[]} displayIcons - Array of user's custom display icons
+ */
+
+/**
+ * @see https://yoto.dev/api/getusericons/
+ * @typedef {Object} YotoUserIcon
+ * @property {string} displayIconId - Unique identifier for the icon
+ * @property {string} mediaId - Unique identifier for the underlying icon file
+ * @property {string} userId - ID of the user who uploaded this icon
+ * @property {string} createdAt - ISO 8601 timestamp when icon record was created
+ * @property {string} url - URL of the display icon
+ * @property {boolean} public - Indicates if the icon is public (always false for user icons)
+ */
+
+/**
+ * Retrieves the authenticated user's custom uploaded icons.
+ * @see https://yoto.dev/api/getusericons/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoUserIconsResponse>} User's custom display icons
+ */
+export async function getUserIcons ({
+  accessToken,
+  userAgent,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/displayIcons/user/me', YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoUserIconsResponse} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @see https://yoto.dev/api/uploadcustomicon/
+ * @typedef {Object} YotoUploadIconResponse
+ * @property {YotoDisplayIcon} displayIcon - The uploaded or existing display icon
+ */
+
+/**
+ * @see https://yoto.dev/api/uploadcustomicon/
+ * @typedef {Object} YotoDisplayIcon
+ * @property {string} displayIconId - Unique identifier for the icon
+ * @property {string} mediaId - Unique identifier for the underlying icon file
+ * @property {string} userId - ID of the user who uploaded this icon
+ * @property {string | object} url - URL of the display icon, or empty object {} for duplicates
+ * @property {boolean} [new] - True if this is a new upload, undefined for duplicates
+ * @property {string} [_id] - MongoDB ID (present for duplicate uploads)
+ * @property {string} [createdAt] - ISO 8601 timestamp (present for duplicate uploads)
+ */
+
+/**
+ * Uploads a custom 16×16px icon for the authenticated user.
+ * Icons are deduplicated by content - re-uploading the same image returns the existing icon.
+ *
+ * Image processing with autoConvert=true (recommended):
+ * - Auto-resizes to 16×16px (crop/pad as needed)
+ * - Adjusts brightness if > ⅔
+ * - Converts to PNG
+ * - Accepts any image format
+ *
+ * Image requirements with autoConvert=false (strict):
+ * - Must be exactly 16×16px
+ * - Only PNG or GIF allowed
+ * - PNG must be 24-bit RGBA (sRGB, 4 channels, hasAlpha, no palette)
+ * - GIF accepted as-is
+ *
+ * @see https://yoto.dev/api/uploadcustomicon/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {Buffer} options.imageData The binary image data (16×16px icon)
+ * @param  {boolean} [options.autoConvert=true] Auto-resize and process the image to 16×16px
+ * @param  {string} [options.filename] Override the stored base filename
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoUploadIconResponse>} The uploaded or existing display icon
+ * @example
+ * import { readFile } from 'fs/promises'
+ * import { uploadIcon } from 'yoto-nodejs-client'
+ *
+ * const imageData = await readFile('./my-icon.png')
+ * const result = await uploadIcon({
+ *   accessToken,
+ *   imageData,
+ *   autoConvert: true,
+ *   filename: 'my-custom-icon'
+ * })
+ *
+ * if (result.displayIcon.new) {
+ *   console.log('New icon uploaded:', result.displayIcon.displayIconId)
+ * } else {
+ *   console.log('Icon already exists:', result.displayIcon.displayIconId)
+ * }
+ */
+export async function uploadIcon ({
+  accessToken,
+  userAgent,
+  imageData,
+  autoConvert = true,
+  filename,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/displayIcons/user/me/upload', YOTO_API_URL)
+
+  if (autoConvert !== undefined) requestUrl.searchParams.set('autoConvert', autoConvert.toString())
+  if (filename) requestUrl.searchParams.set('filename', filename)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'POST',
+    headers: {
+      ...defaultAuthHeaders({ accessToken, userAgent }),
+      'Content-Type': 'application/octet-stream'
+    },
+    body: imageData
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoUploadIconResponse} */ (await response.body.json())
+  return responseBody
+}

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

@@ -0,0 +1,118 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { getPublicIcons, getUserIcons } from './icons.js'
+import { YotoAPIError } from './helpers.js'
+import { loadTestTokens, logResponse } from './test-helpers.js'
+
+const { accessToken } = loadTestTokens()
+
+test('getPublicIcons', async (t) => {
+  await t.test('should fetch public display icons', async () => {
+    const response = await getPublicIcons({
+      accessToken
+    })
+
+    // Log response for type verification and documentation
+    logResponse('GET /media/displayIcons/user/yoto', response)
+
+    // Validate response structure matches YotoPublicIconsResponse
+    assert.ok(response, 'Response should exist')
+    assert.ok(response.displayIcons, 'Response should have displayIcons property')
+    assert.ok(Array.isArray(response.displayIcons), 'displayIcons should be an array')
+    assert.ok(response.displayIcons.length > 0, 'Should have at least one public icon')
+
+    // Validate icon structure
+    const icon = response.displayIcons[0]
+    assert.ok(icon, 'Icon should exist')
+    assert.ok(typeof icon.displayIconId === 'string', 'Icon should have displayIconId string')
+    assert.ok(typeof icon.mediaId === 'string', 'Icon should have mediaId string')
+    assert.ok(typeof icon.userId === 'string', 'Icon should have userId string')
+    assert.strictEqual(icon.userId, 'yoto', 'Public icon userId should be "yoto"')
+    assert.ok(typeof icon.createdAt === 'string', 'Icon should have createdAt string')
+    assert.ok(typeof icon.title === 'string', 'Icon should have title string')
+    assert.ok(typeof icon.url === 'string', 'Icon should have url string')
+    assert.ok(icon.url.startsWith('http'), 'Icon URL should be a valid URL')
+    assert.strictEqual(icon.public, true, 'Public icon should have public=true')
+    // Note: new field may not always be present in public icons
+    if (icon.new !== undefined) {
+      assert.strictEqual(typeof icon.new, 'boolean', 'Icon new should be boolean when present')
+    }
+    assert.ok(Array.isArray(icon.publicTags), 'Icon should have publicTags array')
+  })
+
+  await t.test('should fail with invalid token', async () => {
+    await assert.rejects(
+      async () => {
+        await getPublicIcons({
+          accessToken: 'invalid-token'
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        assert.ok(err.statusCode === 401 || err.statusCode === 403, 'Should return 401 or 403 for invalid token')
+        assert.ok(err.body, 'Error should have body')
+        return true
+      }
+    )
+  })
+})
+
+test('getUserIcons', async (t) => {
+  await t.test('should fetch user custom icons', async () => {
+    const response = await getUserIcons({
+      accessToken
+    })
+
+    // Log response for type verification and documentation
+    logResponse('GET /media/displayIcons/user/me', response)
+
+    // Validate response structure matches YotoUserIconsResponse
+    assert.ok(response, 'Response should exist')
+    assert.ok(response.displayIcons, 'Response should have displayIcons property')
+    assert.ok(Array.isArray(response.displayIcons), 'displayIcons should be an array')
+
+    // Note: User may not have any custom icons, so we only validate structure if icons exist
+    if (response.displayIcons.length > 0) {
+      const icon = response.displayIcons[0]
+      assert.ok(icon, 'Icon should exist')
+      assert.ok(typeof icon.displayIconId === 'string', 'Icon should have displayIconId string')
+      assert.ok(typeof icon.mediaId === 'string', 'Icon should have mediaId string')
+      assert.ok(typeof icon.userId === 'string', 'Icon should have userId string')
+      assert.ok(typeof icon.createdAt === 'string', 'Icon should have createdAt string')
+      assert.ok(typeof icon.url === 'string', 'Icon should have url string')
+      assert.strictEqual(icon.public, false, 'User icon should have public=false')
+      assert.strictEqual('title' in icon, false, 'User icon should not have title')
+      assert.strictEqual('publicTags' in icon, false, 'User icon should not have publicTags')
+    }
+  })
+
+  await t.test('should fail with invalid token', async () => {
+    await assert.rejects(
+      async () => {
+        await getUserIcons({
+          accessToken: 'invalid-token'
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        assert.ok(err.statusCode === 401 || err.statusCode === 403, 'Should return 401 or 403 for invalid token')
+        assert.ok(err.body, 'Error should have body')
+        return true
+      }
+    )
+  })
+})
+
+// TODO: Add tests for uploadIcon
+// - should upload a new icon with autoConvert=true
+// - should return new=true for first upload
+// - should validate response structure matches YotoUploadIconResponse
+// - should upload icon with custom filename
+// - should handle re-upload of same icon (deduplication)
+// - should return existing icon with url={} for duplicate
+// - should list user icons and find uploaded icon
+// - should upload icon with autoConvert=false (strict mode)
+// - should fail with invalid dimensions when autoConvert=false
+// - should fail with invalid format when autoConvert=false
+// - should fail with file that's not an image
+// - should fail with invalid token

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

@@ -0,0 +1,37 @@
+export function getAudioUploadUrl({ accessToken, userAgent, sha256, filename, requestOptions }: {
+    accessToken: string;
+    sha256: string;
+    filename?: string | 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<YotoAudioUploadUrlResponse>;
+export function uploadCoverImage({ accessToken, userAgent, imageData, imageUrl, autoConvert, coverType, filename, requestOptions }: {
+    accessToken: string;
+    imageData?: string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | undefined;
+    imageUrl?: string | undefined;
+    autoConvert?: boolean | undefined;
+    coverType?: YotoCoverType | undefined;
+    filename?: string | 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<YotoUploadCoverImageResponse>;
+export type YotoAudioUpload = {
+    uploadId: string;
+    uploadUrl: string | null;
+};
+export type YotoAudioUploadUrlResponse = {
+    upload: YotoAudioUpload;
+};
+export type YotoCoverImage = {
+    mediaId: string;
+    mediaUrl: string;
+};
+export type YotoUploadCoverImageResponse = {
+    coverImage: YotoCoverImage;
+};
+export type YotoCoverType = "default" | "activities" | "music" | "myo" | "podcast" | "radio" | "sfx" | "stories";
+//# sourceMappingURL=media.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["media.js"],"names":[],"mappings":"AAmEA,gGAPG;IAAwB,WAAW,EAA3B,MAAM;IACU,MAAM,EAAtB,MAAM;IACW,QAAQ;IACR,SAAS;IACD,cAAc;;;CAC/C,GAAU,OAAO,CAAC,0BAA0B,CAAC,CAuB/C;AA6BD,oIAVG;IAAwB,WAAW,EAA3B,MAAM;IACiC,SAAS;IAC/B,QAAQ;IACP,WAAW;IACL,SAAS;IAChB,QAAQ;IACR,SAAS;IACD,cAAc;;;CAC/C,GAAU,OAAO,CAAC,4BAA4B,CAAC,CAuCjD;;cArIa,MAAM;eACN,MAAM,GAAG,IAAI;;;YAMb,eAAe;;;aAMf,MAAM;cACN,MAAM;;;gBAMN,cAAc;;4BAKf,SAAS,GAAG,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS"}

package/lib/api-endpoints/media.js

@@ -0,0 +1,155 @@
+/**
+ * @import { RequestOptions } from './helpers.js'
+ */
+import { request } from 'undici'
+import { defaultAuthHeaders, handleBadResponse, mergeRequestOptions } from './helpers.js'
+import { YOTO_API_URL } from './constants.js'
+
+// ============================================================================
+// Media: Media endpoints for audio uploads and cover images
+//
+// Audio Transcoding:
+// - All uploaded audio files are transcoded using FFmpeg
+// - Converted to MP4 format with AAC codec (libfdk_aac)
+// - Bit Rate: 128Kbps, Sample Rate: 11.025/22.05/44.1/48 kHz
+// - Files are transcoded to balance quality vs compression for players
+// - Maximum file size: 1GB (arbitrary limit to prevent timeout/corruption)
+// ============================================================================
+
+/**
+ * @see https://yoto.dev/api/getanuploadurl/
+ * @typedef {Object} YotoAudioUpload
+ * @property {string} uploadId - Upload identifier
+ * @property {string | null} uploadUrl - Signed upload URL, or null if file already exists
+ */
+
+/**
+ * @see https://yoto.dev/api/getanuploadurl/
+ * @typedef {Object} YotoAudioUploadUrlResponse
+ * @property {YotoAudioUpload} upload
+ */
+
+/**
+ * @see https://yoto.dev/api/uploadcoverimage/
+ * @typedef {Object} YotoCoverImage
+ * @property {string} mediaId - Media identifier
+ * @property {string} mediaUrl - URL to access the uploaded cover image
+ */
+
+/**
+ * @see https://yoto.dev/api/uploadcoverimage/
+ * @typedef {Object} YotoUploadCoverImageResponse
+ * @property {YotoCoverImage} coverImage
+ */
+
+/**
+ * @see https://yoto.dev/api/uploadcoverimage/
+ * @typedef {'default' | 'activities' | 'music' | 'myo' | 'podcast' | 'radio' | 'sfx' | 'stories'} YotoCoverType
+ */
+
+/**
+ * Get a signed URL for uploading an audio file. The SHA256 hash is used to check
+ * if a file with that checksum already exists (deduplication).
+ *
+ * Response behavior:
+ * - If file already exists: uploadUrl will be null (file is already in store)
+ * - If file doesn't exist: uploadUrl contains a signed URL for uploading
+ * - uploadId is always returned and can be used to reference the upload
+ *
+ * @see https://yoto.dev/api/getanuploadurl/
+ * @param {object} options
+ * @param {string} options.accessToken - Authentication token
+ * @param {string} options.sha256 - SHA256 hash of the file to upload
+ * @param {string} [options.filename] - Optional filename for the uploaded file
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @returns {Promise<YotoAudioUploadUrlResponse>}
+ */
+export async function getAudioUploadUrl ({
+  accessToken,
+  userAgent,
+  sha256,
+  filename,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/transcode/audio/uploadUrl', YOTO_API_URL)
+
+  requestUrl.searchParams.set('sha256', sha256)
+  if (filename) requestUrl.searchParams.set('filename', filename)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response, { sha256 })
+
+  const responseBody = /** @type {YotoAudioUploadUrlResponse} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * Upload a cover image to the user's media account. Supports both direct binary
+ * uploads and fetching from a URL. Images are automatically resized based on coverType.
+ *
+ * Image processing:
+ * - Images are resized according to coverType (default: 638x1011px)
+ * - Aspect ratio is preserved
+ * - Images are cropped to fit dimensions, positioned to center
+ * - Supports automatic image conversion with autoConvert flag
+ *
+ * Cover type dimensions:
+ * - default/activities/music/sfx/stories: 638×1011px
+ * - myo: 520×400px
+ * - podcast/radio: 600×600px
+ *
+ * @see https://yoto.dev/api/uploadcoverimage/
+ * @param {object} options
+ * @param {string} options.accessToken - Authentication token
+ * @param {Buffer | Uint8Array | string} [options.imageData] - Binary image data to upload (required if imageUrl not provided)
+ * @param {string} [options.imageUrl] - URL of image to fetch and upload (required if imageData not provided)
+ * @param {boolean} [options.autoConvert] - Whether to automatically convert the image
+ * @param {YotoCoverType} [options.coverType] - Type of cover image, determines dimensions
+ * @param {string} [options.filename] - Custom filename for the uploaded image
+ * @param {string} [options.userAgent] - Optional user agent string
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ * @returns {Promise<YotoUploadCoverImageResponse>}
+ */
+export async function uploadCoverImage ({
+  accessToken,
+  userAgent,
+  imageData,
+  imageUrl,
+  autoConvert,
+  coverType,
+  filename,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/coverImage/user/me/upload', YOTO_API_URL)
+
+  if (imageUrl) requestUrl.searchParams.set('imageUrl', imageUrl)
+  if (autoConvert !== undefined) requestUrl.searchParams.set('autoconvert', autoConvert.toString())
+  if (coverType) requestUrl.searchParams.set('coverType', coverType)
+  if (filename) requestUrl.searchParams.set('filename', filename)
+
+  // Build headers - add Content-Type for binary uploads
+  const headers = imageData
+    ? {
+        ...defaultAuthHeaders({ accessToken, userAgent }),
+        'Content-Type': 'application/octet-stream'
+      }
+    : defaultAuthHeaders({ accessToken, userAgent })
+
+  const baseRequestOptions = {
+    method: 'POST',
+    headers,
+    ...(imageData && { body: imageData })
+  }
+
+  const response = await request(requestUrl, mergeRequestOptions(baseRequestOptions, requestOptions))
+
+  await handleBadResponse(response, { imageUrl, filename })
+
+  const responseBody = /** @type {YotoUploadCoverImageResponse} */ (await response.body.json())
+  return responseBody
+}

package/lib/api-endpoints/test-helpers.d.ts

@@ -0,0 +1,7 @@
+export function loadTestTokens(): {
+    accessToken: string;
+    refreshToken: string;
+    clientId: string;
+};
+export function logResponse(label: string, response: any): void;
+//# sourceMappingURL=test-helpers.d.ts.map

package/lib/api-endpoints/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["test-helpers.js"],"names":[],"mappings":"AAUA,kCAFa;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiCzE;AAmBD,mCAPW,MAAM,YACN,GAAG,QASb"}

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

@@ -0,0 +1,64 @@
+/**
+ * Shared test helpers for loading tokens and test setup
+ */
+
+import { join } from 'node:path'
+
+/**
+ * Load tokens from .env file for testing
+ * @returns {{accessToken: string, refreshToken: string, clientId: string}}
+ */
+export function loadTestTokens () {
+  const testDir = import.meta.dirname
+  const envPath = join(testDir, '../..', '.env')
+
+  // Load .env file from project root
+  try {
+    process.loadEnvFile(envPath)
+  } catch (err) {
+    console.error(`Failed to load .env file from ${envPath}`)
+    console.error('Tests require YOTO_ACCESS_TOKEN and YOTO_REFRESH_TOKEN in .env')
+    console.error('Run `yoto-auth` to authenticate first')
+    process.exit(1)
+  }
+
+  const accessToken = process.env['YOTO_ACCESS_TOKEN']
+  const refreshToken = process.env['YOTO_REFRESH_TOKEN']
+  const clientId = process.env['YOTO_CLIENT_ID']
+
+  if (!accessToken || !refreshToken) {
+    console.error('Missing required environment variables:')
+    console.error('  YOTO_ACCESS_TOKEN:', accessToken ? '✓' : '✗')
+    console.error('  YOTO_REFRESH_TOKEN:', refreshToken ? '✓' : '✗')
+    console.error('\nRun `yoto-auth` to authenticate first')
+    process.exit(1)
+  }
+
+  return {
+    accessToken,
+    refreshToken,
+    clientId: clientId || ''
+  }
+}
+
+/**
+ * Log API response for type verification and documentation.
+ *
+ * This is a first-class testing feature, not temporary debug code.
+ * It helps with:
+ * - Writing new tests by showing actual API response structure
+ * - Verifying type definitions match reality
+ * - Debugging test failures
+ * - Documenting API behavior
+ *
+ * @param {string} label - Descriptive label for the response (e.g., 'GET DEVICES')
+ * @param {any} response - The API response object to log
+ *
+ * @example
+ * const devices = await getDevices({ token })
+ * logResponse('GET DEVICES', devices)
+ */
+export function logResponse (label, response) {
+  console.log(`\n${label}:`)
+  console.dir(response, { depth: null, colors: true })
+}