@syra.fm/sdk 0.2.0 → 0.4.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,15 @@ const ARTWORK_FALLBACK_ORDER = [
     'small',
 ];
 const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
+/**
+ * Default episode page size, matching the backend's own default so the SDK's
+ * offset→page translation lines up with the server's pagination window.
+ */
+const DEFAULT_EPISODES_PAGE_SIZE = 20;
+/** 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 +76,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 +137,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)}`));
@@ -156,5 +186,59 @@ function createSyraClient(options = {}) {
             }
             return resolveImageRef(source.imageSourceUrl);
         },
+        async getPodcastEpisodes(podcastId, listOptions = {}) {
+            // The endpoint paginates by 1-based `page`; translate the SDK's uniform
+            // offset-based paging into it. `limit` must be concrete (unlike search,
+            // which can omit it) because the page number is derived from it.
+            const limit = listOptions.limit ?? DEFAULT_EPISODES_PAGE_SIZE;
+            const offset = listOptions.offset ?? 0;
+            const page = Math.floor(offset / limit) + 1;
+            const json = (await getJson(`/api/podcasts/${encodeURIComponent(podcastId)}/episodes?page=${page}&limit=${limit}`));
+            const rawEpisodes = Array.isArray(json?.data) ? json.data : [];
+            const items = [];
+            for (const raw of rawEpisodes) {
+                // A single malformed episode row must not fail the whole listing.
+                const parsed = schema_1.episodeSummarySchema.safeParse(raw);
+                if (parsed.success) {
+                    items.push(parsed.data);
+                }
+            }
+            // `total` is the backend's full count over the show; derive `hasMore` from
+            // it rather than `items.length`, which the schema/enclosure filter above may
+            // shrink below `limit` on a page that is NOT the last one. Absent a count,
+            // fall back to what we have (this page ends the listing).
+            const total = numberOr(json?.total, offset + items.length);
+            return {
+                items,
+                hasMore: page * limit < total,
+                limit,
+                offset,
+            };
+        },
+        async getEpisode(episodeId) {
+            const json = (await getJson(`/api/episodes/${encodeURIComponent(episodeId)}`));
+            return schema_1.episodeSummarySchema.parse(json?.data?.episode);
+        },
+        episodeImageUrl(source, size) {
+            if (size && source.imageSizes) {
+                const resolved = resolveImageRef(source.imageSizes[size]?.url);
+                if (resolved) {
+                    return resolved;
+                }
+            }
+            const fromImage = resolveImageRef(source.image);
+            if (fromImage) {
+                return fromImage;
+            }
+            if (source.imageSizes) {
+                for (const key of ARTWORK_FALLBACK_ORDER) {
+                    const resolved = resolveImageRef(source.imageSizes[key]?.url);
+                    if (resolved) {
+                        return resolved;
+                    }
+                }
+            }
+            return resolveImageRef(source.imageSourceUrl);
+        },
     };
 }

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SyraApiError = exports.coverArtVariantSchema = exports.coverArtSizesSchema = exports.podcastSummarySchema = exports.trackSummarySchema = exports.DEFAULT_SYRA_WEB_BASE_URL = exports.DEFAULT_SYRA_BASE_URL = exports.createSyraClient = void 0;
+exports.SyraApiError = exports.coverArtVariantSchema = exports.coverArtSizesSchema = exports.episodeSummarySchema = exports.podcastSummarySchema = exports.trackSummarySchema = exports.DEFAULT_SYRA_WEB_BASE_URL = exports.DEFAULT_SYRA_BASE_URL = exports.createSyraClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createSyraClient", { enumerable: true, get: function () { return client_1.createSyraClient; } });
 Object.defineProperty(exports, "DEFAULT_SYRA_BASE_URL", { enumerable: true, get: function () { return client_1.DEFAULT_SYRA_BASE_URL; } });
@@ -8,6 +8,7 @@ Object.defineProperty(exports, "DEFAULT_SYRA_WEB_BASE_URL", { enumerable: true,
 var schema_1 = require("./schema");
 Object.defineProperty(exports, "trackSummarySchema", { enumerable: true, get: function () { return schema_1.trackSummarySchema; } });
 Object.defineProperty(exports, "podcastSummarySchema", { enumerable: true, get: function () { return schema_1.podcastSummarySchema; } });
+Object.defineProperty(exports, "episodeSummarySchema", { enumerable: true, get: function () { return schema_1.episodeSummarySchema; } });
 Object.defineProperty(exports, "coverArtSizesSchema", { enumerable: true, get: function () { return schema_1.coverArtSizesSchema; } });
 Object.defineProperty(exports, "coverArtVariantSchema", { enumerable: true, get: function () { return schema_1.coverArtVariantSchema; } });
 var errors_1 = require("./errors");

package/dist/cjs/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.podcastSummarySchema = exports.trackSummarySchema = exports.coverArtSizesSchema = exports.coverArtVariantSchema = void 0;
+exports.episodeSummarySchema = exports.podcastSummarySchema = exports.trackSummarySchema = exports.coverArtSizesSchema = exports.coverArtVariantSchema = void 0;
 const zod_1 = require("zod");
 /**
  * Minimal, self-contained schemas for the public Syra API response shapes this
@@ -60,3 +60,35 @@ exports.podcastSummarySchema = zod_1.z.object({
     imageSizes: exports.coverArtSizesSchema.optional(),
     imageSourceUrl: zod_1.z.string().optional(),
 });
+/**
+ * The summary view of a podcast EPISODE returned by the public podcast endpoints
+ * (`GET /api/podcasts/:id/episodes`, `GET /api/episodes/:id`) — just enough to
+ * list an episode and stream its audio.
+ *
+ * `enclosureUrl` is the direct audio file URL (e.g.
+ * `https://api.fastcast.ai/audio/<guid>.mp3`) and is REQUIRED: an episode with
+ * no enclosure is unplayable, so a row missing it is treated as malformed and
+ * dropped rather than surfaced as a dead entry. `enclosureType` /
+ * `enclosureLength` describe that file (MIME type and byte length); `duration`
+ * is the runtime in seconds and `pubDate` the ISO publish timestamp.
+ *
+ * Artwork mirrors the podcast SHOW: `image` is the re-hosted Syra image id
+ * (resolved via `/api/images/:id`); `imageSizes` is the multi-resolution variant
+ * set (each variant `url` is `/api/images/:id`); `imageSourceUrl` keeps the
+ * original external artwork URL as an absolute fallback when re-hosting has not
+ * run yet.
+ */
+exports.episodeSummarySchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    podcastId: zod_1.z.string(),
+    title: zod_1.z.string(),
+    description: zod_1.z.string().optional(),
+    enclosureUrl: zod_1.z.string(),
+    enclosureType: zod_1.z.string().optional(),
+    enclosureLength: zod_1.z.number().optional(),
+    duration: zod_1.z.number().optional(),
+    pubDate: zod_1.z.string().optional(),
+    image: zod_1.z.string().optional(),
+    imageSizes: exports.coverArtSizesSchema.optional(),
+    imageSourceUrl: zod_1.z.string().optional(),
+});

