yoto-nodejs-client 0.0.1

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

@@ -0,0 +1,247 @@
+/**
+ * @import { RequestOptions } from './helpers.js'
+ */
+import { request } from 'undici'
+import { defaultAuthHeaders, handleBadResponse, mergeRequestOptions } from './helpers.js'
+import { YOTO_API_URL } from './constants.js'
+
+// ============================================================================
+// Family Library Groups: Endpoints for managing family library card groups
+// ============================================================================
+
+/**
+ * @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 async function getGroups ({
+  accessToken,
+  userAgent,
+  requestOptions
+}) {
+  const requestUrl = new URL('/card/family/library/groups', YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoGroup[]} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @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 async function createGroup ({
+  token,
+  userAgent,
+  group,
+  requestOptions
+}) {
+  const requestUrl = new URL('/card/family/library/groups', YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'POST',
+    headers: {
+      ...defaultAuthHeaders({ accessToken: token, userAgent }),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(group)
+  }, requestOptions))
+
+  await handleBadResponse(response)
+
+  const responseBody = /** @type {YotoGroup} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * 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 async function getGroup ({
+  accessToken,
+  userAgent,
+  groupId,
+  requestOptions
+}) {
+  const requestUrl = new URL(`/card/family/library/groups/${groupId}`, YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'GET',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response, { groupId })
+
+  const responseBody = /** @type {YotoGroup} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @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 async function updateGroup ({
+  accessToken,
+  userAgent,
+  groupId,
+  group,
+  requestOptions
+}) {
+  const requestUrl = new URL(`/card/family/library/groups/${groupId}`, YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'PUT',
+    headers: {
+      ...defaultAuthHeaders({ accessToken, userAgent }),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(group)
+  }, requestOptions))
+
+  await handleBadResponse(response, { groupId })
+
+  const responseBody = /** @type {YotoGroup} */ (await response.body.json())
+  return responseBody
+}
+
+/**
+ * @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 async function deleteGroup ({
+  accessToken,
+  userAgent,
+  groupId,
+  requestOptions
+}) {
+  const requestUrl = new URL(`/card/family/library/groups/${groupId}`, YOTO_API_URL)
+
+  const response = await request(requestUrl, mergeRequestOptions({
+    method: 'DELETE',
+    headers: defaultAuthHeaders({ accessToken, userAgent })
+  }, requestOptions))
+
+  await handleBadResponse(response, { groupId })
+
+  const responseBody = /** @type {YotoDeleteGroupResponse} */ (await response.body.json())
+  return responseBody
+}

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

