@syra.fm/sdk 0.3.0 → 0.4.0

package/dist/cjs/client.js

@@ -18,6 +18,11 @@ 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;
@@ -181,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,11 @@ 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;
@@ -177,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. */
@@ -31,6 +31,12 @@ export interface SearchPodcastsOptions {
     /** 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.
  *
@@ -61,6 +67,12 @@ 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. Returns one paginated page: rows are
@@ -98,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, SearchPage, 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';

package/dist/types/schema.d.ts

@@ -765,3 +765,307 @@ export declare const podcastSummarySchema: z.ZodObject<{
     imageSourceUrl?: string | undefined;
 }>;
 export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
+/**
+ * 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 declare const episodeSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    podcastId: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enclosureUrl: z.ZodString;
+    enclosureType: z.ZodOptional<z.ZodString>;
+    enclosureLength: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    pubDate: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    imageSizes: z.ZodOptional<z.ZodObject<{
+        small: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        medium: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        large: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        xlarge: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        xxlarge: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        original: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        small?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        medium?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        large?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xxlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        original?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    }, {
+        small?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        medium?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        large?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xxlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        original?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    }>>;
+    imageSourceUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    podcastId: string;
+    enclosureUrl: string;
+    duration?: number | undefined;
+    description?: string | undefined;
+    image?: string | undefined;
+    imageSizes?: {
+        small?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        medium?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        large?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xxlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        original?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    } | undefined;
+    imageSourceUrl?: string | undefined;
+    enclosureType?: string | undefined;
+    enclosureLength?: number | undefined;
+    pubDate?: string | undefined;
+}, {
+    id: string;
+    title: string;
+    podcastId: string;
+    enclosureUrl: string;
+    duration?: number | undefined;
+    description?: string | undefined;
+    image?: string | undefined;
+    imageSizes?: {
+        small?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        medium?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        large?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        xxlarge?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        original?: {
+            url: string;
+            id?: string | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    } | undefined;
+    imageSourceUrl?: string | undefined;
+    enclosureType?: string | undefined;
+    enclosureLength?: number | undefined;
+    pubDate?: string | undefined;
+}>;
+export type EpisodeSummary = z.infer<typeof episodeSummarySchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syra.fm/sdk",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -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;
 }
@@ -445,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();
+  });
+});

package/src/client.ts

@@ -1,8 +1,10 @@
 import {
   trackSummarySchema,
   podcastSummarySchema,
+  episodeSummarySchema,
   type TrackSummary,
   type PodcastSummary,
+  type EpisodeSummary,
   type CoverArtSizes,
   type ArtworkSize,
 } from './schema';
@@ -45,6 +47,13 @@ export interface SearchPodcastsOptions {
   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.
  *
@@ -78,6 +87,13 @@ export interface PodcastArtworkSource {
   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. Returns one paginated page: rows are
@@ -115,6 +131,31 @@ 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;
 }
 
 /** Order used to pick the best available artwork variant when none is named. */
@@ -129,6 +170,12 @@ const ARTWORK_FALLBACK_ORDER: ArtworkSize[] = [
 
 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: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
@@ -152,6 +199,17 @@ interface PodcastDetailResponseShape {
   data?: { podcast?: unknown };
 }
 
+interface PodcastEpisodesResponseShape {
+  data?: unknown[];
+  total?: unknown;
+  page?: unknown;
+  limit?: unknown;
+}
+
+interface EpisodeDetailResponseShape {
+  data?: { episode?: unknown };
+}
+
 /**
  * Create a headless client for the public Syra API. Public reads only — there
  * is no authentication in this version.
@@ -344,5 +402,72 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
 
       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}`,
+      )) as PodcastEpisodesResponseShape;
+      const rawEpisodes = Array.isArray(json?.data) ? json.data : [];
+
+      const items: EpisodeSummary[] = [];
+      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)}`,
+      )) as EpisodeDetailResponseShape;
+      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/src/index.ts

@@ -8,19 +8,23 @@ export type {
   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,

package/src/schema.ts

@@ -69,3 +69,37 @@ export const podcastSummarySchema = z.object({
   imageSourceUrl: z.string().optional(),
 });
 export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
+
+/**
+ * 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(),
+});
+export type EpisodeSummary = z.infer<typeof episodeSummarySchema>;