@syra.fm/sdk 0.2.0 → 0.4.0

package/src/client.test.ts

@@ -45,6 +45,29 @@ function makePodcast(overrides: Record<string, unknown> = {}): Record<string, un
   };
 }
 
+function makeEpisode(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: '507f1f77bcf86cd799439031',
+    podcastId: '507f1f77bcf86cd799439021',
+    podcastTitle: 'Test Show',
+    title: 'Test Episode',
+    description: 'An episode about testing.',
+    guid: 'guid-1',
+    enclosureUrl: 'https://api.fastcast.ai/audio/guid-1.mp3',
+    enclosureType: 'audio/mpeg',
+    enclosureLength: 12_345_678,
+    duration: 1800,
+    pubDate: '2026-01-01T00:00:00.000Z',
+    episodeType: 'full',
+    image: '507f1f77bcf86cd799439032',
+    imageSourceUrl: 'https://cdn.example.com/episode.jpg',
+    status: 'ready',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
 interface FetchCall {
   url: string;
 }
@@ -70,7 +93,7 @@ function fakeFetch(
 // ── searchTracks ──────────────────────────────────────────────────────────────
 
 describe('createSyraClient.searchTracks', () => {
-  it('calls /api/search with category=tracks and the limit, returns preview-available tracks', async () => {
+  it('calls /api/search with category=tracks and the limit, returns a page of preview-available tracks', async () => {
     const { fetch, calls } = fakeFetch(() => ({
       body: {
         results: {
@@ -79,14 +102,20 @@ describe('createSyraClient.searchTracks', () => {
             makeTrack({ id: '507f1f77bcf86cd799439012', previewAvailable: false }),
           ],
         },
+        hasMore: false,
+        limit: 10,
+        offset: 0,
       },
     }));
 
     const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
-    const tracks = await client.searchTracks('hello', { limit: 10 });
+    const page = await client.searchTracks('hello', { limit: 10 });
 
-    expect(tracks).toHaveLength(1);
-    expect(tracks[0].id).toBe('507f1f77bcf86cd799439011');
+    expect(page.items).toHaveLength(1);
+    expect(page.items[0].id).toBe('507f1f77bcf86cd799439011');
+    expect(page.hasMore).toBe(false);
+    expect(page.limit).toBe(10);
+    expect(page.offset).toBe(0);
 
     expect(calls).toHaveLength(1);
     const url = new URL(calls[0].url);
@@ -94,6 +123,53 @@ describe('createSyraClient.searchTracks', () => {
     expect(url.searchParams.get('q')).toBe('hello');
     expect(url.searchParams.get('category')).toBe('tracks');
     expect(url.searchParams.get('limit')).toBe('10');
+    expect(url.searchParams.has('offset')).toBe(false);
+  });
+
+  it('sends the offset param and reports hasMore/offset/limit from the backend', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        results: { tracks: [makeTrack()] },
+        hasMore: true,
+        limit: 20,
+        offset: 40,
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.searchTracks('hello', { limit: 20, offset: 40 });
+
+    expect(page.items).toHaveLength(1);
+    expect(page.hasMore).toBe(true);
+    expect(page.limit).toBe(20);
+    expect(page.offset).toBe(40);
+
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('offset')).toBe('40');
+    expect(url.searchParams.get('limit')).toBe('20');
+  });
+
+  it('reports backend hasMore even when client-side preview filtering empties the page', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: {
+        results: {
+          tracks: [
+            makeTrack({ previewAvailable: false }),
+            makeTrack({ previewAvailable: false }),
+          ],
+        },
+        hasMore: true,
+        limit: 2,
+        offset: 0,
+      },
+    }));
+
+    const client = createSyraClient({ fetch });
+    const page = await client.searchTracks('x', { limit: 2 });
+
+    // All rows were filtered out, but the page is NOT the last one.
+    expect(page.items).toHaveLength(0);
+    expect(page.hasMore).toBe(true);
   });
 
   it('drops malformed rows without throwing', async () => {
@@ -109,14 +185,17 @@ describe('createSyraClient.searchTracks', () => {
     }));
 
     const client = createSyraClient({ fetch });
-    const tracks = await client.searchTracks('x');
-    expect(tracks).toHaveLength(1);
+    const page = await client.searchTracks('x');
+    expect(page.items).toHaveLength(1);
   });
 
-  it('returns an empty array when results.tracks is absent', async () => {
+  it('returns an empty page with hasMore=false when results.tracks is absent', async () => {
     const { fetch } = fakeFetch(() => ({ body: {} }));
     const client = createSyraClient({ fetch });
-    expect(await client.searchTracks('x')).toEqual([]);
+    const page = await client.searchTracks('x');
+    expect(page.items).toEqual([]);
+    expect(page.hasMore).toBe(false);
+    expect(page.offset).toBe(0);
   });
 });
 
@@ -222,36 +301,60 @@ describe('createSyraClient.artworkUrl', () => {
 // ── searchPodcasts ──────────────────────────────────────────────────────────────
 
 describe('createSyraClient.searchPodcasts', () => {
-  it('calls /api/podcasts/search with q and limit, returns parsed shows', async () => {
+  it('calls /api/podcasts/search with q and limit, returns a page of parsed shows', async () => {
     const { fetch, calls } = fakeFetch(() => ({
       body: {
         data: [
           makePodcast({ id: '507f1f77bcf86cd799439021' }),
           makePodcast({ id: '507f1f77bcf86cd799439023', title: 'Second Show' }),
         ],
+        hasMore: false,
+        limit: 5,
+        offset: 0,
       },
     }));
 
     const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
-    const podcasts = await client.searchPodcasts('news', { limit: 5 });
+    const page = await client.searchPodcasts('news', { limit: 5 });
 
-    expect(podcasts).toHaveLength(2);
-    expect(podcasts[0].id).toBe('507f1f77bcf86cd799439021');
-    expect(podcasts[0].author).toBe('Test Publisher');
+    expect(page.items).toHaveLength(2);
+    expect(page.items[0].id).toBe('507f1f77bcf86cd799439021');
+    expect(page.items[0].author).toBe('Test Publisher');
+    expect(page.hasMore).toBe(false);
+    expect(page.limit).toBe(5);
+    expect(page.offset).toBe(0);
 
     expect(calls).toHaveLength(1);
     const url = new URL(calls[0].url);
     expect(url.pathname).toBe('/api/podcasts/search');
     expect(url.searchParams.get('q')).toBe('news');
     expect(url.searchParams.get('limit')).toBe('5');
+    expect(url.searchParams.has('offset')).toBe(false);
   });
 
-  it('omits the limit param when not provided', async () => {
+  it('sends the offset param and reports hasMore/offset from the backend', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: { data: [makePodcast()], hasMore: true, limit: 10, offset: 20 },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.searchPodcasts('news', { limit: 10, offset: 20 });
+
+    expect(page.hasMore).toBe(true);
+    expect(page.limit).toBe(10);
+    expect(page.offset).toBe(20);
+
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('offset')).toBe('20');
+  });
+
+  it('omits the limit and offset params when not provided', async () => {
     const { fetch, calls } = fakeFetch(() => ({ body: { data: [makePodcast()] } }));
     const client = createSyraClient({ fetch });
     await client.searchPodcasts('news');
     const url = new URL(calls[0].url);
     expect(url.searchParams.has('limit')).toBe(false);
+    expect(url.searchParams.has('offset')).toBe(false);
   });
 
   it('drops malformed rows without throwing', async () => {
@@ -259,14 +362,17 @@ describe('createSyraClient.searchPodcasts', () => {
       body: { data: [{ id: 'broken' }, makePodcast()] },
     }));
     const client = createSyraClient({ fetch });
-    const podcasts = await client.searchPodcasts('x');
-    expect(podcasts).toHaveLength(1);
+    const page = await client.searchPodcasts('x');
+    expect(page.items).toHaveLength(1);
   });
 
-  it('returns an empty array when data is absent', async () => {
+  it('returns an empty page with hasMore=false when data is absent', async () => {
     const { fetch } = fakeFetch(() => ({ body: {} }));
     const client = createSyraClient({ fetch });
-    expect(await client.searchPodcasts('x')).toEqual([]);
+    const page = await client.searchPodcasts('x');
+    expect(page.items).toEqual([]);
+    expect(page.hasMore).toBe(false);
+    expect(page.offset).toBe(0);
   });
 });
 
@@ -362,3 +468,165 @@ describe('createSyraClient.podcastArtworkUrl', () => {
     expect(client.podcastArtworkUrl({ image: 'not-an-id' })).toBeUndefined();
   });
 });
+
+// ── getPodcastEpisodes ──────────────────────────────────────────────────────────
+
+describe('createSyraClient.getPodcastEpisodes', () => {
+  it('calls /api/podcasts/:id/episodes with page and limit and returns parsed episodes', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        data: [
+          makeEpisode({ id: '507f1f77bcf86cd799439031' }),
+          makeEpisode({ id: '507f1f77bcf86cd799439033', title: 'Second Episode' }),
+        ],
+        total: 2,
+        page: 1,
+        limit: 20,
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.getPodcastEpisodes('507f1f77bcf86cd799439021', { limit: 20 });
+
+    expect(page.items).toHaveLength(2);
+    expect(page.items[0].id).toBe('507f1f77bcf86cd799439031');
+    expect(page.items[0].enclosureUrl).toBe('https://api.fastcast.ai/audio/guid-1.mp3');
+    expect(page.hasMore).toBe(false);
+    expect(page.limit).toBe(20);
+    expect(page.offset).toBe(0);
+
+    expect(calls).toHaveLength(1);
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe('/api/podcasts/507f1f77bcf86cd799439021/episodes');
+    expect(url.searchParams.get('page')).toBe('1');
+    expect(url.searchParams.get('limit')).toBe('20');
+  });
+
+  it('translates a zero-based offset into a 1-based page and derives hasMore from total', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: { data: [makeEpisode()], total: 45, page: 3, limit: 10 },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.getPodcastEpisodes('507f1f77bcf86cd799439021', {
+      limit: 10,
+      offset: 20,
+    });
+
+    // offset 20 / limit 10 → page 3; 3 * 10 = 30 < 45 → more remain.
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('page')).toBe('3');
+    expect(url.searchParams.get('limit')).toBe('10');
+    expect(page.offset).toBe(20);
+    expect(page.limit).toBe(10);
+    expect(page.hasMore).toBe(true);
+  });
+
+  it('reports hasMore=false when the page reaches the end of the total', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: { data: [makeEpisode()], total: 20, page: 2, limit: 10 },
+    }));
+    const client = createSyraClient({ fetch });
+    const page = await client.getPodcastEpisodes('507f1f77bcf86cd799439021', {
+      limit: 10,
+      offset: 10,
+    });
+    // page 2 * limit 10 = 20, not < total 20 → this is the last page.
+    expect(page.hasMore).toBe(false);
+  });
+
+  it('drops a row missing the required enclosureUrl without throwing', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: {
+        data: [makeEpisode({ enclosureUrl: undefined }), makeEpisode()],
+        total: 2,
+      },
+    }));
+    const client = createSyraClient({ fetch });
+    const page = await client.getPodcastEpisodes('507f1f77bcf86cd799439021', { limit: 10 });
+    expect(page.items).toHaveLength(1);
+    expect(page.items[0].enclosureUrl).toBe('https://api.fastcast.ai/audio/guid-1.mp3');
+  });
+
+  it('defaults the limit and returns an empty page when data is absent', async () => {
+    const { fetch, calls } = fakeFetch(() => ({ body: {} }));
+    const client = createSyraClient({ fetch });
+    const page = await client.getPodcastEpisodes('507f1f77bcf86cd799439021');
+    expect(page.items).toEqual([]);
+    expect(page.hasMore).toBe(false);
+    expect(page.offset).toBe(0);
+    expect(page.limit).toBe(20);
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('page')).toBe('1');
+    expect(url.searchParams.get('limit')).toBe('20');
+  });
+});
+
+// ── getEpisode ──────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.getEpisode', () => {
+  it('fetches /api/episodes/:id and validates data.episode', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: { data: { episode: makeEpisode(), persons: [] } },
+    }));
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+
+    const episode = await client.getEpisode('507f1f77bcf86cd799439031');
+    expect(episode.title).toBe('Test Episode');
+    expect(episode.enclosureUrl).toBe('https://api.fastcast.ai/audio/guid-1.mp3');
+    expect(calls[0].url).toBe('https://api.example.test/api/episodes/507f1f77bcf86cd799439031');
+  });
+
+  it('throws SyraApiError on a non-2xx response', async () => {
+    const { fetch } = fakeFetch(() => ({ status: 404, body: { error: 'not found' } }));
+    const client = createSyraClient({ fetch });
+    await expect(client.getEpisode('507f1f77bcf86cd799439031')).rejects.toBeInstanceOf(SyraApiError);
+  });
+
+  it('throws when data.episode fails schema validation', async () => {
+    const { fetch } = fakeFetch(() => ({ body: { data: { episode: { id: 'x' } } } }));
+    const client = createSyraClient({ fetch });
+    await expect(client.getEpisode('x')).rejects.toThrow();
+  });
+});
+
+// ── episodeImageUrl ──────────────────────────────────────────────────────────────
+
+describe('createSyraClient.episodeImageUrl', () => {
+  const client = createSyraClient({ baseURL: 'https://api.example.test' });
+
+  it('resolves the re-hosted image id to an absolute images URL', () => {
+    expect(client.episodeImageUrl({ image: '507f1f77bcf86cd799439032' })).toBe(
+      'https://api.example.test/api/images/507f1f77bcf86cd799439032',
+    );
+  });
+
+  it('prefers a named size from imageSizes', () => {
+    const url = client.episodeImageUrl(
+      {
+        image: '507f1f77bcf86cd799439032',
+        imageSizes: {
+          large: {
+            id: '507f1f77bcf86cd799439033',
+            url: '/api/images/507f1f77bcf86cd799439033',
+            width: 640,
+            height: 640,
+          },
+        },
+      },
+      'large',
+    );
+    expect(url).toBe('https://api.example.test/api/images/507f1f77bcf86cd799439033');
+  });
+
+  it('falls back to imageSourceUrl when no Syra image is present', () => {
+    expect(client.episodeImageUrl({ imageSourceUrl: 'https://cdn.example.com/episode.jpg' })).toBe(
+      'https://cdn.example.com/episode.jpg',
+    );
+  });
+
+  it('returns undefined when nothing resolvable is present', () => {
+    expect(client.episodeImageUrl({})).toBeUndefined();
+    expect(client.episodeImageUrl({ image: 'not-an-id' })).toBeUndefined();
+  });
+});