@syra.fm/sdk 0.2.0 → 0.3.0

package/README.md

@@ -18,11 +18,15 @@ import { createSyraClient } from '@syra.fm/sdk';
 
 const syra = createSyraClient(); // defaults to https://api.syra.fm
 
-// Search the catalog (only tracks with a public preview are returned)
-const tracks = await syra.searchTracks('lofi beats', { limit: 10 });
+// Search the catalog — returns one page; only tracks with a public preview are
+// in `items`. Paginate for infinite scroll by advancing `offset` by `limit`.
+const page = await syra.searchTracks('lofi beats', { limit: 10, offset: 0 });
+if (page.hasMore) {
+  const next = await syra.searchTracks('lofi beats', { limit: 10, offset: 10 });
+}
 
 // Fetch a single track
-const track = await syra.getTrack(tracks[0].id);
+const track = await syra.getTrack(page.items[0].id);
 
 // Build a public 30s preview URL (directly playable MP3)
 const url = syra.previewUrl(track.id);          // .../api/preview/<id>.mp3?start=0
@@ -48,10 +52,18 @@ authenticated transport can be layered in a future version.
 
 | Method | Description |
 | --- | --- |
-| `searchTracks(query, { limit })` | Preview-available `TrackSummary[]` matching `query`. |
+| `searchTracks(query, { limit, offset })` | A `SearchPage<TrackSummary>` of preview-available tracks (`{ items, hasMore, limit, offset }`). |
 | `getTrack(id)` | A single `TrackSummary`, schema-validated. |
 | `previewUrl(id, startSec = 0)` | Public 30s preview URL. |
 | `artworkUrl(trackOrCoverArt, size?)` | Absolute artwork URL, or `undefined`. |
+| `searchPodcasts(query, { limit, offset })` | A `SearchPage<PodcastSummary>` of podcast shows. |
+| `getPodcast(id)` | A single `PodcastSummary`, schema-validated. |
+| `podcastUrl(id)` | Syra web deep link (`/podcasts/:id`). |
+| `podcastArtworkUrl(show, size?)` | Absolute show-artwork URL, or `undefined`. |
+
+`hasMore` reflects the backend's pagination over the full result set, so it is
+not affected by the client-side preview filter on `searchTracks` — paginate by
+advancing `offset` by `limit`, never by `items.length`.
 
 Responses are validated at runtime with the package's own self-contained Zod
 schemas (`trackSummarySchema`), so there are no shared internal dependencies.

package/dist/cjs/client.js

@@ -18,6 +18,10 @@ const ARTWORK_FALLBACK_ORDER = [
     'small',
 ];
 const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
