@syra.fm/sdk 0.2.0 → 0.4.0

package/src/client.ts

@@ -1,8 +1,10 @@
 import {
   trackSummarySchema,
   podcastSummarySchema,
+  episodeSummarySchema,
   type TrackSummary,
   type PodcastSummary,
+  type EpisodeSummary,
   type CoverArtSizes,
   type ArtworkSize,
 } from './schema';
@@ -32,13 +34,44 @@ 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;
+}
+
+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. */
@@ -54,12 +87,21 @@ 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. 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 +112,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
@@ -88,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. */
@@ -102,18 +170,46 @@ 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;
+}
+
 interface SearchResponseShape {
   results?: { tracks?: unknown[] };
+  hasMore?: unknown;
+  limit?: unknown;
+  offset?: unknown;
 }
 
 interface PodcastSearchResponseShape {
   data?: unknown[];
+  hasMore?: unknown;
+  limit?: unknown;
+  offset?: unknown;
 }
 
 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.
@@ -172,19 +268,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 +340,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) {
@@ -283,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,18 +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>;