yoto-nodejs-client 0.0.1 → 0.0.2

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/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/api-endpoints/test-helpers.d.ts

@@ -1,7 +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=test-helpers.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["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"}