package/dist/esm/client.js

@@ -1,4 +1,4 @@
-import { trackSummarySchema, podcastSummarySchema, } from './schema.js';
+import { trackSummarySchema, podcastSummarySchema, episodeSummarySchema, } from './schema.js';
 import { SyraApiError } from './errors.js';
 /** Default base URL of the public Syra API. */
 export const DEFAULT_SYRA_BASE_URL = 'https://api.syra.fm';
@@ -14,6 +14,15 @@ const ARTWORK_FALLBACK_ORDER = [
     'small',
 ];
 const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
+/**
+ * Default episode page size, matching the backend's own default so the SDK's
+ * offset→page translation lines up with the server's pagination window.
+ */
+const DEFAULT_EPISODES_PAGE_SIZE = 20;
+/** 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 +72,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 +133,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)}`));
@@ -152,5 +182,59 @@ export function createSyraClient(options = {}) {
             }
             return resolveImageRef(source.imageSourceUrl);
         },
+        async getPodcastEpisodes(podcastId, listOptions = {}) {
+            // The endpoint paginates by 1-based `page`; translate the SDK's uniform
+            // offset-based paging into it. `limit` must be concrete (unlike search,
+            // which can omit it) because the page number is derived from it.
+            const limit = listOptions.limit ?? DEFAULT_EPISODES_PAGE_SIZE;
+            const offset = listOptions.offset ?? 0;
+            const page = Math.floor(offset / limit) + 1;
+            const json = (await getJson(`/api/podcasts/${encodeURIComponent(podcastId)}/episodes?page=${page}&limit=${limit}`));
+            const rawEpisodes = Array.isArray(json?.data) ? json.data : [];
+            const items = [];
+            for (const raw of rawEpisodes) {
+                // A single malformed episode row must not fail the whole listing.
+                const parsed = episodeSummarySchema.safeParse(raw);
+                if (parsed.success) {
+                    items.push(parsed.data);
+                }
+            }
+            // `total` is the backend's full count over the show; derive `hasMore` from
+            // it rather than `items.length`, which the schema/enclosure filter above may
+            // shrink below `limit` on a page that is NOT the last one. Absent a count,
+            // fall back to what we have (this page ends the listing).
+            const total = numberOr(json?.total, offset + items.length);
+            return {
+                items,
+                hasMore: page * limit < total,
+                limit,
+                offset,
+            };
+        },
+        async getEpisode(episodeId) {
+            const json = (await getJson(`/api/episodes/${encodeURIComponent(episodeId)}`));
+            return episodeSummarySchema.parse(json?.data?.episode);
+        },
+        episodeImageUrl(source, size) {
+            if (size && source.imageSizes) {
+                const resolved = resolveImageRef(source.imageSizes[size]?.url);
+                if (resolved) {
+                    return resolved;
+                }
+            }
+            const fromImage = resolveImageRef(source.image);
+            if (fromImage) {
+                return fromImage;
+            }
+            if (source.imageSizes) {
+                for (const key of ARTWORK_FALLBACK_ORDER) {
+                    const resolved = resolveImageRef(source.imageSizes[key]?.url);
+                    if (resolved) {
+                        return resolved;
+                    }
+                }
+            }
+            return resolveImageRef(source.imageSourceUrl);
+        },
     };
 }

package/dist/esm/index.js

@@ -1,3 +1,3 @@
 export { createSyraClient, DEFAULT_SYRA_BASE_URL, DEFAULT_SYRA_WEB_BASE_URL, } from './client.js';
-export { trackSummarySchema, podcastSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema.js';
+export { trackSummarySchema, podcastSummarySchema, episodeSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema.js';
 export { SyraApiError } from './errors.js';

package/dist/esm/schema.js

@@ -57,3 +57,35 @@ export const podcastSummarySchema = z.object({
     imageSizes: coverArtSizesSchema.optional(),
     imageSourceUrl: z.string().optional(),
 });
+/**
+ * The summary view of a podcast EPISODE returned by the public podcast endpoints
+ * (`GET /api/podcasts/:id/episodes`, `GET /api/episodes/:id`) — just enough to
+ * list an episode and stream its audio.
+ *
+ * `enclosureUrl` is the direct audio file URL (e.g.
+ * `https://api.fastcast.ai/audio/<guid>.mp3`) and is REQUIRED: an episode with
+ * no enclosure is unplayable, so a row missing it is treated as malformed and
+ * dropped rather than surfaced as a dead entry. `enclosureType` /
+ * `enclosureLength` describe that file (MIME type and byte length); `duration`
+ * is the runtime in seconds and `pubDate` the ISO publish timestamp.
+ *
+ * Artwork mirrors the podcast SHOW: `image` is the re-hosted Syra image id
+ * (resolved via `/api/images/:id`); `imageSizes` is the multi-resolution variant
+ * set (each variant `url` is `/api/images/:id`); `imageSourceUrl` keeps the
+ * original external artwork URL as an absolute fallback when re-hosting has not
+ * run yet.
+ */
+export const episodeSummarySchema = z.object({
+    id: z.string(),
+    podcastId: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    enclosureUrl: z.string(),
+    enclosureType: z.string().optional(),
+    enclosureLength: z.number().optional(),
+    duration: z.number().optional(),
+    pubDate: z.string().optional(),
+    image: z.string().optional(),
+    imageSizes: coverArtSizesSchema.optional(),
+    imageSourceUrl: z.string().optional(),
+});

