@syra.fm/sdk 0.1.0 → 0.3.0

package/src/client.ts

@@ -1,6 +1,8 @@
 import {
   trackSummarySchema,
+  podcastSummarySchema,
   type TrackSummary,
+  type PodcastSummary,
   type CoverArtSizes,
   type ArtworkSize,
 } from './schema';
@@ -9,9 +11,18 @@ import { SyraApiError } from './errors';
 /** Default base URL of the public Syra API. */
 export const DEFAULT_SYRA_BASE_URL = 'https://api.syra.fm';
 
+/** Default base URL of the Syra web app, used for deep links. */
+export const DEFAULT_SYRA_WEB_BASE_URL = 'https://syra.fm';
+
 export interface SyraClientOptions {
   /** Base URL of the Syra API. Defaults to {@link DEFAULT_SYRA_BASE_URL}. */
   baseURL?: string;
+  /**
+   * Base URL of the Syra WEB app (not the API host), used to build deep links
+   * such as {@link SyraClient.podcastUrl}. Defaults to
+   * {@link DEFAULT_SYRA_WEB_BASE_URL}.
+   */
+  webBaseURL?: string;
   /**
    * `fetch` implementation. Defaults to the global `fetch` (Node 18+, browsers,
    * React Native). Inject one (e.g. `node-fetch`) when no global is available.
@@ -21,22 +32,60 @@ 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 (the page size). */
   limit?: number;
+  /** Zero-based offset of the first show to return (for infinite scroll). */
+  offset?: number;
 }
 
-/** Minimal shape from which artwork URLs can be derived. */
+/**
+ * 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 {
   coverArt?: string | null;
   coverArtSizes?: CoverArtSizes | null;
 }
 
+/** Minimal shape from which podcast-show artwork URLs can be derived. */
+export interface PodcastArtworkSource {
+  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. */
@@ -46,6 +95,26 @@ export interface SyraClient {
    * `undefined` when no artwork can be derived.
    */
   artworkUrl(source: string | ArtworkSource, size?: ArtworkSize): string | undefined;
+  /**
+   * 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<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
+   * returns just the show summary needed to render a card.
+   */
+  getPodcast(id: string): Promise<PodcastSummary>;
+  /** Build the Syra web app deep link for a podcast show (`/podcasts/:id`). */
+  podcastUrl(id: string): string;
+  /**
+   * Resolve an absolute artwork URL from a podcast show 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.
+   */
+  podcastArtworkUrl(source: PodcastArtworkSource, size?: ArtworkSize): string | undefined;
 }
 
 /** Order used to pick the best available artwork variant when none is named. */
@@ -60,8 +129,27 @@ 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 {
+  data?: { podcast?: unknown };
 }
 
 /**
@@ -70,6 +158,7 @@ interface SearchResponseShape {
  */
 export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
   const baseURL = (options.baseURL ?? DEFAULT_SYRA_BASE_URL).replace(/\/+$/, '');
+  const webBaseURL = (options.webBaseURL ?? DEFAULT_SYRA_WEB_BASE_URL).replace(/\/+$/, '');
 
   function resolveFetch(): typeof fetch {
     if (options.fetch) {
@@ -121,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) {
@@ -174,5 +276,73 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
 
       return undefined;
     },
+
+    async searchPodcasts(query, searchOptions = {}) {
+      const params = new URLSearchParams({ q: query });
+      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 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) {
+          items.push(parsed.data);
+        }
+      }
+
+      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)}`,
+      )) as PodcastDetailResponseShape;
+      return podcastSummarySchema.parse(json?.data?.podcast);
+    },
+
+    podcastUrl(id) {
+      return `${webBaseURL}/podcasts/${encodeURIComponent(id)}`;
+    },
+
+    podcastArtworkUrl(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

@@ -1,20 +1,26 @@
 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,

package/src/schema.ts

@@ -48,3 +48,24 @@ export const trackSummarySchema = z.object({
   previewAvailable: z.boolean().optional(),
 });
 export type TrackSummary = z.infer<typeof trackSummarySchema>;
+
+/**
+ * The summary view of a podcast SHOW returned by the public podcast endpoints
+ * (`GET /api/podcasts/search`, `GET /api/podcasts/:id`) — just enough to render
+ * a show card and deep-link into the Syra app.
+ *
+ * Artwork mirrors tracks: `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 podcastSummarySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  author: z.string().optional(),
+  description: z.string().optional(),
+  image: z.string().optional(),
+  imageSizes: coverArtSizesSchema.optional(),
+  imageSourceUrl: z.string().optional(),
+});
+export type PodcastSummary = z.infer<typeof podcastSummarySchema>;