Add list pagination

site/lib/cli/pagination.d.ts

@@ -0,0 +1,19 @@
+/** Pull the `page[cursor]` token out of a JSON:API `links.next` value. */
+export declare function extractCursor(next: unknown): string | undefined;
+interface PageParams {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+}
+interface PaginationOptions {
+    /** Delay between per-page retries. Overridable (set to 0) to keep tests fast. */
+    retryDelayMs?: number;
+}
+/**
+ * Repeatedly GET `path`, following `links.next`, until no further page.
+ * Returns the concatenated `data` and `included` arrays from every page.
+ */
+export declare function fetchAllPages(client: any, path: string, params: PageParams, options?: PaginationOptions): Promise<{
+    data: any[];
+    included: any[];
+}>;
+export {};

site/scripts/copy-cli-dist.js

@@ -15,6 +15,7 @@ const files = [
   'album.js', 'album.d.ts',
   'playlist.js', 'playlist.d.ts',
   'library.js', 'library.d.ts',
+  'pagination.js', 'pagination.d.ts',
   'playback.js', 'playback.d.ts',
   'recommend.js', 'recommend.d.ts',
   'mix.js', 'mix.d.ts',

src/__tests__/library.test.ts

@@ -119,6 +119,10 @@ describe('listFavoritedPlaylists', () => {
   it('lists favorited playlists', async () => {
     mockClient.GET.mockResolvedValue({
       data: {
+        data: [
+          { type: 'playlists', id: 'pl-fav-1' },
+          { type: 'playlists', id: 'pl-fav-2' },
+        ],
         included: [
           {
             id: 'pl-fav-1',
@@ -143,6 +147,7 @@ describe('listFavoritedPlaylists', () => {
   it('outputs JSON', async () => {
     mockClient.GET.mockResolvedValue({
       data: {
+        data: [{ type: 'playlists', id: 'pl-1' }],
         included: [
           { id: 'pl-1', type: 'playlists', attributes: { name: 'Fav PL', numberOfItems: 10 } },
         ],
@@ -169,6 +174,37 @@ describe('listFavoritedPlaylists', () => {
 
     await expect(listFavoritedPlaylists(false)).rejects.toThrow('process.exit(1)');
   });
+
+  it('follows cursor pagination across multiple pages', async () => {
+    mockClient.GET
+      .mockResolvedValueOnce({
+        data: {
+          data: [{ type: 'playlists', id: 'pl-1' }],
+          included: [
+            { id: 'pl-1', type: 'playlists', attributes: { name: 'Page1', numberOfItems: 10 } },
+          ],
+          links: {
+            next: '/userCollectionPlaylists/me/relationships/items?page%5Bcursor%5D=CURSOR2',
+          },
+        },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          data: [{ type: 'playlists', id: 'pl-2' }],
+          included: [
+            { id: 'pl-2', type: 'playlists', attributes: { name: 'Page2', numberOfItems: 20 } },
+          ],
+          links: {}, // no `next` -> stop
+        },
+      });
+
+    await listFavoritedPlaylists(false);
+
+    expect(mockClient.GET).toHaveBeenCalledTimes(2);
+    expect(mockClient.GET.mock.calls[1][1].params.query['page[cursor]']).toBe('CURSOR2');
+    expect(output.some((l) => l.includes('[pl-1] Page1'))).toBe(true);
+    expect(output.some((l) => l.includes('[pl-2] Page2'))).toBe(true);
+  });
 });
 
 describe('addPlaylistToFavorites', () => {