yoto-nodejs-client 0.0.1

package/lib/api-endpoints/family.js

@@ -0,0 +1,166 @@
+/**
+ * @import { RequestOptions } from './helpers.js'
+ */
+import { request } from 'undici'
+import { defaultAuthHeaders, handleBadResponse, mergeRequestOptions } from './helpers.js'
+import { YOTO_API_URL } from './constants.js'
+
+// ============================================================================
+// Family: Family endpoints for managing family groups and images
+// ============================================================================
+
+/**
+ * @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 async function getFamilyImages ({
+  accessToken,
+  userAgent,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/family/images', YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoFamilyImagesResponse} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @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 async function getAFamilyImage ({
+  accessToken,
+  userAgent,
+  imageId,
+  size,
+  requestOptions
+}) {
+  const requestUrl = new URL(`/media/family/images/${imageId}`, YOTO_API_URL)
+
+  // Map size string to width and height
+  const dimensions = size === '640x480' ? { width: 640, height: 480 } : { width: 320, height: 320 }
+
+  requestUrl.searchParams.set('width', dimensions.width.toString())
+  requestUrl.searchParams.set('height', dimensions.height.toString())
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  // 302 is expected for successful image requests
+  if (response.statusCode !== 302) {
+    await handleBadResponse(response, { imageId })
+  }
+
+  // Get the signed URL from the Location header
+  const locationHeaders = response.headers['location']
+  const imageUrl = Array.isArray(locationHeaders) ? locationHeaders[0] : locationHeaders
+
+  if (!imageUrl) {
+    throw new Error('No Location header found in 302 response')
+  }
+
+  return {
+    imageUrl
+  }
+}
+
+/**
+ * @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 async function uploadAFamilyImage ({
+  accessToken,
+  userAgent,
+  imageData,
+  requestOptions
+}) {
+  const requestUrl = new URL('/media/family/images', YOTO_API_URL)
+
+  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 {YotoUploadFamilyImageResponse} */ (await response.body.json())
+  return responseBody
+}

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

