yoto-nodejs-client 0.0.1 → 0.0.3

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

@@ -1 +1 @@
-{"version":3,"file":"devices.d.ts","sourceRoot":"","sources":["devices.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"devices.d.ts","sourceRoot":"","sources":["devices.js"],"names":[],"mappings":"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"}

package/lib/api-endpoints/devices.js

@@ -63,38 +63,38 @@ export async function getDevices ({
  * @see https://yoto.dev/api/getdevicestatus/
  * @typedef {Object} YotoDeviceStatusResponse
  * @property {string} deviceId - Unique identifier of the device
- * @property {string} [activeCard] - Active card on the device (can be 'none')
- * @property {number} [ambientLightSensorReading] - Reading from ambient light sensor
- * @property {number} [averageDownloadSpeedBytesSecond] - Average download speed in bytes per second
- * @property {number} [batteryLevelPercentage] - Battery level in percentage
- * @property {number} [batteryLevelPercentageRaw] - Raw battery level percentage
- * @property {number} [buzzErrors] - Number of buzz errors
- * @property {0 | 1 | 2} [cardInsertionState] - Card insertion state (0=none, 1=physical, 2=remote)
- * @property {-1 | 0 | 1} [dayMode] - Day mode status (-1=unknown, 0=night, 1=day)
- * @property {number} [errorsLogged] - Number of errors logged
- * @property {string} [firmwareVersion] - Firmware version (e.g., 'v2.23.2')
- * @property {number} [freeDiskSpaceBytes] - Free disk space in bytes
- * @property {boolean} [isAudioDeviceConnected] - Whether audio device is connected
- * @property {boolean} [isBackgroundDownloadActive] - Whether background download is active
- * @property {boolean} [isBluetoothAudioConnected] - Whether Bluetooth audio is connected
- * @property {boolean} [isCharging] - Whether device is currently charging
- * @property {number} [isNfcLocked] - NFC lock status
- * @property {boolean} [isOnline] - Whether device is currently online
- * @property {string} [networkSsid] - Network SSID device is connected to
- * @property {string} [nightlightMode] - Nightlight mode (hex code or 'off')
- * @property {number} [playingSource] - Currently playing source
- * @property {string | null} [powerCapabilities] - Power capabilities (e.g., '0x02')
- * @property {0 | 1 | 2 | 3} [powerSource] - Power source (0=battery, 1=V2 dock, 2=USB-C, 3=Qi)
- * @property {number} [systemVolumePercentage] - System volume in percentage
- * @property {number} [taskWatchdogTimeoutCount] - Task watchdog timeout count
- * @property {number | string} [temperatureCelcius] - Temperature in Celsius (can be number, string like "0", or "notSupported")
- * @property {number} [totalDiskSpaceBytes] - Total disk space in bytes
- * @property {string} [updatedAt] - Timestamp of last update
- * @property {number} [uptime] - Uptime of the device in seconds
- * @property {number} [userVolumePercentage] - User volume in percentage
- * @property {number} [utcOffsetSeconds] - UTC offset in seconds
- * @property {number} [utcTime] - UTC time as Unix timestamp
- * @property {number} [wifiStrength] - WiFi connection strength in decibels
+ * @property {string} activeCard - Active card on the device (can be 'none')
+ * @property {number} ambientLightSensorReading - Reading from ambient light sensor
+ * @property {number} averageDownloadSpeedBytesSecond - Average download speed in bytes per second
+ * @property {number} batteryLevelPercentage - Battery level in percentage
+ * @property {number} batteryLevelPercentageRaw - Raw battery level percentage
+ * @property {number} buzzErrors - Number of buzz errors
+ * @property {0 | 1 | 2} cardInsertionState - Card insertion state from API (0=none, 1=physical, 2=remote) - converted to CardInsertionState string union in YotoDeviceStatus
+ * @property {-1 | 0 | 1} dayMode - Day mode status (-1=unknown, 0=night, 1=day)
+ * @property {number} errorsLogged - Number of errors logged
+ * @property {string} firmwareVersion - Firmware version (e.g., 'v2.23.2')
+ * @property {number} freeDiskSpaceBytes - Free disk space in bytes
+ * @property {boolean} isAudioDeviceConnected - Whether audio device is connected
+ * @property {boolean} isBackgroundDownloadActive - Whether background download is active
+ * @property {boolean} isBluetoothAudioConnected - Whether Bluetooth audio is connected
+ * @property {boolean} isCharging - Whether device is currently charging
+ * @property {number} isNfcLocked - NFC lock status
+ * @property {boolean} isOnline - Whether device is currently online
+ * @property {string} networkSsid - Network SSID device is connected to
+ * @property {string} nightlightMode - Current nightlight color (HTTP returns 'off' or '0x000000'; MQTT provides actual hex color like '0xff5733')
+ * @property {number} playingSource - Currently playing source
+ * @property {string | null} powerCapabilities - Power capabilities (e.g., '0x02')
+ * @property {0 | 1 | 2 | 3} powerSource - Power source (0=battery, 1=V2 dock, 2=USB-C, 3=Qi)
+ * @property {number} systemVolumePercentage - System/max volume in percentage (0-100, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number} taskWatchdogTimeoutCount - Task watchdog timeout count
+ * @property {string | number} temperatureCelcius - Temperature in Celsius (can be number or string like "0" or "notSupported") - Note: API misspells "Celsius"
+ * @property {number} totalDiskSpaceBytes - Total disk space in bytes
+ * @property {string} updatedAt - Timestamp of last update
+ * @property {number} uptime - Uptime of the device in seconds
+ * @property {number} userVolumePercentage - User volume in percentage (0-100, represents 0-16 hardware scale, maps to volume in events)
+ * @property {number} utcOffsetSeconds - UTC offset in seconds
+ * @property {number} utcTime - UTC time as Unix timestamp
+ * @property {number} wifiStrength - WiFi connection strength in decibels
  */
 
 /**
@@ -152,45 +152,107 @@ export async function getDeviceStatus ({
  * @property {string} releaseChannelId - Release channel identifier
  * @property {string} releaseChannelVersion - Release channel version
  * @property {string} fwVersion - Firmware version (undocumented)
- * @property {any} [status] - Device status object (undocumented)
- * @property {YotoDeviceShortcuts} [shortcuts] - Button shortcuts configuration (beta feature)
+ * @property {YotoDeviceFullStatus} status - Comprehensive device status object (undocumented)
+ * @property {YotoDeviceShortcuts} shortcuts - Button shortcuts configuration (beta feature)
+ */
+
+/**
+ * Comprehensive device status from HTTP config endpoint (undocumented)
+ * Contains both user-facing fields and low-level hardware/diagnostic data
+ * Note: Many fields are nullable when device hasn't synced settings yet
+ * @typedef {Object} YotoDeviceFullStatus
+ * @property {string} activeCard - Active card ID or 'none'
+ * @property {number | null} aliveTime - Total time device has been alive
+ * @property {number} als - Ambient light sensor reading
+ * @property {number | null} battery - Raw battery voltage
+ * @property {number} batteryLevel - Battery level percentage
+ * @property {number} batteryLevelRaw - Raw battery level percentage
+ * @property {number | null} batteryRemaining - Battery remaining time estimate
+ * @property {0 | 1} bgDownload - Background download status (0 or 1)
+ * @property {0 | 1} bluetoothHp - Bluetooth headphones enabled (0 or 1)
+ * @property {number} buzzErrors - Number of buzz errors
+ * @property {number} bytesPS - Bytes per second transfer rate
+ * @property {0 | 1 | 2} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
+ * @property {number | null} chgStatLevel - Charge state level
+ * @property {0 | 1} charging - Charging state (0 or 1)
+ * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
+ * @property {number | null} dayBright - Day brightness setting
+ * @property {number | null} dbatTimeout - DBAT timeout value
+ * @property {string} deviceId - Device unique identifier
+ * @property {number | null} dnowBrightness - Current display brightness
+ * @property {number} errorsLogged - Number of errors logged
+ * @property {any} failData - Failure data (null if none)
+ * @property {any} failReason - Failure reason (null if none)
+ * @property {number | null} free - Free memory in bytes
+ * @property {number | null} free32 - Free 32-bit memory pool
+ * @property {number} freeDisk - Free disk space in bytes
+ * @property {number | null} freeDMA - Free DMA memory
+ * @property {string} fwVersion - Firmware version
+ * @property {0 | 1} headphones - Headphones connected (0 or 1)
+ * @property {string | null} lastSeenAt - Last seen timestamp
+ * @property {number | null} missedLogs - Number of missed log entries
+ * @property {string} nfcErrs - NFC errors (e.g., 'n/a')
+ * @property {number} nfcLock - NFC lock status
+ * @property {number | null} nightBright - Night brightness setting
+ * @property {string} nightlightMode - Current nightlight color (hex color like '0xff5733' or 'off')
+ * @property {number} playingStatus - Playing status code
+ * @property {string | null} powerCaps - Power capabilities
+ * @property {0 | 1 | 2 | 3} powerSrc - Power source (0=battery, 1=V2 dock, 2=USB-C, 3=Qi)
+ * @property {number | null} qiOtp - Qi OTP value
+ * @property {string | null} sd_info - SD card information
+ * @property {string | null} shutDown - Shutdown reason ('nA' = running, 'userShutdown' = powered off, etc.)
+ * @property {number | null} shutdownTimeout - Shutdown timeout in seconds
+ * @property {string} ssid - WiFi SSID
+ * @property {number | null} statusVersion - Status version number
+ * @property {string} temp - Temperature readings (format: 'value1:value2' or 'value1:notSupported')
+ * @property {'12' | '24' | null} timeFormat - Time format ('12' or '24')
+ * @property {number} totalDisk - Total disk space in bytes
+ * @property {number} twdt - Task watchdog timeout count
+ * @property {string} updatedAt - Last update timestamp (ISO 8601)
+ * @property {number} upTime - Uptime in seconds
+ * @property {number} userVolume - User volume setting (0-100 percentage, represents 0-16 hardware scale, maps to volume in events)
+ * @property {number} utcOffset - UTC offset in seconds
+ * @property {number} utcTime - UTC time as Unix timestamp
+ * @property {number} volume - System/max volume level (0-100 percentage, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number | null} wifiRestarts - Number of WiFi restarts
+ * @property {number} wifiStrength - WiFi signal strength in dBm
  */
 
 /**
  * @see https://yoto.dev/api/getdeviceconfig/
  * @typedef {Object} YotoDeviceConfig
- * @property {string[]} [alarms] - Array of alarm strings in comma-separated format (e.g., '1111111,1100,5WsQg,,,8')
+ * @property {string[]} alarms - Array of alarm strings in comma-separated format (e.g., '1111111,1100,5WsQg,,,8')
  * @property {string} ambientColour - Ambient light color (hex code)
  * @property {string} bluetoothEnabled - Bluetooth enabled state ('0' or '1')
  * @property {boolean} btHeadphonesEnabled - Bluetooth headphones enabled
- * @property {string} [clockFace] - Clock face style (e.g., 'digital-sun')
- * @property {string} dayDisplayBrightness - Day display brightness (e.g., 'auto')
- * @property {string} dayTime - Day mode start time (e.g., '07:30')
+ * @property {string} clockFace - Clock face style (e.g., 'digital-sun')
+ * @property {string} dayDisplayBrightness - Day display brightness (e.g., 'auto', '100')
+ * @property {string} dayTime - Day mode start time (e.g., '07:00')
  * @property {string} dayYotoDaily - Day mode Yoto Daily card path
  * @property {string} dayYotoRadio - Day mode Yoto Radio card path
- * @property {string} [daySoundsOff] - Day sounds off setting (undocumented)
- * @property {string} [displayDimBrightness] - Display dim brightness level
+ * @property {string} daySoundsOff - Day sounds off setting ('0' or '1') (undocumented)
+ * @property {string} displayDimBrightness - Display dim brightness level (undocumented)
  * @property {string} displayDimTimeout - Display dim timeout in seconds
  * @property {boolean} headphonesVolumeLimited - Whether headphones volume is limited
- * @property {string} [hourFormat] - Hour format ('12' or '24')
- * @property {string} [logLevel] - Log level (e.g., 'none') (undocumented)
- * @property {string} [locale] - Device locale (e.g., 'en') (undocumented)
+ * @property {string} hourFormat - Hour format ('12' or '24') (undocumented)
+ * @property {string} logLevel - Log level (e.g., 'none') (undocumented)
+ * @property {string} locale - Device locale (e.g., 'en') (undocumented)
  * @property {string} maxVolumeLimit - Maximum volume limit
  * @property {string} nightAmbientColour - Night ambient light color (hex code)
  * @property {string} nightDisplayBrightness - Night display brightness
  * @property {string} nightMaxVolumeLimit - Night maximum volume limit
- * @property {string} nightTime - Night mode start time (e.g., '19:30')
+ * @property {string} nightTime - Night mode start time (e.g., '19:20')
  * @property {string} nightYotoDaily - Night mode Yoto Daily card path
- * @property {string} nightYotoRadio - Night mode Yoto Radio card path
- * @property {string} [nightSoundsOff] - Night sounds off setting (undocumented)
- * @property {boolean} [pausePowerButton] - Pause on power button press (undocumented)
- * @property {boolean} [pauseVolumeDown] - Pause on volume down (undocumented)
+ * @property {string} nightYotoRadio - Night mode Yoto Radio card path (can be '0' for none)
+ * @property {string} nightSoundsOff - Night sounds off setting ('0' or '1') (undocumented)
+ * @property {boolean} pausePowerButton - Pause on power button press (undocumented)
+ * @property {boolean} pauseVolumeDown - Pause on volume down (undocumented)
  * @property {boolean} repeatAll - Whether repeat all is enabled
- * @property {boolean} [showDiagnostics] - Show diagnostics (undocumented)
+ * @property {boolean} showDiagnostics - Show diagnostics (undocumented)
  * @property {string} shutdownTimeout - Shutdown timeout in seconds
- * @property {string} [systemVolume] - System volume level (undocumented)
- * @property {string} [timezone] - Timezone setting (undocumented)
- * @property {string} [volumeLevel] - Volume level preset (e.g., 'safe')
+ * @property {string} systemVolume - System volume level (e.g., '100') (undocumented)
+ * @property {string} timezone - Timezone setting (empty string if not set) (undocumented)
+ * @property {string} volumeLevel - Volume level preset (e.g., 'safe') (undocumented)
  */
 
 /**

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

@@ -2,7 +2,7 @@ import test from 'node:test'
 import assert from 'node:assert'
 import { getDevices, getDeviceStatus, getDeviceConfig } from './devices.js'
 import { YotoAPIError } from './helpers.js'
-import { loadTestTokens, logResponse } from './test-helpers.js'
+import { loadTestTokens, logResponse } from './endpoint-test-helpers.js'
 
 const { accessToken } = loadTestTokens()
 

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

@@ -0,0 +1,28 @@
+/**
+ * Load tokens from .env file for testing
+ * @returns {{accessToken: string, refreshToken: string, clientId: string}}
+ */
+export function loadTestTokens(): {
+    accessToken: string;
+    refreshToken: string;
+    clientId: string;
+};
+/**
+ * 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: string, response: any): void;
+//# sourceMappingURL=endpoint-test-helpers.d.ts.map

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

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

package/lib/api-endpoints/family-library-groups.d.ts

@@ -1,3 +1,48 @@
+/**
+ * @see https://yoto.dev/api/getgroups/
+ * @typedef {Object} YotoGroupsResponse
+ * @property {YotoGroup[]} groups - Array of family library groups
+ */
+/**
+ * @see https://yoto.dev/api/getgroups/
+ * @typedef {Object} YotoGroup
+ * @property {string} id - Group identifier
+ * @property {string} name - Group name (e.g., "My Favourites")
+ * @property {string} familyId - Associated family ID
+ * @property {string} imageId - ID for the group image (can be uploaded family image hash or preset like "fp-cards")
+ * @property {string} imageUrl - CDN URL to the group image
+ * @property {YotoGroupItem[]} items - Array of content items in the group
+ * @property {any[]} cards - Array of card objects
+ * @property {string} createdAt - ISO 8601 timestamp when group was created
+ * @property {string} lastModifiedAt - ISO 8601 timestamp when group was last updated
+ */
+/**
+ * @see https://yoto.dev/api/getgroups/
+ * @typedef {Object} YotoGroupItem
+ * @property {string} contentId - ID of the card content
+ * @property {string} addedAt - ISO 8601 timestamp when item was added to group
+ */
+/**
+ * Retrieves all family library groups for the authenticated user's family.
+ * Returns an empty array if no groups exist.
+ * @see https://yoto.dev/api/getgroups/
+ * @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<YotoGroup[]>} Array of family library groups
+ * @example
+ * import { getGroups } from 'yoto-nodejs-client'
+ *
+ * const groups = await getGroups({
+ *   accessToken
+ * })
+ *
+ * console.log('Groups:', groups.length)
+ * groups.forEach(group => {
+ *   console.log(`${group.name}: ${group.items.length} items`)
+ * })
+ */
 export function getGroups({ accessToken, userAgent, requestOptions }: {
     accessToken: string;
     userAgent?: string | undefined;
@@ -5,6 +50,42 @@ export function getGroups({ accessToken, userAgent, requestOptions }: {
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoGroup[]>;
+/**
+ * @see https://yoto.dev/api/createagroup/
+ * @typedef {Object} YotoCreateGroupRequest
+ * @property {string} name - Group name (max 100 characters, UTF-8 supported)
+ * @property {string} imageId - Image ID (preset like "fp-cards" or uploaded image hash)
+ * @property {YotoGroupItemInput[]} items - Array of content items (can be empty, order preserved)
+ */
+/**
+ * @see https://yoto.dev/api/createagroup/
+ * @typedef {Object} YotoGroupItemInput
+ * @property {string} contentId - ID of the card content to add to group
+ */
+/**
+ * Creates a new group in the family library.
+ * Max 20 groups per family. ContentIds must be in family's library (invalid ones filtered out).
+ * @see https://yoto.dev/api/createagroup/
+ * @param  {object} options
+ * @param  {string} options.token    The API token to request with
+ * @param  {YotoCreateGroupRequest} options.group The group data to create
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoGroup>} The created group with populated cards array
+ * @example
+ * import { createGroup } from 'yoto-nodejs-client'
+ *
+ * const group = await createGroup({
+ *   token: accessToken,
+ *   group: {
+ *     name: 'My Favourites',
+ *     imageId: 'fp-cards',
+ *     items: [
+ *       { contentId: '37KwQ' }
+ *     ]
+ *   }
+ * })
+ */
 export function createGroup({ token, userAgent, group, requestOptions }: {
     token: string;
     group: YotoCreateGroupRequest;
@@ -13,6 +94,17 @@ export function createGroup({ token, userAgent, group, requestOptions }: {
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoGroup>;
+/**
+ * Retrieves a specific group by ID.
+ * Returns 404 if group doesn't exist or belongs to another family.
+ * @see https://yoto.dev/api/getagroup/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} options.groupId  The group ID to retrieve
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoGroup>} The requested group with populated cards array
+ */
 export function getGroup({ accessToken, userAgent, groupId, requestOptions }: {
     accessToken: string;
     groupId: string;
@@ -21,6 +113,25 @@ export function getGroup({ accessToken, userAgent, groupId, requestOptions }: {
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoGroup>;
+/**
+ * @see https://yoto.dev/api/updateagroup/
+ * @typedef {Object} YotoUpdateGroupRequest
+ * @property {string} name - Group name (max 100 characters, UTF-8 supported)
+ * @property {string} imageId - Image ID (preset like "fp-cards" or uploaded image hash)
+ * @property {YotoGroupItemInput[]} items - Array of content items (replaces entire array)
+ */
+/**
+ * Updates an existing group.
+ * Can only update groups owned by family. Returns 404 if doesn't exist or owned by another family.
+ * @see https://yoto.dev/api/updateagroup/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} options.groupId  The group ID to update
+ * @param  {YotoUpdateGroupRequest} options.group The updated group data
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoGroup>} The updated group with populated cards array
+ */
 export function updateGroup({ accessToken, userAgent, groupId, group, requestOptions }: {
     accessToken: string;
     groupId: string;
@@ -30,6 +141,22 @@ export function updateGroup({ accessToken, userAgent, groupId, group, requestOpt
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoGroup>;
+/**
+ * @see https://yoto.dev/api/deleteagroup/
+ * @typedef {Object} YotoDeleteGroupResponse
+ * @property {string} id - The ID of the deleted group
+ */
+/**
+ * Deletes a group permanently (hard delete, cannot be recovered).
+ * Content remains in family library. Returns 404 if doesn't exist or owned by another family.
+ * @see https://yoto.dev/api/deleteagroup/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} options.groupId  The group ID to delete
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoDeleteGroupResponse>} Confirmation with deleted group ID
+ */
 export function deleteGroup({ accessToken, userAgent, groupId, requestOptions }: {
     accessToken: string;
     groupId: string;
@@ -39,37 +166,97 @@ export function deleteGroup({ accessToken, userAgent, groupId, requestOptions }:
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoDeleteGroupResponse>;
 export type YotoGroupsResponse = {
+    /**
+     * - Array of family library groups
+     */
     groups: YotoGroup[];
 };
 export type YotoGroup = {
+    /**
+     * - Group identifier
+     */
     id: string;
+    /**
+     * - Group name (e.g., "My Favourites")
+     */
     name: string;
+    /**
+     * - Associated family ID
+     */
     familyId: string;
+    /**
+     * - ID for the group image (can be uploaded family image hash or preset like "fp-cards")
+     */
     imageId: string;
+    /**
+     * - CDN URL to the group image
+     */
     imageUrl: string;
+    /**
+     * - Array of content items in the group
+     */
     items: YotoGroupItem[];
+    /**
+     * - Array of card objects
+     */
     cards: any[];
+    /**
+     * - ISO 8601 timestamp when group was created
+     */
     createdAt: string;
+    /**
+     * - ISO 8601 timestamp when group was last updated
+     */
     lastModifiedAt: string;
 };
 export type YotoGroupItem = {
+    /**
+     * - ID of the card content
+     */
     contentId: string;
+    /**
+     * - ISO 8601 timestamp when item was added to group
+     */
     addedAt: string;
 };
 export type YotoCreateGroupRequest = {
+    /**
+     * - Group name (max 100 characters, UTF-8 supported)
+     */
     name: string;
+    /**
+     * - Image ID (preset like "fp-cards" or uploaded image hash)
+     */
     imageId: string;
+    /**
+     * - Array of content items (can be empty, order preserved)
+     */
     items: YotoGroupItemInput[];
 };
 export type YotoGroupItemInput = {
+    /**
+     * - ID of the card content to add to group
+     */
     contentId: string;
 };
 export type YotoUpdateGroupRequest = {
+    /**
+     * - Group name (max 100 characters, UTF-8 supported)
+     */
     name: string;
+    /**
+     * - Image ID (preset like "fp-cards" or uploaded image hash)
+     */
     imageId: string;
+    /**
+     * - Array of content items (replaces entire array)
+     */
     items: YotoGroupItemInput[];
 };
 export type YotoDeleteGroupResponse = {
+    /**
+     * - The ID of the deleted group
+     */
     id: string;
 };
 //# sourceMappingURL=family-library-groups.d.ts.map

package/lib/api-endpoints/family-library-groups.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"family-library-groups.d.ts","sourceRoot":"","sources":["family-library-groups.js"],"names":[],"mappings":"AA2DA,sEAhBG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,EAAE,CAAC,CA6B/B;AAwCD,yEAnBG;IAAyB,KAAK,EAArB,MAAM;IAC0B,KAAK,EAArC,sBAAsB;IACL,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAoC7B;AAaD,8EANG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAmB7B;AAsBD,wFAPG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IAC0B,KAAK,EAArC,sBAAsB;IACL,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAwB7B;AAmBD,iFANG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CAmB3C;;YAxOa,SAAS,EAAE;;;QAMX,MAAM;UACN,MAAM;cACN,MAAM;aACN,MAAM;cACN,MAAM;WACN,aAAa,EAAE;WACf,GAAG,EAAE;eACL,MAAM;oBACN,MAAM;;;eAMN,MAAM;aACN,MAAM;;;UA6CN,MAAM;aACN,MAAM;WACN,kBAAkB,EAAE;;;eAMpB,MAAM;;;UAmFN,MAAM;aACN,MAAM;WACN,kBAAkB,EAAE;;;QA0CpB,MAAM"}
+{"version":3,"file":"family-library-groups.d.ts","sourceRoot":"","sources":["family-library-groups.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sEAhBG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,EAAE,CAAC,CA6B/B;AAED;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,yEAnBG;IAAyB,KAAK,EAArB,MAAM;IAC0B,KAAK,EAArC,sBAAsB;IACL,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAoC7B;AAED;;;;;;;;;;GAUG;AACH,8EANG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAmB7B;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,wFAPG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IAC0B,KAAK,EAArC,sBAAsB;IACL,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,SAAS,CAAC,CAwB7B;AAED;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,iFANG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CAmB3C;;;;;YAxOa,SAAS,EAAE;;;;;;QAMX,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;WACN,aAAa,EAAE;;;;WACf,GAAG,EAAE;;;;eACL,MAAM;;;;oBACN,MAAM;;;;;;eAMN,MAAM;;;;aACN,MAAM;;;;;;UA6CN,MAAM;;;;aACN,MAAM;;;;WACN,kBAAkB,EAAE;;;;;;eAMpB,MAAM;;;;;;UAmFN,MAAM;;;;aACN,MAAM;;;;WACN,kBAAkB,EAAE;;;;;;QA0CpB,MAAM"}

package/lib/api-endpoints/family-library-groups.test.js

@@ -2,7 +2,7 @@ import test from 'node:test'
 import assert from 'node:assert'
 import { getGroups, createGroup, getGroup, updateGroup, deleteGroup } from './family-library-groups.js'
 import { YotoAPIError } from './helpers.js'
-import { loadTestTokens, logResponse } from './test-helpers.js'
+import { loadTestTokens, logResponse } from './endpoint-test-helpers.js'
 
 const { accessToken } = loadTestTokens()