@@ -0,0 +1,272 @@
+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'
+
+const { accessToken } = loadTestTokens()
+
+test('getGroups', async (t) => {
+  await t.test('should fetch family library groups', async () => {
+    const response = await getGroups({
+      accessToken
+    })
+
+    // Log response for type verification and documentation
+    logResponse('GET /card/family/library/groups', response)
+
+    // Validate response structure matches YotoGroup[]
+    assert.ok(response, 'Response should exist')
+    assert.ok(Array.isArray(response), 'Response should be an array')
+
+    // Note: User may not have any groups, so we only validate structure if groups exist
+    if (response.length > 0) {
+      const group = response[0]
+      assert.ok(group, 'Group should exist')
+      assert.ok(typeof group.id === 'string', 'Group should have id string')
+      assert.ok(typeof group.name === 'string', 'Group should have name string')
+      assert.ok(typeof group.familyId === 'string', 'Group should have familyId string')
+      assert.ok(typeof group.imageId === 'string', 'Group should have imageId string')
+      assert.ok(typeof group.imageUrl === 'string', 'Group should have imageUrl string')
+      assert.ok(Array.isArray(group.items), 'Group should have items array')
+      assert.ok(Array.isArray(group.cards), 'Group should have cards array')
+      assert.ok(typeof group.createdAt === 'string', 'Group should have createdAt string')
+      assert.ok(typeof group.lastModifiedAt === 'string', 'Group should have lastModifiedAt string')
+
+      // Validate items structure if items exist
+      if (group.items.length > 0) {
+        const item = group.items[0]
+        assert.ok(item, 'Item should exist')
+        assert.ok(typeof item.contentId === 'string', 'Item should have contentId string')
+        assert.ok(typeof item.addedAt === 'string', 'Item should have addedAt string')
+      }
+    }
+  })
+
+  await t.test('should fail with invalid token', async () => {
+    await assert.rejects(
+      async () => {
+        await getGroups({
+          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('CRUD operations - full lifecycle', async (t) => {
+  /** @type {string[]} */
+  let createdGroupIds = []
+  /** @type {string} */
+  let group1Id
+  /** @type {string} */
+  let group2Id
+
+  // Cleanup function to run after all tests
+  t.after(async () => {
+    console.log('\n🧹 Cleaning up test groups...')
+    for (const groupId of createdGroupIds) {
+      try {
+        await deleteGroup({ accessToken, groupId })
+        console.log(`  ✓ Deleted group: ${groupId}`)
+      } catch (err) {
+        console.log(`  ⚠️  Failed to delete group ${groupId}:`, /** @type {Error} */(err).message)
+      }
+    }
+  })
+
+  await t.test('should create first group', async () => {
+    const group = await createGroup({
+      token: accessToken,
+      group: {
+        name: 'Test Group 1',
+        imageId: 'fp-cards',
+        items: []
+      }
+    })
+
+    logResponse('POST /card/family/library/groups (group 1)', group)
+
+    // Validate response structure
+    assert.ok(group, 'Response should exist')
+    assert.ok(typeof group.id === 'string', 'Group should have id string')
+    assert.strictEqual(group.name, 'Test Group 1', 'Group name should match')
+    assert.strictEqual(group.imageId, 'fp-cards', 'Image ID should match')
+    assert.ok(Array.isArray(group.items), 'Group should have items array')
+    assert.strictEqual(group.items.length, 0, 'Items should be empty')
+    assert.ok(Array.isArray(group.cards), 'Group should have cards array')
+    assert.ok(typeof group.familyId === 'string', 'Group should have familyId')
+    assert.ok(typeof group.createdAt === 'string', 'Group should have createdAt')
+    assert.ok(typeof group.lastModifiedAt === 'string', 'Group should have lastModifiedAt')
+
+    group1Id = group.id
+    createdGroupIds.push(group.id)
+  })
+
+  await t.test('should create second group', async () => {
+    const group = await createGroup({
+      token: accessToken,
+      group: {
+        name: 'Test Group 2',
+        imageId: 'fp-cards',
+        items: []
+      }
+    })
+
+    logResponse('POST /card/family/library/groups (group 2)', group)
+
+    // Validate response structure
+    assert.ok(group, 'Response should exist')
+    assert.ok(typeof group.id === 'string', 'Group should have id string')
+    assert.strictEqual(group.name, 'Test Group 2', 'Group name should match')
+    assert.notStrictEqual(group.id, group1Id, 'Group IDs should be different')
+
+    group2Id = group.id
+    createdGroupIds.push(group.id)
+  })
+
+  await t.test('should list groups and find both created groups', async () => {
+    const groups = await getGroups({
+      accessToken
+    })
+
+    logResponse('GET /card/family/library/groups (after creating 2)', groups)
+
+    assert.ok(Array.isArray(groups), 'Response should be an array')
+    assert.ok(groups.length >= 2, 'Should have at least 2 groups')
+
+    const foundGroup1 = groups.find(g => g.id === group1Id)
+    const foundGroup2 = groups.find(g => g.id === group2Id)
+
+    assert.ok(foundGroup1, 'Should find first created group in list')
+    assert.strictEqual(foundGroup1.name, 'Test Group 1', 'First group name should match')
+
+    assert.ok(foundGroup2, 'Should find second created group in list')
+    assert.strictEqual(foundGroup2.name, 'Test Group 2', 'Second group name should match')
+  })
+
+  await t.test('should get first group by ID', async () => {
+    const group = await getGroup({
+      accessToken,
+      groupId: group1Id
+    })
+
+    logResponse(`GET /card/family/library/groups/${group1Id}`, group)
+
+    assert.ok(group, 'Response should exist')
+    assert.strictEqual(group.id, group1Id, 'Group ID should match')
+    assert.strictEqual(group.name, 'Test Group 1', 'Group name should match')
+    assert.strictEqual(group.imageId, 'fp-cards', 'Image ID should match')
+    assert.ok(Array.isArray(group.items), 'Group should have items array')
+    assert.ok(Array.isArray(group.cards), 'Group should have cards array')
+  })
+
+  await t.test('should get second group by ID', async () => {
+    const group = await getGroup({
+      accessToken,
+      groupId: group2Id
+    })
+
+    logResponse(`GET /card/family/library/groups/${group2Id}`, group)
+
+    assert.ok(group, 'Response should exist')
+    assert.strictEqual(group.id, group2Id, 'Group ID should match')
+    assert.strictEqual(group.name, 'Test Group 2', 'Group name should match')
+  })
+
+  await t.test('should update first group', async () => {
+    const updatedGroup = await updateGroup({
+      accessToken,
+      groupId: group1Id,
+      group: {
+        name: 'Test Group 1 - Updated',
+        imageId: 'fp-cards',
+        items: []
+      }
+    })
+
+    logResponse(`PUT /card/family/library/groups/${group1Id}`, updatedGroup)
+
+    assert.ok(updatedGroup, 'Response should exist')
+    assert.strictEqual(updatedGroup.id, group1Id, 'Group ID should remain the same')
+    assert.strictEqual(updatedGroup.name, 'Test Group 1 - Updated', 'Group name should be updated')
+    assert.ok(typeof updatedGroup.lastModifiedAt === 'string', 'Should have lastModifiedAt')
+  })
+
+  await t.test('should get updated group and confirm changes', async () => {
+    const group = await getGroup({
+      accessToken,
+      groupId: group1Id
+    })
+
+    logResponse(`GET /card/family/library/groups/${group1Id} (after update)`, group)
+
+    assert.strictEqual(group.name, 'Test Group 1 - Updated', 'Updated name should persist')
+  })
+
+  await t.test('should delete first group', async () => {
+    const response = await deleteGroup({
+      accessToken,
+      groupId: group1Id
+    })
+
+    logResponse(`DELETE /card/family/library/groups/${group1Id}`, response)
+
+    assert.ok(response, 'Response should exist')
+    assert.strictEqual(response.id, group1Id, 'Deleted group ID should match')
+
+    // Remove from cleanup list since we already deleted it
+    createdGroupIds = createdGroupIds.filter(id => id !== group1Id)
+  })
+
+  await t.test('should delete second group', async () => {
+    const response = await deleteGroup({
+      accessToken,
+      groupId: group2Id
+    })
+
+    logResponse(`DELETE /card/family/library/groups/${group2Id}`, response)
+
+    assert.ok(response, 'Response should exist')
+    assert.strictEqual(response.id, group2Id, 'Deleted group ID should match')
+
+    // Remove from cleanup list since we already deleted it
+    createdGroupIds = createdGroupIds.filter(id => id !== group2Id)
+  })
+
+  await t.test('should verify groups are deleted from list', async () => {
+    const groups = await getGroups({
+      accessToken
+    })
+
+    logResponse('GET /card/family/library/groups (after deletion)', groups)
+
+    const foundGroup1 = groups.find(g => g.id === group1Id)
+    const foundGroup2 = groups.find(g => g.id === group2Id)
+
+    assert.strictEqual(foundGroup1, undefined, 'First group should not be in list')
+    assert.strictEqual(foundGroup2, undefined, 'Second group should not be in list')
+  })
+
+  await t.test('should return 404 when getting deleted group', async () => {
+    await assert.rejects(
+      async () => {
+        await getGroup({
+          accessToken,
+          groupId: group1Id
+        })
+      },
+      (err) => {
+        assert.ok(err instanceof YotoAPIError, 'Should throw YotoAPIError')
+        assert.strictEqual(err.statusCode, 404, 'Should return 404 for deleted group')
+        return true
+      }
+    )
+  })
+})

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

@@ -0,0 +1,39 @@
+export function getFamilyImages({ 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<YotoFamilyImagesResponse>;
+export function getAFamilyImage({ accessToken, userAgent, imageId, size, requestOptions }: {
+    accessToken: string;
+    imageId: string;
+    size: "640x480" | "320x320";
+    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<YotoFamilyImageResponse>;
+export function uploadAFamilyImage({ accessToken, userAgent, imageData, requestOptions }: {
+    accessToken: string;
+    imageData: Buffer;
+    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<YotoUploadFamilyImageResponse>;
+export type YotoFamilyImagesResponse = {
+    images: YotoFamilyImage[];
+};
+export type YotoFamilyImage = {
+    imageId: string;
+    name?: string;
+};
+export type YotoFamilyImageResponse = {
+    imageUrl: string;
+};
+export type YotoUploadFamilyImageResponse = {
+    imageId: string;
+    url: string;
+};
+//# sourceMappingURL=family.d.ts.map

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

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