package/dist/types/client.d.ts

@@ -1,4 +1,4 @@
-import { type TrackSummary, type PodcastSummary, type CoverArtSizes, type ArtworkSize } from './schema';
+import { type TrackSummary, type PodcastSummary, type EpisodeSummary, type CoverArtSizes, type ArtworkSize } from './schema';
 /** Default base URL of the public Syra API. */
 export declare const DEFAULT_SYRA_BASE_URL = "https://api.syra.fm";
 /** Default base URL of the Syra web app, used for deep links. */
@@ -20,12 +20,41 @@ 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;
+}
+export interface PodcastEpisodesOptions {
+    /** Maximum number of episodes to request from the API (the page size). */
+    limit?: number;
+    /** Zero-based offset of the first episode 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 {
@@ -38,12 +67,20 @@ export interface PodcastArtworkSource {
     imageSizes?: CoverArtSizes | null;
     imageSourceUrl?: string | null;
 }
+/** Minimal shape from which podcast-episode artwork URLs can be derived. */
+export interface EpisodeArtworkSource {
+    image?: string | null;
+    imageSizes?: CoverArtSizes | null;
+    imageSourceUrl?: string | null;
+}
 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 +91,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
@@ -72,6 +110,28 @@ export interface SyraClient {
      * external artwork URL. Returns `undefined` when no artwork can be derived.
      */
     podcastArtworkUrl(source: PodcastArtworkSource, size?: ArtworkSize): string | undefined;
+    /**
+     * List a podcast show's EPISODES (newest first, as the backend orders them).
+     * Returns one paginated page: rows are validated against the episode-summary
+     * schema and malformed rows are dropped — including any without a playable
+     * `enclosureUrl`, which the schema requires. The backend paginates by 1-based
+     * `page`, but this keeps the uniform offset-based {@link SearchPage} for parity
+     * with {@link SyraClient.searchPodcasts}; paginate by advancing `offset` by
+     * `limit` (the page size), never by `items.length`.
+     */
+    getPodcastEpisodes(podcastId: string, options?: PodcastEpisodesOptions): Promise<SearchPage<EpisodeSummary>>;
+    /**
+     * Fetch a single episode by id, validated against the episode-summary schema.
+     * The by-id endpoint nests the episode under `data.episode` alongside resolved
+     * persons; this returns just the episode summary needed to stream its audio.
+     */
+    getEpisode(episodeId: string): Promise<EpisodeSummary>;
+    /**
+     * Resolve an absolute artwork URL from a podcast episode reference. Prefers the
+     * re-hosted Syra image, then the requested/fallback variant, then the original
+     * external artwork URL. Returns `undefined` when no artwork can be derived.
+     */
+    episodeImageUrl(source: EpisodeArtworkSource, size?: ArtworkSize): string | undefined;
 }
 /**
  * Create a headless client for the public Syra API. Public reads only — there

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 { trackSummarySchema, podcastSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema';
-export type { TrackSummary, PodcastSummary, CoverArtSizes, CoverArtVariant, ArtworkSize, } from './schema';
+export type { SyraClient, SyraClientOptions, SearchTracksOptions, SearchPodcastsOptions, PodcastEpisodesOptions, SearchPage, ArtworkSource, PodcastArtworkSource, EpisodeArtworkSource, } from './client';
+export { trackSummarySchema, podcastSummarySchema, episodeSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema';
+export type { TrackSummary, PodcastSummary, EpisodeSummary, CoverArtSizes, CoverArtVariant, ArtworkSize, } from './schema';
 export { SyraApiError } from './errors';