+/** Read a finite number from an unknown response field, else a fallback. */
+function numberOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
 /**
  * Create a headless client for the public Syra API. Public reads only — there
  * is no authentication in this version.
@@ -67,17 +71,29 @@ function createSyraClient(options = {}) {
             if (typeof searchOptions.limit === 'number') {
                 params.set('limit', String(searchOptions.limit));
             }
+            if (typeof searchOptions.offset === 'number') {
+                params.set('offset', String(searchOptions.offset));
+            }
             const json = (await getJson(`/api/search?${params.toString()}`));
             const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
-            const tracks = [];
+            const items = [];
             for (const raw of rawTracks) {
                 // A single malformed catalog row must not fail the whole search.
                 const parsed = schema_1.trackSummarySchema.safeParse(raw);
                 if (parsed.success && parsed.data.previewAvailable === true) {
-                    tracks.push(parsed.data);
+                    items.push(parsed.data);
                 }
             }
-            return tracks;
+            return {
+                items,
+                // `hasMore` is sourced from the backend's pagination over the FULL result
+                // set; the client-side preview filter above may shrink `items` below
+                // `limit`, but must NOT corrupt `hasMore` (else a page whose tail was
+                // filtered out would falsely report the end of the catalog).
+                hasMore: json?.hasMore === true,
+                limit: numberOr(json?.limit, searchOptions.limit ?? rawTracks.length),
+                offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+            };
         },
         async getTrack(id) {
             const json = await getJson(`/api/tracks/${encodeURIComponent(id)}`);
@@ -116,17 +132,26 @@ function createSyraClient(options = {}) {
             if (typeof searchOptions.limit === 'number') {
                 params.set('limit', String(searchOptions.limit));
             }
+            if (typeof searchOptions.offset === 'number') {
+                params.set('offset', String(searchOptions.offset));
+            }
             const json = (await getJson(`/api/podcasts/search?${params.toString()}`));
             const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
-            const podcasts = [];
+            const items = [];
             for (const raw of rawPodcasts) {
                 // A single malformed catalog row must not fail the whole search.
                 const parsed = schema_1.podcastSummarySchema.safeParse(raw);
                 if (parsed.success) {
-                    podcasts.push(parsed.data);
+                    items.push(parsed.data);
                 }
             }
-            return podcasts;
+            return {
+                items,
+                // `hasMore` reflects the backend's pagination over the full result set.
+                hasMore: json?.hasMore === true,
+                limit: numberOr(json?.limit, searchOptions.limit ?? rawPodcasts.length),
+                offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+            };
         },
         async getPodcast(id) {
             const json = (await getJson(`/api/podcasts/${encodeURIComponent(id)}`));

package/dist/esm/client.js

@@ -14,6 +14,10 @@ const ARTWORK_FALLBACK_ORDER = [
     'small',
 ];
 const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
+/** Read a finite number from an unknown response field, else a fallback. */
+function numberOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
 /**
  * Create a headless client for the public Syra API. Public reads only — there
  * is no authentication in this version.
@@ -63,17 +67,29 @@ export function createSyraClient(options = {}) {
             if (typeof searchOptions.limit === 'number') {
                 params.set('limit', String(searchOptions.limit));
             }
+            if (typeof searchOptions.offset === 'number') {
+                params.set('offset', String(searchOptions.offset));
+            }
             const json = (await getJson(`/api/search?${params.toString()}`));
             const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
-            const tracks = [];
+            const items = [];
             for (const raw of rawTracks) {
                 // A single malformed catalog row must not fail the whole search.
                 const parsed = trackSummarySchema.safeParse(raw);
                 if (parsed.success && parsed.data.previewAvailable === true) {
-                    tracks.push(parsed.data);
+                    items.push(parsed.data);
                 }
             }
-            return tracks;
+            return {
+                items,
+                // `hasMore` is sourced from the backend's pagination over the FULL result
+                // set; the client-side preview filter above may shrink `items` below
+                // `limit`, but must NOT corrupt `hasMore` (else a page whose tail was
+                // filtered out would falsely report the end of the catalog).
+                hasMore: json?.hasMore === true,
+                limit: numberOr(json?.limit, searchOptions.limit ?? rawTracks.length),
+                offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+            };
         },
         async getTrack(id) {
             const json = await getJson(`/api/tracks/${encodeURIComponent(id)}`);
@@ -112,17 +128,26 @@ export function createSyraClient(options = {}) {
             if (typeof searchOptions.limit === 'number') {
                 params.set('limit', String(searchOptions.limit));
             }
+            if (typeof searchOptions.offset === 'number') {
+                params.set('offset', String(searchOptions.offset));
+            }
             const json = (await getJson(`/api/podcasts/search?${params.toString()}`));
             const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
-            const podcasts = [];
+            const items = [];
             for (const raw of rawPodcasts) {
                 // A single malformed catalog row must not fail the whole search.
                 const parsed = podcastSummarySchema.safeParse(raw);
                 if (parsed.success) {
-                    podcasts.push(parsed.data);
+                    items.push(parsed.data);
                 }
             }
-            return podcasts;
+            return {
+                items,
+                // `hasMore` reflects the backend's pagination over the full result set.
+                hasMore: json?.hasMore === true,
+                limit: numberOr(json?.limit, searchOptions.limit ?? rawPodcasts.length),
+                offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+            };
         },
         async getPodcast(id) {
             const json = (await getJson(`/api/podcasts/${encodeURIComponent(id)}`));

package/dist/types/client.d.ts

@@ -20,12 +20,35 @@ export interface SyraClientOptions {
     fetch?: typeof fetch;
 }
 export interface SearchTracksOptions {
-    /** Maximum number of tracks to request from the API. */
+    /** Maximum number of tracks to request from the API (the page size). */
     limit?: number;
