yoto-nodejs-client 0.0.1 → 0.0.3

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

@@ -1,3 +1,23 @@
+/**
+ * @see https://yoto.dev/api/getfamilyimages/
+ * @typedef {Object} YotoFamilyImagesResponse
+ * @property {YotoFamilyImage[]} images
+ */
+/**
+ * @see https://yoto.dev/api/getfamilyimages/
+ * @typedef {Object} YotoFamilyImage
+ * @property {string} imageId - The unique identifier for the family image (hash)
+ * @property {string} [name] - Optional name of the family image
+ */
+/**
+ * Retrieves the list of families associated with the authenticated user.
+ * @see https://yoto.dev/api/getfamilyimages/
+ * @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<YotoFamilyImagesResponse>} The user's families
+ */
 export function getFamilyImages({ accessToken, userAgent, requestOptions }: {
     accessToken: string;
     userAgent?: string | undefined;
@@ -5,6 +25,23 @@ export function getFamilyImages({ 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<YotoFamilyImagesResponse>;
+/**
+ * @see https://yoto.dev/api/getafamilyimage/
+ * @typedef {Object} YotoFamilyImageResponse
+ * @property {string} imageUrl - The signed URL to the family image (expires after 7 days)
+ */
+/**
+ * Retrieves a signed URL for a specific family image. Returns a 302 redirect with the image URL in the Location header.
+ * The signed URL expires after 7 days.
+ * @see https://yoto.dev/api/getafamilyimage/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {string} options.imageId The family image ID (hash) to get the image for
+ * @param  {'640x480' | '320x320'} options.size Image dimensions (supported: '640x480' or '320x320')
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoFamilyImageResponse>} The signed image URL
+ */
 export function getAFamilyImage({ accessToken, userAgent, imageId, size, requestOptions }: {
     accessToken: string;
     imageId: string;
@@ -14,6 +51,42 @@ export function getAFamilyImage({ accessToken, userAgent, imageId, size, request
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoFamilyImageResponse>;
+/**
+ * @see https://yoto.dev/api/uploadafamilyimage/
+ * @typedef {Object} YotoUploadFamilyImageResponse
+ * @property {string} imageId - The SHA256 checksum of the uploaded image
+ * @property {string} url - URL to the 'get a family image' endpoint (requires width/height params)
+ */
+/**
+ * Uploads a family image for use across various features in Yoto.
+ * Images are deduplicated using SHA256 checksums.
+ *
+ * Constraints:
+ * - Max size: 8mb
+ * - Supported formats: JPEG, GIF, PNG
+ * - Limit: 500 images per family
+ * - No restrictions on resolution or aspect ratio
+ *
+ * @see https://yoto.dev/api/uploadafamilyimage/
+ * @param  {object} options
+ * @param  {string} options.accessToken    The API token to request with
+ * @param  {Buffer} options.imageData The binary image data (JPEG, GIF, or PNG)
+ * @param  {string} [options.userAgent]  Optional user agent string
+ * @param  {RequestOptions} [options.requestOptions]  Additional undici request options
+ * @return {Promise<YotoUploadFamilyImageResponse>} The uploaded image details
+ * @example
+ * import { readFile } from 'fs/promises'
+ * import { uploadAFamilyImage } from 'yoto-nodejs-client'
+ *
+ * const imageData = await readFile('./family-photo.jpg')
+ * const result = await uploadAFamilyImage({
+ *   accessToken,
+ *   imageData
+ * })
+ *
+ * console.log('Image ID:', result.imageId)
+ * console.log('Image URL:', result.url)
+ */
 export function uploadAFamilyImage({ accessToken, userAgent, imageData, requestOptions }: {
     accessToken: string;
     imageData: Buffer;
@@ -26,14 +99,29 @@ export type YotoFamilyImagesResponse = {
     images: YotoFamilyImage[];
 };
 export type YotoFamilyImage = {
+    /**
+     * - The unique identifier for the family image (hash)
+     */
     imageId: string;
+    /**
+     * - Optional name of the family image
+     */
     name?: string;
 };
 export type YotoFamilyImageResponse = {
+    /**
+     * - The signed URL to the family image (expires after 7 days)
+     */
     imageUrl: string;
 };
 export type YotoUploadFamilyImageResponse = {
+    /**
+     * - The SHA256 checksum of the uploaded image
+     */
     imageId: string;
+    /**
+     * - URL to the 'get a family image' endpoint (requires width/height params)
+     */
     url: string;
 };
 //# sourceMappingURL=family.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"family.d.ts","sourceRoot":"","sources":["family.js"],"names":[],"mappings":"AAiCA,4EALG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,wBAAwB,CAAC,CAkB5C;AAoBD,2FAPG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACyB,IAAI,EAAnC,SAAS,GAAG,SAAS;IACJ,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CAsC3C;AAuCD,0FAlBG;IAAyB,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,6BAA6B,CAAC,CAmCjD;;YAvJa,eAAe,EAAE;;;aAMjB,MAAM;WACN,MAAM;;;cAiCN,MAAM;;;aAwDN,MAAM;SACN,MAAM"}
+{"version":3,"file":"family.d.ts","sourceRoot":"","sources":["family.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,4EALG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,wBAAwB,CAAC,CAkB5C;AAED;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,2FAPG;IAAyB,WAAW,EAA3B,MAAM;IACU,OAAO,EAAvB,MAAM;IACyB,IAAI,EAAnC,SAAS,GAAG,SAAS;IACJ,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CAsC3C;AAED;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,0FAlBG;IAAyB,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,6BAA6B,CAAC,CAmCjD;;YAvJa,eAAe,EAAE;;;;;;aAMjB,MAAM;;;;WACN,MAAM;;;;;;cAiCN,MAAM;;;;;;aAwDN,MAAM;;;;SACN,MAAM"}

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

@@ -2,7 +2,7 @@ import test from 'node:test'
 import assert from 'node:assert'
 import { getFamilyImages, getAFamilyImage } from './family.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/helpers.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Request options derived from undici.request
+ * @typedef {NonNullable<Parameters<typeof request>[1]>} RequestOptions
+ */
+/**
+ * @param {object} [options]
+ * @param {string} [options.userAgent] - Optional user agent string to prepend to library user agent
+ * @param {RequestOptions} [options.requestOptions] - Additional undici request options
+ */
 export function defaultHeaders(options?: {
     userAgent?: string | undefined;
     requestOptions?: ({
@@ -7,6 +16,11 @@ export function defaultHeaders(options?: {
     Accept: string;
     'User-Agent': string;
 };
+/**
+ * @param  {object} params
+ * @param  {string} params.accessToken
+ * @param {string} [params.userAgent] - Optional user agent string to prepend to library user agent
+ */
 export function defaultAuthHeaders({ accessToken: token, userAgent }: {
     accessToken: string;
     userAgent?: string | undefined;
@@ -15,14 +29,34 @@ export function defaultAuthHeaders({ accessToken: token, userAgent }: {
     Accept: string;
     'User-Agent': string;
 };
+/**
+ * Merge undici request options with defaults
+ * Properly merges headers by supplementing rather than overriding
+ * Only supports object headers (not arrays)
+ * @param {RequestOptions} baseOptions - Base request options with headers
+ * @param {RequestOptions} [requestOptions] - Additional request options to merge
+ * @returns {object} Merged options
+ */
 export function mergeRequestOptions(baseOptions: RequestOptions, requestOptions?: RequestOptions): object;
+/**
+ * @param  {Dispatcher.ResponseData} response
+ * @param  {any} [extra]
+ */
 export function handleBadResponse(response: Dispatcher.ResponseData, extra?: any): Promise<void>;
 export class YotoAPIError extends Error {
+    /**
+     * @param  {Dispatcher.ResponseData} response A undici Response
+     * @param  {string | object} body response body
+     * @param  {any} [extra] any extra info to attach to the error
+     */
     constructor(response: Dispatcher.ResponseData, body: string | object, extra?: any);
-    statusCode: number;
-    body: string | object;
-    extra: any;
+    /** @type { number } */ statusCode: number;
+    /** @type {string | object } */ body: string | object;
+    /** @type {any} */ extra: any;
 }
+/**
+ * Request options derived from undici.request
+ */
 export type RequestOptions = NonNullable<Parameters<typeof request>[1]>;
 import type { Dispatcher } from 'undici';
 import type { request } from 'undici';

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["helpers.js"],"names":[],"mappings":"AAiBA,yCAHG;IAAyB,SAAS;IACD,cAAc;;;CACjD;;;EAWA;AAOD,sEAHG;IAAwB,WAAW,EAA1B,MAAM;IACS,SAAS;CACnC;;;;EAMA;AAUD,iDAJW,cAAc,mBACd,cAAc,GACZ,MAAM,CAoBlB;AAMD,4CAHY,uBAAuB,UACvB,GAAG,iBAWd;AAED;IAUE,sBAJY,uBAAuB,QACvB,MAAM,GAAG,MAAM,UACf,GAAG,EAUd;IAjBuB,YAAZ,MAAM,CAAgB;IACF,MAArB,MAAM,GAAG,MAAM,CAAU;IACjB,OAAR,GAAG,CAAU;CAgBzB;6BA9FY,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;gCARxB,QAAQ;6BACX,QAAQ"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["helpers.js"],"names":[],"mappings":"AAOA;;;GAGG;AAEH;;;;GAIG;AACH,yCAHG;IAAyB,SAAS;IACD,cAAc;;;CACjD;;;EAWA;AAED;;;;GAIG;AACH,sEAHG;IAAwB,WAAW,EAA1B,MAAM;IACS,SAAS;CACnC;;;;EAMA;AAED;;;;;;;GAOG;AACH,iDAJW,cAAc,mBACd,cAAc,GACZ,MAAM,CAoBlB;AAED;;;GAGG;AACH,4CAHY,uBAAuB,UACvB,GAAG,iBAWd;AAED;IAKE;;;;OAIG;IACH,sBAJY,uBAAuB,QACvB,MAAM,GAAG,MAAM,UACf,GAAG,EAUd;IAjBD,uBAAuB,CAAC,YAAZ,MAAM,CAAgB;IAClC,+BAA+B,CAAC,MAArB,MAAM,GAAG,MAAM,CAAU;IACpC,kBAAkB,CAAC,OAAR,GAAG,CAAU;CAgBzB;;;;6BA9FY,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;gCARxB,QAAQ;6BACX,QAAQ"}

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

@@ -1,3 +1,41 @@
+/**
+ * @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 function getPublicIcons({ accessToken, userAgent, requestOptions }: {
     accessToken: string;
     userAgent?: string | undefined;
@@ -5,6 +43,30 @@ export function getPublicIcons({ 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<YotoPublicIconsResponse>;
+/**
+ * @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 function getUserIcons({ accessToken, userAgent, requestOptions }: {
     accessToken: string;
     userAgent?: string | undefined;
@@ -12,6 +74,65 @@ export function getUserIcons({ 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<YotoUserIconsResponse>;
+/**
+ * @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 function uploadIcon({ accessToken, userAgent, imageData, autoConvert, filename, requestOptions }: {
     accessToken: string;
     imageData: Buffer;
@@ -23,40 +144,115 @@ export function uploadIcon({ accessToken, userAgent, imageData, autoConvert, fil
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoUploadIconResponse>;
 export type YotoPublicIconsResponse = {
+    /**
+     * - Array of public display icons
+     */
     displayIcons: YotoPublicIcon[];
 };
 export type YotoPublicIcon = {
+    /**
+     * - Unique identifier for the icon
+     */
     displayIconId: string;
+    /**
+     * - Unique identifier for the underlying icon file
+     */
     mediaId: string;
+    /**
+     * - ID of the user who uploaded this icon (always "yoto" for public icons)
+     */
     userId: string;
+    /**
+     * - ISO 8601 timestamp when icon record was created
+     */
     createdAt: string;
+    /**
+     * - Title of the display icon
+     */
     title: string;
+    /**
+     * - URL of the display icon
+     */
     url: string;
+    /**
+     * - Indicates if the icon is public (always true for public icons)
+     */
     public: boolean;
+    /**
+     * - Indicates if this is a new icon (may not always be present)
+     */
     new?: boolean;
+    /**
+     * - Public tags associated with the display icon
+     */
     publicTags: string[];
 };
 export type YotoUserIconsResponse = {
+    /**
+     * - Array of user's custom display icons
+     */
     displayIcons: YotoUserIcon[];
 };
 export type YotoUserIcon = {
+    /**
+     * - Unique identifier for the icon
+     */
     displayIconId: string;
+    /**
+     * - Unique identifier for the underlying icon file
+     */
     mediaId: string;
+    /**
+     * - ID of the user who uploaded this icon
+     */
     userId: string;
+    /**
+     * - ISO 8601 timestamp when icon record was created
+     */
     createdAt: string;
+    /**
+     * - URL of the display icon
+     */
     url: string;
+    /**
+     * - Indicates if the icon is public (always false for user icons)
+     */
     public: boolean;
 };
 export type YotoUploadIconResponse = {
+    /**
+     * - The uploaded or existing display icon
+     */
     displayIcon: YotoDisplayIcon;
 };
 export type YotoDisplayIcon = {
+    /**
+     * - Unique identifier for the icon
+     */
     displayIconId: string;
+    /**
+     * - Unique identifier for the underlying icon file
+     */
     mediaId: string;
+    /**
+     * - ID of the user who uploaded this icon
+     */
     userId: string;
+    /**
+     * - URL of the display icon, or empty object {} for duplicates
+     */
     url: string | object;
+    /**
+     * - True if this is a new upload, undefined for duplicates
+     */
     new?: boolean;
+    /**
+     * - MongoDB ID (present for duplicate uploads)
+     */
     _id?: string;
+    /**
+     * - ISO 8601 timestamp (present for duplicate uploads)
+     */
     createdAt?: string;
 };
 //# sourceMappingURL=icons.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["icons.js"],"names":[],"mappings":"AAmDA,2EAhBG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CA6B3C;AA4BD,yEALG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,qBAAqB,CAAC,CAkBzC;AA+DD,yGAzBG;IAAyB,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACY,WAAW;IACZ,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,sBAAsB,CAAC,CA6C1C;;kBA1La,cAAc,EAAE;;;mBAMhB,MAAM;aACN,MAAM;YACN,MAAM;eACN,MAAM;WACN,MAAM;SACN,MAAM;YACN,OAAO;UACP,OAAO;gBACP,MAAM,EAAE;;;kBA4CR,YAAY,EAAE;;;mBAMd,MAAM;aACN,MAAM;YACN,MAAM;eACN,MAAM;SACN,MAAM;YACN,OAAO;;;iBAiCP,eAAe;;;mBAMf,MAAM;aACN,MAAM;YACN,MAAM;SACN,MAAM,GAAG,MAAM;UACf,OAAO;UACP,MAAM;gBACN,MAAM"}
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["icons.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2EAhBG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,uBAAuB,CAAC,CA6B3C;AAED;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,yEALG;IAAyB,WAAW,EAA3B,MAAM;IACW,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,qBAAqB,CAAC,CAkBzC;AAED;;;;GAIG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,yGAzBG;IAAyB,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACY,WAAW;IACZ,QAAQ;IACR,SAAS;IACD,cAAc;;;CAChD,GAAS,OAAO,CAAC,sBAAsB,CAAC,CA6C1C;;;;;kBA1La,cAAc,EAAE;;;;;;mBAMhB,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;eACN,MAAM;;;;WACN,MAAM;;;;SACN,MAAM;;;;YACN,OAAO;;;;UACP,OAAO;;;;gBACP,MAAM,EAAE;;;;;;kBA4CR,YAAY,EAAE;;;;;;mBAMd,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;eACN,MAAM;;;;SACN,MAAM;;;;YACN,OAAO;;;;;;iBAiCP,eAAe;;;;;;mBAMf,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;SACN,MAAM,GAAG,MAAM;;;;UACf,OAAO;;;;UACP,MAAM;;;;gBACN,MAAM"}

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

@@ -2,7 +2,7 @@ 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'
+import { loadTestTokens, logResponse } from './endpoint-test-helpers.js'
 
 const { accessToken } = loadTestTokens()
 

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

@@ -1,3 +1,47 @@
+/**
+ * @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 function getAudioUploadUrl({ accessToken, userAgent, sha256, filename, requestOptions }: {
     accessToken: string;
     sha256: string;
@@ -7,6 +51,33 @@ export function getAudioUploadUrl({ accessToken, userAgent, sha256, filename, re
         dispatcher?: import("undici").Dispatcher;
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoAudioUploadUrlResponse>;
+/**
+ * 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 function uploadCoverImage({ accessToken, userAgent, imageData, imageUrl, autoConvert, coverType, filename, requestOptions }: {
     accessToken: string;
     imageData?: string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | undefined;
@@ -20,14 +91,26 @@ export function uploadCoverImage({ accessToken, userAgent, imageData, imageUrl,
     } & Omit<import("undici").Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<import("undici").Dispatcher.RequestOptions<null>, "method">>) | undefined;
 }): Promise<YotoUploadCoverImageResponse>;
 export type YotoAudioUpload = {
+    /**
+     * - Upload identifier
+     */
     uploadId: string;
+    /**
+     * - Signed upload URL, or null if file already exists
+     */
     uploadUrl: string | null;
 };
 export type YotoAudioUploadUrlResponse = {
     upload: YotoAudioUpload;
 };
 export type YotoCoverImage = {
+    /**
+     * - Media identifier
+     */
     mediaId: string;
+    /**
+     * - URL to access the uploaded cover image
+     */
     mediaUrl: string;
 };
 export type YotoUploadCoverImageResponse = {

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

@@ -1 +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"}
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["media.js"],"names":[],"mappings":"AAkBA;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,gGAPG;IAAwB,WAAW,EAA3B,MAAM;IACU,MAAM,EAAtB,MAAM;IACW,QAAQ;IACR,SAAS;IACD,cAAc;;;CAC/C,GAAU,OAAO,CAAC,0BAA0B,CAAC,CAuB/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,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/helpers/power-state.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Power state detection helper for Yoto device status
+ *
+ * Analyzes shutdown field and uptime to determine device power state changes
+ */
+/**
+ * Power state detection result
+ * @typedef {Object} PowerStateResult
+ * @property {'running' | 'shutdown' | 'startup'} state - Device power state
+ * @property {string | null} shutDownReason - Shutdown reason if state is 'shutdown'
+ * @property {number | null} upTime - Device uptime in seconds if state is 'startup'
+ */
+/**
+ * Detect device power state from legacy status
+ *
+ * @param {string | null | undefined} shutDown - shutDown field from legacy status
+ * @param {number | null | undefined} upTime - upTime field from legacy status in seconds
+ * @returns {PowerStateResult}
+ *
+ * @example
+ * // Device running normally
+ * detectPowerState('nA', 3600)
+ * // { state: 'running', shutDownReason: null, upTime: null }
+ *
+ * @example
+ * // Device just started (low uptime)
+ * detectPowerState('nA', 45)
+ * // { state: 'startup', shutDownReason: null, upTime: 45 }
+ *
+ * @example
+ * // Device shutting down
+ * detectPowerState('userShutdown', 3600)
+ * // { state: 'shutdown', shutDownReason: 'userShutdown', upTime: null }
+ */
+export function detectPowerState(shutDown: string | null | undefined, upTime: number | null | undefined): PowerStateResult;
+/**
+ * Power state detection result
+ */
+export type PowerStateResult = {
+    /**
+     * - Device power state
+     */
+    state: "running" | "shutdown" | "startup";
+    /**
+     * - Shutdown reason if state is 'shutdown'
+     */
+    shutDownReason: string | null;
+    /**
+     * - Device uptime in seconds if state is 'startup'
+     */
+    upTime: number | null;
+};
+//# sourceMappingURL=power-state.d.ts.map

package/lib/helpers/power-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"power-state.d.ts","sourceRoot":"","sources":["power-state.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,2CAnBW,MAAM,GAAG,IAAI,GAAG,SAAS,UACzB,MAAM,GAAG,IAAI,GAAG,SAAS,GACvB,gBAAgB,CAqD5B;;;;;;;;WA/Da,SAAS,GAAG,UAAU,GAAG,SAAS;;;;oBAClC,MAAM,GAAG,IAAI;;;;YACb,MAAM,GAAG,IAAI"}