@@ -0,0 +1,184 @@
+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'
+
+const { accessToken } = loadTestTokens()
+
+test('getFamilyImages', async (t) => {
+  await t.test('should fetch user family images', async () => {
+    const response = await getFamilyImages({
+      accessToken
+    })
+
+    // Log response for type verification and documentation
+    logResponse('GET /media/family/images', response)
+
+    // Validate response structure matches YotoFamilyImagesResponse
+    assert.ok(response, 'Response should exist')
+    assert.ok(Array.isArray(response.images), 'Response should have images array')
+
+    // Note: User may not have any family images, so we only validate structure if images exist
+    if (response.images.length > 0) {
+      const image = response.images[0]
+      assert.ok(image, 'Image should exist')
+      assert.ok(typeof image.imageId === 'string', 'Image should have imageId string')
+    }
+  })
+
+  await t.test('should fail with invalid token', async () => {
+    await assert.rejects(
+      async () => {
+        await getFamilyImages({
+          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('getAFamilyImage', async (t) => {
+  /** @type {string[]} */
+  let testImageIds = []
+
+  // Get real image IDs to test with
+  await t.test('setup - get image IDs from family images', async () => {
+    const response = await getFamilyImages({
+      accessToken
+    })
+
+    if (response.images.length === 0) {
+      console.log('⚠️  User has no family images - getAFamilyImage tests will be skipped')
+      return
+    }
+
+    testImageIds = response.images.slice(0, 2).map(image => image.imageId).filter(Boolean)
+    assert.ok(testImageIds.length > 0, 'Should have extracted at least one image ID')
+  })
+
+  await t.test('should fetch family image signed URL', async () => {
+    if (testImageIds.length === 0) {
+      console.log('⚠️  Skipping - no family images available')
+      return
+    }
+
+    const imageId = testImageIds[0]
+    assert.ok(imageId, 'Image ID should exist')
+
+    const response = await getAFamilyImage({
+      accessToken,
+      imageId,
+      size: '640x480'
+    })
+
+    // Log response for type verification and documentation
+    logResponse('GET /media/family/images/{imageId}', response)
+
+    // Validate response structure matches YotoFamilyImageResponse
+    assert.ok(response, 'Response should exist')
+    assert.ok(typeof response.imageUrl === 'string', 'Response should have imageUrl string')
+    assert.ok(response.imageUrl.startsWith('http'), 'Image URL should be a valid URL')
+  })
+
+  await t.test('should fetch family image with size 640x480', async () => {
+    if (testImageIds.length === 0) {
+      console.log('⚠️  Skipping - no family images available')
+      return
+    }
+
+    const imageId = testImageIds[0]
+    assert.ok(imageId, 'Image ID should exist')
+
+    const response = await getAFamilyImage({
+      accessToken,
+      imageId,
+      size: '640x480'
+    })
+
+    assert.ok(response, 'Response should exist')
+    assert.ok(typeof response.imageUrl === 'string', 'Response should have imageUrl string')
+    assert.ok(response.imageUrl.startsWith('http'), 'Image URL should be a valid URL')
+  })
+
+  await t.test('should fetch family image with size 320x320', async () => {
+    if (testImageIds.length === 0) {
+      console.log('⚠️  Skipping - no family images available')
+      return
+    }
+
+    const imageId = testImageIds[0]
+    assert.ok(imageId, 'Image ID should exist')
+
+    const response = await getAFamilyImage({
+      accessToken,
+      imageId,
+      size: '320x320'
+    })
+
+    assert.ok(response, 'Response should exist')
+    assert.ok(typeof response.imageUrl === 'string', 'Response should have imageUrl string')
+    assert.ok(response.imageUrl.startsWith('http'), 'Image URL should be a valid URL')
+  })
+
+  await t.test('should fail with invalid image ID', async () => {
+    await assert.rejects(
+      async () => {
+        await getAFamilyImage({
+          accessToken,
+          imageId: 'invalid-image-id-12345',
+          size: '640x480'
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        assert.ok(err.statusCode === 404 || err.statusCode === 400, 'Should return 404 or 400 for invalid image ID')
+        return true
+      }
+    )
+  })
+
+  await t.test('should fail with invalid token', async () => {
+    if (testImageIds.length === 0) {
+      console.log('⚠️  Skipping - no family images available')
+      return
+    }
+
+    const imageId = testImageIds[0]
+    assert.ok(imageId, 'Image ID should exist')
+
+    await assert.rejects(
+      async () => {
+        await getAFamilyImage({
+          accessToken: 'invalid-token',
+          imageId,
+          size: '640x480'
+        })
+      },
+      (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 uploadAFamilyImage
+// - should upload a valid JPEG image
+// - should upload a valid PNG image
+// - should upload a valid GIF image
+// - should return imageId (SHA256 checksum) and url
+// - should deduplicate identical images (same SHA256)
+// - should fail with file larger than 8mb
+// - should fail with unsupported image format
+// - should fail when family has reached 500 image limit
+// - should fail with invalid token
+// - should validate response structure matches YotoUploadFamilyImageResponse

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

@@ -0,0 +1,29 @@
+export function defaultHeaders(options?: {
+    userAgent?: string | undefined;
+    requestOptions?: ({
+        dispatcher?: Dispatcher;
+    } & Omit<Dispatcher.RequestOptions<unknown>, "origin" | "path" | "method"> & Partial<Pick<Dispatcher.RequestOptions<null>, "method">>) | undefined;
+}): {
+    Accept: string;
+    'User-Agent': string;
+};
+export function defaultAuthHeaders({ accessToken: token, userAgent }: {
+    accessToken: string;
+    userAgent?: string | undefined;
+}): {
+    Authorization: string;
+    Accept: string;
+    'User-Agent': string;
+};
+export function mergeRequestOptions(baseOptions: RequestOptions, requestOptions?: RequestOptions): object;
+export function handleBadResponse(response: Dispatcher.ResponseData, extra?: any): Promise<void>;
+export class YotoAPIError extends Error {
+    constructor(response: Dispatcher.ResponseData, body: string | object, extra?: any);
+    statusCode: number;
+    body: string | object;
+    extra: any;
+}
+export type RequestOptions = NonNullable<Parameters<typeof request>[1]>;
+import type { Dispatcher } from 'undici';
+import type { request } from 'undici';
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +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"}

package/lib/api-endpoints/helpers.js

@@ -0,0 +1,104 @@
+/**
+ * @import { Dispatcher } from 'undici'
+ * @import { request } from 'undici'
+ */
+import { pkg } from '../pkg.cjs'
+import os from 'node:os'
+
+/**
+ * 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 = {}) {
+  const libraryAgent = `${pkg.name}/${pkg.version} (${os.type()})`
+  const userAgent = options.userAgent
+    ? `${options.userAgent} ${libraryAgent}`
+    : libraryAgent
+
+  return {
+    Accept: 'application/json',
+    'User-Agent': userAgent
+  }
+}
+
+/**
+ * @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 }) {
+  return {
+    ...defaultHeaders({ userAgent }),
+    Authorization: `Bearer ${token}`,
+  }
+}
+
+/**
+ * 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) {
+  if (!requestOptions) return baseOptions
+
+  // Extract headers from both options
+  const { headers: baseHeaders, ...baseRest } = baseOptions
+  const { headers: requestHeaders, ...requestRest } = requestOptions
+
+  // Merge headers - only support object headers
+  const mergedHeaders = {
+    ...(baseHeaders || {}),
+    ...(requestHeaders || {})
+  }
+
+  return {
+    ...baseRest,
+    ...requestRest,
+    headers: mergedHeaders
+  }
+}
+
+/**
+ * @param  {Dispatcher.ResponseData} response
+ * @param  {any} [extra]
+ */
+export async function handleBadResponse (response, extra) {
+  if (response.statusCode > 299) {
+    const contentTypeHeaders = response.headers['Content-Type']
+    const contentType = Array.isArray(contentTypeHeaders) ? contentTypeHeaders[0] : contentTypeHeaders
+    const isJSON = contentType && contentType.match(/json/)
+    /** @type { any } */
+    const body = isJSON ? await response.body.json() : await response.body.text()
+    throw new YotoAPIError(response, body, extra)
+  }
+}
+
+export class YotoAPIError extends Error {
+  /** @type { number } */ statusCode
+  /** @type {string | object } */ body
+  /** @type {any} */ extra
+
+  /**
+   * @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, body, extra) {
+    super('Unexpected response status code')
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+
+    this.statusCode = response.statusCode
+    this.body = body
+    this.extra = extra
+  }
+}

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

@@ -0,0 +1,62 @@
+export function getPublicIcons({ accessToken, userAgent, requestOptions }: {
+    accessToken: string;
+    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<YotoPublicIconsResponse>;
+export function getUserIcons({ accessToken, userAgent, requestOptions }: {
+    accessToken: string;
+    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<YotoUserIconsResponse>;
+export function uploadIcon({ accessToken, userAgent, imageData, autoConvert, filename, requestOptions }: {
+    accessToken: string;
+    imageData: Buffer;
+    autoConvert?: boolean | 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<YotoUploadIconResponse>;
+export type YotoPublicIconsResponse = {
+    displayIcons: YotoPublicIcon[];
+};
+export type YotoPublicIcon = {
+    displayIconId: string;
+    mediaId: string;
+    userId: string;
+    createdAt: string;
+    title: string;
+    url: string;
+    public: boolean;
+    new?: boolean;
+    publicTags: string[];
+};
+export type YotoUserIconsResponse = {
+    displayIcons: YotoUserIcon[];
+};
+export type YotoUserIcon = {
+    displayIconId: string;
+    mediaId: string;
+    userId: string;
+    createdAt: string;
+    url: string;
+    public: boolean;
+};
+export type YotoUploadIconResponse = {
+    displayIcon: YotoDisplayIcon;
+};
+export type YotoDisplayIcon = {
+    displayIconId: string;
+    mediaId: string;
+    userId: string;
+    url: string | object;
+    new?: boolean;
+    _id?: string;
+    createdAt?: string;
+};
+//# sourceMappingURL=icons.d.ts.map

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

@@ -0,0 +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"}