+    /** Zero-based offset of the first track to return (for infinite scroll). */
+    offset?: number;
 }
 export interface SearchPodcastsOptions {
-    /** Maximum number of podcast shows to request from the API. */
+    /** Maximum number of podcast shows to request from the API (the page size). */
     limit?: number;
+    /** Zero-based offset of the first show to return (for infinite scroll). */
+    offset?: number;
+}
+/**
+ * One page of paginated catalog search results.
+ *
+ * `hasMore` reflects the BACKEND's pagination over the full matching set — NOT
+ * `items.length`. {@link SyraClient.searchTracks} additionally filters its page
+ * client-side to preview-available tracks, so `items.length` can be smaller than
+ * `limit` while `hasMore` is still `true`; callers must paginate by advancing
+ * `offset` by `limit` (the page size), never by `items.length`.
+ */
+export interface SearchPage<T> {
+    /** The validated rows for this page. */
+    items: T[];
+    /** Whether the backend has results beyond this page. */
+    hasMore: boolean;
+    /** The page size the backend applied. */
+    limit: number;
+    /** The zero-based offset of this page. */
+    offset: number;
 }
 /** Minimal shape from which track artwork URLs can be derived. */
 export interface ArtworkSource {
@@ -40,10 +63,12 @@ export interface PodcastArtworkSource {
 }
 export interface SyraClient {
     /**
-     * Search the public catalog for tracks. Results are validated against the
-     * track-summary schema and filtered to those that expose a public preview.
+     * Search the public catalog for tracks. Returns one paginated page: rows are
+     * validated against the track-summary schema and filtered to those that expose
+     * a public preview. `hasMore` comes from the backend's pagination, so it is
+     * unaffected by the client-side preview filter (see {@link SearchPage}).
      */
-    searchTracks(query: string, options?: SearchTracksOptions): Promise<TrackSummary[]>;
+    searchTracks(query: string, options?: SearchTracksOptions): Promise<SearchPage<TrackSummary>>;
     /** Fetch a single track by id, validated against the track-summary schema. */
     getTrack(id: string): Promise<TrackSummary>;
     /** Build the public 30s preview URL for a track at the given start offset. */
@@ -54,10 +79,11 @@ export interface SyraClient {
      */
     artworkUrl(source: string | ArtworkSource, size?: ArtworkSize): string | undefined;
     /**
-     * Search the public catalog for podcast SHOWS (not episodes). Results are
-     * validated against the podcast-summary schema; malformed rows are dropped.
+     * Search the public catalog for podcast SHOWS (not episodes). Returns one
+     * paginated page: rows are validated against the podcast-summary schema and
+     * malformed rows are dropped. `hasMore` comes from the backend's pagination.
      */
-    searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<PodcastSummary[]>;
+    searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<SearchPage<PodcastSummary>>;
     /**
      * Fetch a single podcast show by id, validated against the podcast-summary
      * schema. The by-id endpoint also returns episodes and resolved persons; this

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export { createSyraClient, DEFAULT_SYRA_BASE_URL, DEFAULT_SYRA_WEB_BASE_URL, } from './client';
-export type { SyraClient, SyraClientOptions, SearchTracksOptions, SearchPodcastsOptions, ArtworkSource, PodcastArtworkSource, } from './client';
+export type { SyraClient, SyraClientOptions, SearchTracksOptions, SearchPodcastsOptions, SearchPage, ArtworkSource, PodcastArtworkSource, } from './client';
 export { trackSummarySchema, podcastSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema';
 export type { TrackSummary, PodcastSummary, CoverArtSizes, CoverArtVariant, ArtworkSize, } from './schema';
 export { SyraApiError } from './errors';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syra.fm/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Headless, isomorphic client for the Syra public API — catalog reads and 30s preview clips. No React/RN/DOM dependencies; public reads only.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/client.test.ts

@@ -70,7 +70,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 +79,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 +100,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 +162,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 +278,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('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 param when not provided', async () => {
+  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 +339,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);
   });
 });
 

package/src/client.ts

@@ -32,13 +32,37 @@ export interface SyraClientOptions {
 }
 
 export interface SearchTracksOptions {
-  /** Maximum number of tracks to request from the API. */
+  /** Maximum number of tracks to request from the API (the page size). */
   limit?: number;
+  /** Zero-based offset of the first track to return (for infinite scroll). */
+  offset?: number;
 }
 
 export interface SearchPodcastsOptions {
-  /** Maximum number of podcast shows to request from the API. */
+  /** Maximum number of podcast shows to request from the API (the page size). */
   limit?: number;
+  /** Zero-based offset of the first show to return (for infinite scroll). */
+  offset?: number;
+}
+
+/**
+ * One page of paginated catalog search results.
+ *
+ * `hasMore` reflects the BACKEND's pagination over the full matching set — NOT
+ * `items.length`. {@link SyraClient.searchTracks} additionally filters its page
+ * client-side to preview-available tracks, so `items.length` can be smaller than
+ * `limit` while `hasMore` is still `true`; callers must paginate by advancing
+ * `offset` by `limit` (the page size), never by `items.length`.
+ */
+export interface SearchPage<T> {
+  /** The validated rows for this page. */
+  items: T[];
+  /** Whether the backend has results beyond this page. */
+  hasMore: boolean;
+  /** The page size the backend applied. */
+  limit: number;
+  /** The zero-based offset of this page. */
+  offset: number;
 }
 
 /** Minimal shape from which track artwork URLs can be derived. */
@@ -56,10 +80,12 @@ export interface PodcastArtworkSource {
 
 export interface SyraClient {
   /**
-   * Search the public catalog for tracks. Results are validated against the
-   * track-summary schema and filtered to those that expose a public preview.
+   * Search the public catalog for tracks. Returns one paginated page: rows are
+   * validated against the track-summary schema and filtered to those that expose
+   * a public preview. `hasMore` comes from the backend's pagination, so it is
+   * unaffected by the client-side preview filter (see {@link SearchPage}).
    */
-  searchTracks(query: string, options?: SearchTracksOptions): Promise<TrackSummary[]>;
+  searchTracks(query: string, options?: SearchTracksOptions): Promise<SearchPage<TrackSummary>>;
   /** Fetch a single track by id, validated against the track-summary schema. */
   getTrack(id: string): Promise<TrackSummary>;
   /** Build the public 30s preview URL for a track at the given start offset. */
@@ -70,10 +96,11 @@ export interface SyraClient {
    */
   artworkUrl(source: string | ArtworkSource, size?: ArtworkSize): string | undefined;
   /**
-   * Search the public catalog for podcast SHOWS (not episodes). Results are
-   * validated against the podcast-summary schema; malformed rows are dropped.
+   * Search the public catalog for podcast SHOWS (not episodes). Returns one
+   * paginated page: rows are validated against the podcast-summary schema and
+   * malformed rows are dropped. `hasMore` comes from the backend's pagination.
    */
-  searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<PodcastSummary[]>;
+  searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<SearchPage<PodcastSummary>>;
   /**
    * Fetch a single podcast show by id, validated against the podcast-summary
    * schema. The by-id endpoint also returns episodes and resolved persons; this
@@ -102,12 +129,23 @@ const ARTWORK_FALLBACK_ORDER: ArtworkSize[] = [
 
 const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
 
+/** Read a finite number from an unknown response field, else a fallback. */
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
 interface SearchResponseShape {
   results?: { tracks?: unknown[] };
+  hasMore?: unknown;
+  limit?: unknown;
+  offset?: unknown;
 }
 
 interface PodcastSearchResponseShape {
   data?: unknown[];
+  hasMore?: unknown;
+  limit?: unknown;
+  offset?: unknown;
 }
 
 interface PodcastDetailResponseShape {
@@ -172,19 +210,32 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
       if (typeof searchOptions.limit === 'number') {
         params.set('limit', String(searchOptions.limit));
       }
+      if (typeof searchOptions.offset === 'number') {
+        params.set('offset', String(searchOptions.offset));
+      }
 
       const json = (await getJson(`/api/search?${params.toString()}`)) as SearchResponseShape;
       const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
 
-      const tracks: TrackSummary[] = [];
+      const items: TrackSummary[] = [];
       for (const raw of rawTracks) {
         // A single malformed catalog row must not fail the whole search.
         const parsed = trackSummarySchema.safeParse(raw);
         if (parsed.success && parsed.data.previewAvailable === true) {
-          tracks.push(parsed.data);
+          items.push(parsed.data);
         }
       }
-      return tracks;
+
+      return {
+        items,
+        // `hasMore` is sourced from the backend's pagination over the FULL result
+        // set; the client-side preview filter above may shrink `items` below
+        // `limit`, but must NOT corrupt `hasMore` (else a page whose tail was
+        // filtered out would falsely report the end of the catalog).
+        hasMore: json?.hasMore === true,
+        limit: numberOr(json?.limit, searchOptions.limit ?? rawTracks.length),
+        offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+      };
     },
 
     async getTrack(id) {
@@ -231,21 +282,31 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
       if (typeof searchOptions.limit === 'number') {
         params.set('limit', String(searchOptions.limit));
       }
+      if (typeof searchOptions.offset === 'number') {
+        params.set('offset', String(searchOptions.offset));
+      }
 
       const json = (await getJson(
         `/api/podcasts/search?${params.toString()}`,
       )) as PodcastSearchResponseShape;
       const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
 
-      const podcasts: PodcastSummary[] = [];
+      const items: PodcastSummary[] = [];
       for (const raw of rawPodcasts) {
         // A single malformed catalog row must not fail the whole search.
         const parsed = podcastSummarySchema.safeParse(raw);
         if (parsed.success) {
-          podcasts.push(parsed.data);
+          items.push(parsed.data);
         }
       }
-      return podcasts;
+
+      return {
+        items,
+        // `hasMore` reflects the backend's pagination over the full result set.
+        hasMore: json?.hasMore === true,
+        limit: numberOr(json?.limit, searchOptions.limit ?? rawPodcasts.length),
+        offset: numberOr(json?.offset, searchOptions.offset ?? 0),
+      };
     },
 
     async getPodcast(id) {

package/src/index.ts

@@ -8,6 +8,7 @@ export type {
   SyraClientOptions,
   SearchTracksOptions,
   SearchPodcastsOptions,
+  SearchPage,
   ArtworkSource,
   PodcastArtworkSource,
 } from './client';