gumnut-sdk 0.73.0 → 0.74.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.74.0 (2026-04-20)
+
+Full Changelog: [v0.73.0...v0.74.0](https://github.com/gumnut-ai/photos-sdk-typescript/compare/v0.73.0...v0.74.0)
+
+### Features
+
+* **api:** api update ([28ddbde](https://github.com/gumnut-ai/photos-sdk-typescript/commit/28ddbde251fff858fe84d59233d94ae4b4f95de9))
+
 ## 0.73.0 (2026-04-17)
 
 Full Changelog: [v0.72.0...v0.73.0](https://github.com/gumnut-ai/photos-sdk-typescript/compare/v0.72.0...v0.73.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gumnut-sdk",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "description": "The official TypeScript library for the Gumnut API",
   "author": "Gumnut <tedmao@gmail.com>",
   "types": "./index.d.ts",

package/resources/album-assets.d.mts

@@ -4,15 +4,23 @@ import { CursorPage, type CursorPageParams, PagePromise } from "../core/paginati
 import { RequestOptions } from "../internal/request-options.mjs";
 export declare class AlbumAssets extends APIResource {
     /**
-     * Retrieves a paginated list of album-asset links, ordered by creation time,
-     * descending. Can be filtered by album_id, asset_id, or specific album-asset IDs.
+     * Returns paginated _link_ records describing which assets are in which albums —
+     * each row contains `album_id` + `asset_id` + link timestamps, not the full asset
+     * or album metadata. Use this when you specifically need the junction records (for
+     * sync or change tracking).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album-asset
-     * in `data` as `starting_after_id` to fetch the next page.
+     * **For most use cases you want a different tool:** use `list_assets` with
+     * `album_id` to get the full asset metadata for a specific album; use
+     * `list_albums` with `asset_id` to find which albums contain an asset.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album-asset in `data` as `starting_after_id` to fetch the next page.
      */
     list(query?: AlbumAssetListParams | null | undefined, options?: RequestOptions): PagePromise<AlbumAssetResponsesCursorPage, AlbumAssetResponse>;
     /**
-     * Retrieves details for a specific album-asset link.
+     * Fetches one album-asset link record (the junction row between an album and an
+     * asset). Rarely needed directly; most callers want `get_asset` or `get_album`
+     * instead.
      */
     get(albumAssetID: string, options?: RequestOptions): APIPromise<AlbumAssetResponse>;
 }
@@ -44,19 +52,25 @@ export interface AlbumAssetResponse {
 }
 export interface AlbumAssetListParams extends CursorPageParams {
     /**
-     * Filter by album ID
+     * Return only link records for this album ID. Equivalent to 'list the assets in
+     * this album' — in most cases prefer `list_assets` with `album_id` to get the
+     * asset metadata directly instead of the lightweight link records.
      */
     album_id?: string | null;
     /**
-     * Filter by asset ID
+     * Return only link records for this asset ID. Equivalent to 'which albums contain
+     * this asset' — in most cases prefer `list_albums` with `asset_id` to get the
+     * album metadata directly.
      */
     asset_id?: string | null;
     /**
-     * Filter by specific album-asset IDs (max 100)
+     * Look up specific album-asset link records by ID (max 100). The ID has the
+     * `album_asset_` prefix.
      */
     ids?: Array<string> | null;
     /**
-     * Library ID (required if user has multiple libraries)
+     * Library to list from. Optional if the user has a single library; required when
+     * they have multiple.
      */
     library_id?: string | null;
 }

package/resources/album-assets.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"album-assets.d.mts","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,EAAE,UAAU,EAAE;OACd,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE;OAClD,EAAE,cAAc,EAAE;AAGzB,qBAAa,WAAY,SAAQ,WAAW;IAC1C;;;;;;OAMG;IACH,IAAI,CACF,KAAK,GAAE,oBAAoB,GAAG,IAAI,GAAG,SAAc,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,6BAA6B,EAAE,kBAAkB,CAAC;IAOjE;;OAEG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,kBAAkB,CAAC;CAGpF;AAED,MAAM,MAAM,6BAA6B,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,OAAO,EACL,KAAK,kBAAkB,IAAI,kBAAkB,EAC7C,KAAK,6BAA6B,IAAI,6BAA6B,EACnE,KAAK,oBAAoB,IAAI,oBAAoB,GAClD,CAAC;CACH"}
+{"version":3,"file":"album-assets.d.mts","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,EAAE,UAAU,EAAE;OACd,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE;OAClD,EAAE,cAAc,EAAE;AAGzB,qBAAa,WAAY,SAAQ,WAAW;IAC1C;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,KAAK,GAAE,oBAAoB,GAAG,IAAI,GAAG,SAAc,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,6BAA6B,EAAE,kBAAkB,CAAC;IAOjE;;;;OAIG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,kBAAkB,CAAC;CAGpF;AAED,MAAM,MAAM,6BAA6B,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,OAAO,EACL,KAAK,kBAAkB,IAAI,kBAAkB,EAC7C,KAAK,6BAA6B,IAAI,6BAA6B,EACnE,KAAK,oBAAoB,IAAI,oBAAoB,GAClD,CAAC;CACH"}

package/resources/album-assets.d.ts

@@ -4,15 +4,23 @@ import { CursorPage, type CursorPageParams, PagePromise } from "../core/paginati
 import { RequestOptions } from "../internal/request-options.js";
 export declare class AlbumAssets extends APIResource {
     /**
-     * Retrieves a paginated list of album-asset links, ordered by creation time,
-     * descending. Can be filtered by album_id, asset_id, or specific album-asset IDs.
+     * Returns paginated _link_ records describing which assets are in which albums —
+     * each row contains `album_id` + `asset_id` + link timestamps, not the full asset
+     * or album metadata. Use this when you specifically need the junction records (for
+     * sync or change tracking).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album-asset
-     * in `data` as `starting_after_id` to fetch the next page.
+     * **For most use cases you want a different tool:** use `list_assets` with
+     * `album_id` to get the full asset metadata for a specific album; use
+     * `list_albums` with `asset_id` to find which albums contain an asset.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album-asset in `data` as `starting_after_id` to fetch the next page.
      */
     list(query?: AlbumAssetListParams | null | undefined, options?: RequestOptions): PagePromise<AlbumAssetResponsesCursorPage, AlbumAssetResponse>;
     /**
-     * Retrieves details for a specific album-asset link.
+     * Fetches one album-asset link record (the junction row between an album and an
+     * asset). Rarely needed directly; most callers want `get_asset` or `get_album`
+     * instead.
      */
     get(albumAssetID: string, options?: RequestOptions): APIPromise<AlbumAssetResponse>;
 }
@@ -44,19 +52,25 @@ export interface AlbumAssetResponse {
 }
 export interface AlbumAssetListParams extends CursorPageParams {
     /**
-     * Filter by album ID
+     * Return only link records for this album ID. Equivalent to 'list the assets in
+     * this album' — in most cases prefer `list_assets` with `album_id` to get the
+     * asset metadata directly instead of the lightweight link records.
      */
     album_id?: string | null;
     /**
-     * Filter by asset ID
+     * Return only link records for this asset ID. Equivalent to 'which albums contain
+     * this asset' — in most cases prefer `list_albums` with `asset_id` to get the
+     * album metadata directly.
      */
     asset_id?: string | null;
     /**
-     * Filter by specific album-asset IDs (max 100)
+     * Look up specific album-asset link records by ID (max 100). The ID has the
+     * `album_asset_` prefix.
      */
     ids?: Array<string> | null;
     /**
-     * Library ID (required if user has multiple libraries)
+     * Library to list from. Optional if the user has a single library; required when
+     * they have multiple.
      */
     library_id?: string | null;
 }

package/resources/album-assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"album-assets.d.ts","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,EAAE,UAAU,EAAE;OACd,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE;OAClD,EAAE,cAAc,EAAE;AAGzB,qBAAa,WAAY,SAAQ,WAAW;IAC1C;;;;;;OAMG;IACH,IAAI,CACF,KAAK,GAAE,oBAAoB,GAAG,IAAI,GAAG,SAAc,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,6BAA6B,EAAE,kBAAkB,CAAC;IAOjE;;OAEG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,kBAAkB,CAAC;CAGpF;AAED,MAAM,MAAM,6BAA6B,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,OAAO,EACL,KAAK,kBAAkB,IAAI,kBAAkB,EAC7C,KAAK,6BAA6B,IAAI,6BAA6B,EACnE,KAAK,oBAAoB,IAAI,oBAAoB,GAClD,CAAC;CACH"}
+{"version":3,"file":"album-assets.d.ts","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,EAAE,UAAU,EAAE;OACd,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE;OAClD,EAAE,cAAc,EAAE;AAGzB,qBAAa,WAAY,SAAQ,WAAW;IAC1C;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,KAAK,GAAE,oBAAoB,GAAG,IAAI,GAAG,SAAc,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,6BAA6B,EAAE,kBAAkB,CAAC;IAOjE;;;;OAIG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,kBAAkB,CAAC;CAGpF;AAED,MAAM,MAAM,6BAA6B,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,OAAO,EACL,KAAK,kBAAkB,IAAI,kBAAkB,EAC7C,KAAK,6BAA6B,IAAI,6BAA6B,EACnE,KAAK,oBAAoB,IAAI,oBAAoB,GAClD,CAAC;CACH"}

package/resources/album-assets.js

@@ -7,11 +7,17 @@ const pagination_1 = require("../core/pagination.js");
 const path_1 = require("../internal/utils/path.js");
 class AlbumAssets extends resource_1.APIResource {
     /**
-     * Retrieves a paginated list of album-asset links, ordered by creation time,
-     * descending. Can be filtered by album_id, asset_id, or specific album-asset IDs.
+     * Returns paginated _link_ records describing which assets are in which albums —
+     * each row contains `album_id` + `asset_id` + link timestamps, not the full asset
+     * or album metadata. Use this when you specifically need the junction records (for
+     * sync or change tracking).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album-asset
-     * in `data` as `starting_after_id` to fetch the next page.
+     * **For most use cases you want a different tool:** use `list_assets` with
+     * `album_id` to get the full asset metadata for a specific album; use
+     * `list_albums` with `asset_id` to find which albums contain an asset.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album-asset in `data` as `starting_after_id` to fetch the next page.
      */
     list(query = {}, options) {
         return this._client.getAPIList('/api/album-assets', (pagination_1.CursorPage), {
@@ -20,7 +26,9 @@ class AlbumAssets extends resource_1.APIResource {
         });
     }
     /**
-     * Retrieves details for a specific album-asset link.
+     * Fetches one album-asset link record (the junction row between an album and an
+     * asset). Rarely needed directly; most callers want `get_asset` or `get_album`
+     * instead.
      */
     get(albumAssetID, options) {
         return this._client.get((0, path_1.path) `/api/album-assets/${albumAssetID}`, options);

package/resources/album-assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"album-assets.js","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAE/C,sDAAoF;AAEpF,oDAA8C;AAE9C,MAAa,WAAY,SAAQ,sBAAW;IAC1C;;;;;;OAMG;IACH,IAAI,CACF,QAAiD,EAAE,EACnD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAA,uBAA8B,CAAA,EAAE;YAClF,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,YAAoB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,qBAAqB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF;AAxBD,kCAwBC"}
+{"version":3,"file":"album-assets.js","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAE/C,sDAAoF;AAEpF,oDAA8C;AAE9C,MAAa,WAAY,SAAQ,sBAAW;IAC1C;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,QAAiD,EAAE,EACnD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAA,uBAA8B,CAAA,EAAE;YAClF,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,YAAoB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,qBAAqB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF;AAhCD,kCAgCC"}

package/resources/album-assets.mjs

@@ -4,11 +4,17 @@ import { CursorPage } from "../core/pagination.mjs";
 import { path } from "../internal/utils/path.mjs";
 export class AlbumAssets extends APIResource {
     /**
-     * Retrieves a paginated list of album-asset links, ordered by creation time,
-     * descending. Can be filtered by album_id, asset_id, or specific album-asset IDs.
+     * Returns paginated _link_ records describing which assets are in which albums —
+     * each row contains `album_id` + `asset_id` + link timestamps, not the full asset
+     * or album metadata. Use this when you specifically need the junction records (for
+     * sync or change tracking).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album-asset
-     * in `data` as `starting_after_id` to fetch the next page.
+     * **For most use cases you want a different tool:** use `list_assets` with
+     * `album_id` to get the full asset metadata for a specific album; use
+     * `list_albums` with `asset_id` to find which albums contain an asset.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album-asset in `data` as `starting_after_id` to fetch the next page.
      */
     list(query = {}, options) {
         return this._client.getAPIList('/api/album-assets', (CursorPage), {
@@ -17,7 +23,9 @@ export class AlbumAssets extends APIResource {
         });
     }
     /**
-     * Retrieves details for a specific album-asset link.
+     * Fetches one album-asset link record (the junction row between an album and an
+     * asset). Rarely needed directly; most callers want `get_asset` or `get_album`
+     * instead.
      */
     get(albumAssetID, options) {
         return this._client.get(path `/api/album-assets/${albumAssetID}`, options);

package/resources/album-assets.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"album-assets.mjs","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EAAE,UAAU,EAAsC;OAElD,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,WAAY,SAAQ,WAAW;IAC1C;;;;;;OAMG;IACH,IAAI,CACF,QAAiD,EAAE,EACnD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAA,UAA8B,CAAA,EAAE;YAClF,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,YAAoB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,qBAAqB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF"}
+{"version":3,"file":"album-assets.mjs","sourceRoot":"","sources":["../src/resources/album-assets.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EAAE,UAAU,EAAsC;OAElD,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,WAAY,SAAQ,WAAW;IAC1C;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,QAAiD,EAAE,EACnD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAA,UAA8B,CAAA,EAAE;YAClF,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,YAAoB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,qBAAqB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/resources/albums/albums.d.mts

@@ -7,29 +7,41 @@ import { RequestOptions } from "../../internal/request-options.mjs";
 export declare class Albums extends APIResource {
     assetsAssociations: AssetsAssociationsAPI.AssetsAssociations;
     /**
-     * Creates a new, empty album with optional name and description in the specified
-     * library.
+     * Creates an album (with optional name and description) and returns it. The album
+     * starts empty — follow up with `add_assets_to_album` to populate it. To rename an
+     * existing album, use `update_album` instead of creating a new one.
      */
     create(body: AlbumCreateParams, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Retrieves details for a specific album.
+     * Fetches one album's metadata (name, description, cover, counts). Use when you
+     * already have an album ID. Does not include the album's assets — use
+     * `list_album_assets` or `list_assets` with `album_id` for that.
      */
     retrieve(albumID: string, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Updates the name and/or description of a specific album.
+     * Updates the `name` and/or `description` of an existing album. Only the fields
+     * included in the request body are changed. To modify the contents of an album,
+     * use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only
+     * changes album metadata.
      */
     update(albumID: string, body: AlbumUpdateParams, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Retrieves a paginated list of albums from the specified library, ordered by
-     * creation time, descending. Can be filtered by asset_id or specific album IDs.
+     * Returns a paginated list of albums ordered by creation time (newest first). Use
+     * this to enumerate a user's albums or to find which albums contain a specific
+     * asset (via `asset_id`).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album in
-     * `data` as `starting_after_id` to fetch the next page.
+     * `list_albums` returns album metadata only — to list the assets inside a
+     * particular album, use `list_album_assets` or `list_assets` with `album_id`.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album in `data` as `starting_after_id` to fetch the next page.
      */
     list(query?: AlbumListParams | null | undefined, options?: RequestOptions): PagePromise<AlbumResponsesCursorPage, AlbumResponse>;
     /**
-     * Deletes a specific album. Note: This does not delete the assets within the
-     * album.
+     * Deletes the album itself. Assets that were in the album remain in the library —
+     * only the album and its asset-links are removed. Use `delete_asset` to delete the
+     * underlying assets, or `remove_assets_from_album` to detach specific assets from
+     * an album you want to keep.
      */
     delete(albumID: string, options?: RequestOptions): APIPromise<void>;
 }
@@ -101,25 +113,45 @@ export declare namespace AlbumResponse {
     }
 }
 export interface AlbumCreateParams {
+    /**
+     * Optional free-form description shown alongside the album name.
+     */
     description?: string | null;
+    /**
+     * Library to create the album in. Optional if the user has a single library;
+     * required when they have multiple. Use `list_libraries` to enumerate.
+     */
     library_id?: string | null;
+    /**
+     * Display name for the new album. Optional; callers that need to name an album can
+     * set it here or via `update_album` after creation.
+     */
     name?: string | null;
 }
 export interface AlbumUpdateParams {
+    /**
+     * New free-form description for the album. Omit to leave unchanged.
+     */
     description?: string | null;
+    /**
+     * New display name for the album. Omit to leave unchanged.
+     */
     name?: string | null;
 }
 export interface AlbumListParams extends CursorPageParams {
     /**
-     * Filter albums containing this asset ID (optional)
+     * Return only albums that contain this asset. Useful for answering 'which albums
+     * is this photo in?' without calling `list_album_assets`.
      */
     asset_id?: string | null;
     /**
-     * Filter by specific album IDs (max 100)
+     * Look up specific albums by ID (max 100; each ID has the `album_` prefix). Use
+     * for bulk fetch when IDs are already known.
      */
     ids?: Array<string> | null;
     /**
-     * Library to list albums from (optional)
+     * Library to list albums from. Optional if the user has a single library; required
+     * when they have multiple. Use `list_libraries` to enumerate.
      */
     library_id?: string | null;
 }

package/resources/albums/albums.d.mts.map

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

package/resources/albums/albums.d.ts

@@ -7,29 +7,41 @@ import { RequestOptions } from "../../internal/request-options.js";
 export declare class Albums extends APIResource {
     assetsAssociations: AssetsAssociationsAPI.AssetsAssociations;
     /**
-     * Creates a new, empty album with optional name and description in the specified
-     * library.
+     * Creates an album (with optional name and description) and returns it. The album
+     * starts empty — follow up with `add_assets_to_album` to populate it. To rename an
+     * existing album, use `update_album` instead of creating a new one.
      */
     create(body: AlbumCreateParams, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Retrieves details for a specific album.
+     * Fetches one album's metadata (name, description, cover, counts). Use when you
+     * already have an album ID. Does not include the album's assets — use
+     * `list_album_assets` or `list_assets` with `album_id` for that.
      */
     retrieve(albumID: string, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Updates the name and/or description of a specific album.
+     * Updates the `name` and/or `description` of an existing album. Only the fields
+     * included in the request body are changed. To modify the contents of an album,
+     * use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only
+     * changes album metadata.
      */
     update(albumID: string, body: AlbumUpdateParams, options?: RequestOptions): APIPromise<AlbumResponse>;
     /**
-     * Retrieves a paginated list of albums from the specified library, ordered by
-     * creation time, descending. Can be filtered by asset_id or specific album IDs.
+     * Returns a paginated list of albums ordered by creation time (newest first). Use
+     * this to enumerate a user's albums or to find which albums contain a specific
+     * asset (via `asset_id`).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album in
-     * `data` as `starting_after_id` to fetch the next page.
+     * `list_albums` returns album metadata only — to list the assets inside a
+     * particular album, use `list_album_assets` or `list_assets` with `album_id`.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album in `data` as `starting_after_id` to fetch the next page.
      */
     list(query?: AlbumListParams | null | undefined, options?: RequestOptions): PagePromise<AlbumResponsesCursorPage, AlbumResponse>;
     /**
-     * Deletes a specific album. Note: This does not delete the assets within the
-     * album.
+     * Deletes the album itself. Assets that were in the album remain in the library —
+     * only the album and its asset-links are removed. Use `delete_asset` to delete the
+     * underlying assets, or `remove_assets_from_album` to detach specific assets from
+     * an album you want to keep.
      */
     delete(albumID: string, options?: RequestOptions): APIPromise<void>;
 }
@@ -101,25 +113,45 @@ export declare namespace AlbumResponse {
     }
 }
 export interface AlbumCreateParams {
+    /**
+     * Optional free-form description shown alongside the album name.
+     */
     description?: string | null;
+    /**
+     * Library to create the album in. Optional if the user has a single library;
+     * required when they have multiple. Use `list_libraries` to enumerate.
+     */
     library_id?: string | null;
+    /**
+     * Display name for the new album. Optional; callers that need to name an album can
+     * set it here or via `update_album` after creation.
+     */
     name?: string | null;
 }
 export interface AlbumUpdateParams {
+    /**
+     * New free-form description for the album. Omit to leave unchanged.
+     */
     description?: string | null;
+    /**
+     * New display name for the album. Omit to leave unchanged.
+     */
     name?: string | null;
 }
 export interface AlbumListParams extends CursorPageParams {
     /**
-     * Filter albums containing this asset ID (optional)
+     * Return only albums that contain this asset. Useful for answering 'which albums
+     * is this photo in?' without calling `list_album_assets`.
      */
     asset_id?: string | null;
     /**
-     * Filter by specific album IDs (max 100)
+     * Look up specific albums by ID (max 100; each ID has the `album_` prefix). Use
+     * for bulk fetch when IDs are already known.
      */
     ids?: Array<string> | null;
     /**
-     * Library to list albums from (optional)
+     * Library to list albums from. Optional if the user has a single library; required
+     * when they have multiple. Use `list_libraries` to enumerate.
      */
     library_id?: string | null;
 }

package/resources/albums/albums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"albums.d.ts","sourceRoot":"","sources":["../../src/resources/albums/albums.ts"],"names":[],"mappings":"OAEO,EAAE,WAAW,EAAE;OACf,KAAK,qBAAqB;OAC1B,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,EAC7B,kBAAkB,EACnB;OACM,EAAE,UAAU,EAAE;OACd,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE;OAElD,EAAE,cAAc,EAAE;AAGzB,qBAAa,MAAO,SAAQ,WAAW;IACrC,kBAAkB,EAAE,qBAAqB,CAAC,kBAAkB,CAE1D;IAEF;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAIpF;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAI9E;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAIrG;;;;;;OAMG;IACH,IAAI,CACF,KAAK,GAAE,eAAe,GAAG,IAAI,GAAG,SAAc,EAC9C,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,CAAC,wBAAwB,EAAE,aAAa,CAAC;IAIvD;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;CAMpE;AAED,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;OAEG;IACH,UAAU,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;IAE/D;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,yBAAiB,aAAa,CAAC;IAC7B;;OAEG;IACH,UAAiB,SAAS;QACxB;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,GAAG,EAAE,MAAM,CAAC;QAEZ;;WAEG;QACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB;CACF;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAID,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,OAAO,EACL,KAAK,aAAa,IAAI,aAAa,EACnC,KAAK,wBAAwB,IAAI,wBAAwB,EACzD,KAAK,iBAAiB,IAAI,iBAAiB,EAC3C,KAAK,iBAAiB,IAAI,iBAAiB,EAC3C,KAAK,eAAe,IAAI,eAAe,GACxC,CAAC;IAEF,OAAO,EACL,kBAAkB,IAAI,kBAAkB,EACxC,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,4BAA4B,IAAI,4BAA4B,EACjE,KAAK,0BAA0B,IAAI,0BAA0B,EAC7D,KAAK,6BAA6B,IAAI,6BAA6B,GACpE,CAAC;CACH"}
+{"version":3,"file":"albums.d.ts","sourceRoot":"","sources":["../../src/resources/albums/albums.ts"],"names":[],"mappings":"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"}

package/resources/albums/albums.js

@@ -15,37 +15,49 @@ class Albums extends resource_1.APIResource {
         this.assetsAssociations = new AssetsAssociationsAPI.AssetsAssociations(this._client);
     }
     /**
-     * Creates a new, empty album with optional name and description in the specified
-     * library.
+     * Creates an album (with optional name and description) and returns it. The album
+     * starts empty — follow up with `add_assets_to_album` to populate it. To rename an
+     * existing album, use `update_album` instead of creating a new one.
      */
     create(body, options) {
         return this._client.post('/api/albums', { body, ...options });
     }
     /**
-     * Retrieves details for a specific album.
+     * Fetches one album's metadata (name, description, cover, counts). Use when you
+     * already have an album ID. Does not include the album's assets — use
+     * `list_album_assets` or `list_assets` with `album_id` for that.
      */
     retrieve(albumID, options) {
         return this._client.get((0, path_1.path) `/api/albums/${albumID}`, options);
     }
     /**
-     * Updates the name and/or description of a specific album.
+     * Updates the `name` and/or `description` of an existing album. Only the fields
+     * included in the request body are changed. To modify the contents of an album,
+     * use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only
+     * changes album metadata.
      */
     update(albumID, body, options) {
         return this._client.patch((0, path_1.path) `/api/albums/${albumID}`, { body, ...options });
     }
     /**
-     * Retrieves a paginated list of albums from the specified library, ordered by
-     * creation time, descending. Can be filtered by asset_id or specific album IDs.
+     * Returns a paginated list of albums ordered by creation time (newest first). Use
+     * this to enumerate a user's albums or to find which albums contain a specific
+     * asset (via `asset_id`).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album in
-     * `data` as `starting_after_id` to fetch the next page.
+     * `list_albums` returns album metadata only — to list the assets inside a
+     * particular album, use `list_album_assets` or `list_assets` with `album_id`.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album in `data` as `starting_after_id` to fetch the next page.
      */
     list(query = {}, options) {
         return this._client.getAPIList('/api/albums', (pagination_1.CursorPage), { query, ...options });
     }
     /**
-     * Deletes a specific album. Note: This does not delete the assets within the
-     * album.
+     * Deletes the album itself. Assets that were in the album remain in the library —
+     * only the album and its asset-links are removed. Use `delete_asset` to delete the
+     * underlying assets, or `remove_assets_from_album` to detach specific assets from
+     * an album you want to keep.
      */
     delete(albumID, options) {
         return this._client.delete((0, path_1.path) `/api/albums/${albumID}`, {

package/resources/albums/albums.js.map

@@ -1 +1 @@
-{"version":3,"file":"albums.js","sourceRoot":"","sources":["../../src/resources/albums/albums.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;;AAEtF,qDAAkD;AAClD,wFAA+D;AAC/D,kEAM+B;AAE/B,yDAAuF;AACvF,uDAAsD;AAEtD,uDAAiD;AAEjD,MAAa,MAAO,SAAQ,sBAAW;IAAvC;;QACE,uBAAkB,GAA6C,IAAI,qBAAqB,CAAC,kBAAkB,CACzG,IAAI,CAAC,OAAO,CACb,CAAC;IAgDJ,CAAC;IA9CC;;;OAGG;IACH,MAAM,CAAC,IAAuB,EAAE,OAAwB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,OAAe,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAe,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CACF,QAA4C,EAAE,EAC9C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,uBAAyB,CAAA,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAe,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE;YACvD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAnDD,wBAmDC;AAgHD,MAAM,CAAC,kBAAkB,GAAG,wCAAkB,CAAC"}
+{"version":3,"file":"albums.js","sourceRoot":"","sources":["../../src/resources/albums/albums.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;;AAEtF,qDAAkD;AAClD,wFAA+D;AAC/D,kEAM+B;AAE/B,yDAAuF;AACvF,uDAAsD;AAEtD,uDAAiD;AAEjD,MAAa,MAAO,SAAQ,sBAAW;IAAvC;;QACE,uBAAkB,GAA6C,IAAI,qBAAqB,CAAC,kBAAkB,CACzG,IAAI,CAAC,OAAO,CACb,CAAC;IA4DJ,CAAC;IA1DC;;;;OAIG;IACH,MAAM,CAAC,IAAuB,EAAE,OAAwB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChE,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,OAAe,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAe,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAI,CACF,QAA4C,EAAE,EAC9C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,uBAAyB,CAAA,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAe,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,eAAe,OAAO,EAAE,EAAE;YACvD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AA/DD,wBA+DC;AAoID,MAAM,CAAC,kBAAkB,GAAG,wCAAkB,CAAC"}

package/resources/albums/albums.mjs

@@ -11,37 +11,49 @@ export class Albums extends APIResource {
         this.assetsAssociations = new AssetsAssociationsAPI.AssetsAssociations(this._client);
     }
     /**
-     * Creates a new, empty album with optional name and description in the specified
-     * library.
+     * Creates an album (with optional name and description) and returns it. The album
+     * starts empty — follow up with `add_assets_to_album` to populate it. To rename an
+     * existing album, use `update_album` instead of creating a new one.
      */
     create(body, options) {
         return this._client.post('/api/albums', { body, ...options });
     }
     /**
-     * Retrieves details for a specific album.
+     * Fetches one album's metadata (name, description, cover, counts). Use when you
+     * already have an album ID. Does not include the album's assets — use
+     * `list_album_assets` or `list_assets` with `album_id` for that.
      */
     retrieve(albumID, options) {
         return this._client.get(path `/api/albums/${albumID}`, options);
     }
     /**
-     * Updates the name and/or description of a specific album.
+     * Updates the `name` and/or `description` of an existing album. Only the fields
+     * included in the request body are changed. To modify the contents of an album,
+     * use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only
+     * changes album metadata.
      */
     update(albumID, body, options) {
         return this._client.patch(path `/api/albums/${albumID}`, { body, ...options });
     }
     /**
-     * Retrieves a paginated list of albums from the specified library, ordered by
-     * creation time, descending. Can be filtered by asset_id or specific album IDs.
+     * Returns a paginated list of albums ordered by creation time (newest first). Use
+     * this to enumerate a user's albums or to find which albums contain a specific
+     * asset (via `asset_id`).
      *
-     * **Pagination:** When `has_more` is true, pass the `id` of the last album in
-     * `data` as `starting_after_id` to fetch the next page.
+     * `list_albums` returns album metadata only — to list the assets inside a
+     * particular album, use `list_album_assets` or `list_assets` with `album_id`.
+     *
+     * **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the
+     * last album in `data` as `starting_after_id` to fetch the next page.
      */
     list(query = {}, options) {
         return this._client.getAPIList('/api/albums', (CursorPage), { query, ...options });
     }
     /**
-     * Deletes a specific album. Note: This does not delete the assets within the
-     * album.
+     * Deletes the album itself. Assets that were in the album remain in the library —
+     * only the album and its asset-links are removed. Use `delete_asset` to delete the
+     * underlying assets, or `remove_assets_from_album` to detach specific assets from
+     * an album you want to keep.
      */
     delete(albumID, options) {
         return this._client.delete(path `/api/albums/${albumID}`, {