@syra.fm/sdk 0.1.0 → 0.2.0

package/dist/cjs/client.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SYRA_BASE_URL = void 0;
+exports.DEFAULT_SYRA_WEB_BASE_URL = exports.DEFAULT_SYRA_BASE_URL = void 0;
 exports.createSyraClient = createSyraClient;
 const schema_1 = require("./schema");
 const errors_1 = require("./errors");
 /** Default base URL of the public Syra API. */
 exports.DEFAULT_SYRA_BASE_URL = 'https://api.syra.fm';
+/** Default base URL of the Syra web app, used for deep links. */
+exports.DEFAULT_SYRA_WEB_BASE_URL = 'https://syra.fm';
 /** Order used to pick the best available artwork variant when none is named. */
 const ARTWORK_FALLBACK_ORDER = [
     'original',
@@ -22,6 +24,7 @@ const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
  */
 function createSyraClient(options = {}) {
     const baseURL = (options.baseURL ?? exports.DEFAULT_SYRA_BASE_URL).replace(/\/+$/, '');
+    const webBaseURL = (options.webBaseURL ?? exports.DEFAULT_SYRA_WEB_BASE_URL).replace(/\/+$/, '');
     function resolveFetch() {
         if (options.fetch) {
             return options.fetch;
@@ -108,5 +111,50 @@ function createSyraClient(options = {}) {
             }
             return undefined;
         },
+        async searchPodcasts(query, searchOptions = {}) {
+            const params = new URLSearchParams({ q: query });
+            if (typeof searchOptions.limit === 'number') {
+                params.set('limit', String(searchOptions.limit));
+            }
+            const json = (await getJson(`/api/podcasts/search?${params.toString()}`));
+            const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
+            const podcasts = [];
+            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);
+                }
+            }
+            return podcasts;
+        },
+        async getPodcast(id) {
+            const json = (await getJson(`/api/podcasts/${encodeURIComponent(id)}`));
+            return schema_1.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/dist/cjs/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SyraApiError = exports.coverArtVariantSchema = exports.coverArtSizesSchema = exports.trackSummarySchema = exports.DEFAULT_SYRA_BASE_URL = exports.createSyraClient = void 0;
+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;
 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; } });
+Object.defineProperty(exports, "DEFAULT_SYRA_WEB_BASE_URL", { enumerable: true, get: function () { return client_1.DEFAULT_SYRA_WEB_BASE_URL; } });
 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, "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.trackSummarySchema = exports.coverArtSizesSchema = exports.coverArtVariantSchema = void 0;
+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
@@ -41,3 +41,22 @@ exports.trackSummarySchema = zod_1.z.object({
     coverArtSizes: exports.coverArtSizesSchema.optional(),
     previewAvailable: zod_1.z.boolean().optional(),
 });
+/**
+ * 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.
+ */
+exports.podcastSummarySchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    title: zod_1.z.string(),
+    author: zod_1.z.string().optional(),
+    description: 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,7 +1,9 @@
-import { trackSummarySchema, } from './schema.js';
+import { trackSummarySchema, podcastSummarySchema, } 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';
+/** Default base URL of the Syra web app, used for deep links. */
+export const DEFAULT_SYRA_WEB_BASE_URL = 'https://syra.fm';
 /** Order used to pick the best available artwork variant when none is named. */
 const ARTWORK_FALLBACK_ORDER = [
     'original',
@@ -18,6 +20,7 @@ const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
  */
 export function createSyraClient(options = {}) {
     const baseURL = (options.baseURL ?? DEFAULT_SYRA_BASE_URL).replace(/\/+$/, '');
+    const webBaseURL = (options.webBaseURL ?? DEFAULT_SYRA_WEB_BASE_URL).replace(/\/+$/, '');
     function resolveFetch() {
         if (options.fetch) {
             return options.fetch;
@@ -104,5 +107,50 @@ export function createSyraClient(options = {}) {
             }
             return undefined;
         },
+        async searchPodcasts(query, searchOptions = {}) {
+            const params = new URLSearchParams({ q: query });
+            if (typeof searchOptions.limit === 'number') {
+                params.set('limit', String(searchOptions.limit));
+            }
+            const json = (await getJson(`/api/podcasts/search?${params.toString()}`));
+            const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
+            const podcasts = [];
+            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);
+                }
+            }
+            return podcasts;
+        },
+        async getPodcast(id) {
+            const json = (await getJson(`/api/podcasts/${encodeURIComponent(id)}`));
+            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/dist/esm/index.js

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

package/dist/esm/schema.js

@@ -38,3 +38,22 @@ export const trackSummarySchema = z.object({
     coverArtSizes: coverArtSizesSchema.optional(),
     previewAvailable: z.boolean().optional(),
 });
+/**
+ * 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(),
+});

package/dist/types/client.d.ts

@@ -1,9 +1,17 @@
-import { type TrackSummary, type CoverArtSizes, type ArtworkSize } from './schema';
+import { type TrackSummary, type PodcastSummary, 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. */
+export declare 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.
@@ -15,11 +23,21 @@ export interface SearchTracksOptions {
     /** Maximum number of tracks to request from the API. */
     limit?: number;
 }
-/** Minimal shape from which artwork URLs can be derived. */
+export interface SearchPodcastsOptions {
+    /** Maximum number of podcast shows to request from the API. */
+    limit?: 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
@@ -35,6 +53,25 @@ 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). Results are
+     * validated against the podcast-summary schema; malformed rows are dropped.
+     */
+    searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<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;
 }
 /**
  * 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, } from './client';
-export type { SyraClient, SyraClientOptions, SearchTracksOptions, ArtworkSource, } from './client';
-export { trackSummarySchema, coverArtSizesSchema, coverArtVariantSchema, } from './schema';
-export type { TrackSummary, CoverArtSizes, CoverArtVariant, ArtworkSize, } from './schema';
+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 { SyraApiError } from './errors';

package/dist/types/schema.d.ts

@@ -484,3 +484,284 @@ export declare const trackSummarySchema: z.ZodObject<{
     previewAvailable?: boolean | undefined;
 }>;
 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 declare const podcastSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    description: 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;
+    author?: string | 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;
+}, {
+    id: string;
+    title: string;
+    author?: string | 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;
+}>;
+export type PodcastSummary = z.infer<typeof podcastSummarySchema>;

package/package.json

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

@@ -1,5 +1,10 @@
 import { describe, it, expect } from 'bun:test';
-import { createSyraClient, SyraApiError, DEFAULT_SYRA_BASE_URL } from './index';
+import {
+  createSyraClient,
+  SyraApiError,
+  DEFAULT_SYRA_BASE_URL,
+  DEFAULT_SYRA_WEB_BASE_URL,
+} from './index';
 
 // ── Fixtures ──────────────────────────────────────────────────────────────────
 
@@ -21,6 +26,25 @@ function makeTrack(overrides: Record<string, unknown> = {}): Record<string, unkn
   };
 }
 
+function makePodcast(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: '507f1f77bcf86cd799439021',
+    title: 'Test Show',
+    author: 'Test Publisher',
+    description: 'A show about testing.',
+    image: '507f1f77bcf86cd799439022',
+    explicit: false,
+    type: 'episodic',
+    source: 'rss',
+    refreshIntervalMin: 60,
+    episodeCount: 12,
+    status: 'active',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
 interface FetchCall {
   url: string;
 }
@@ -194,3 +218,147 @@ describe('createSyraClient.artworkUrl', () => {
     expect(client.artworkUrl('not-an-id')).toBeUndefined();
   });
 });
+
+// ── searchPodcasts ──────────────────────────────────────────────────────────────
+
+describe('createSyraClient.searchPodcasts', () => {
+  it('calls /api/podcasts/search with q and limit, returns parsed shows', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        data: [
+          makePodcast({ id: '507f1f77bcf86cd799439021' }),
+          makePodcast({ id: '507f1f77bcf86cd799439023', title: 'Second Show' }),
+        ],
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const podcasts = await client.searchPodcasts('news', { limit: 5 });
+
+    expect(podcasts).toHaveLength(2);
+    expect(podcasts[0].id).toBe('507f1f77bcf86cd799439021');
+    expect(podcasts[0].author).toBe('Test Publisher');
+
+    expect(calls).toHaveLength(1);
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe('/api/podcasts/search');
+    expect(url.searchParams.get('q')).toBe('news');
+    expect(url.searchParams.get('limit')).toBe('5');
+  });
+
+  it('omits the limit param when not provided', async () => {
+    const { fetch, calls } = fakeFetch(() => ({ body: { data: [makePodcast()] } }));
+    const client = createSyraClient({ fetch });
+    await client.searchPodcasts('news');
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.has('limit')).toBe(false);
+  });
+
+  it('drops malformed rows without throwing', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: { data: [{ id: 'broken' }, makePodcast()] },
+    }));
+    const client = createSyraClient({ fetch });
+    const podcasts = await client.searchPodcasts('x');
+    expect(podcasts).toHaveLength(1);
+  });
+
+  it('returns an empty array when data is absent', async () => {
+    const { fetch } = fakeFetch(() => ({ body: {} }));
+    const client = createSyraClient({ fetch });
+    expect(await client.searchPodcasts('x')).toEqual([]);
+  });
+});
+
+// ── getPodcast ──────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.getPodcast', () => {
+  it('fetches /api/podcasts/:id and validates data.podcast', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: { data: { podcast: makePodcast(), episodes: [], persons: [] } },
+    }));
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+
+    const podcast = await client.getPodcast('507f1f77bcf86cd799439021');
+    expect(podcast.title).toBe('Test Show');
+    expect(calls[0].url).toBe('https://api.example.test/api/podcasts/507f1f77bcf86cd799439021');
+  });
+
+  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.getPodcast('507f1f77bcf86cd799439021')).rejects.toBeInstanceOf(SyraApiError);
+  });
+
+  it('throws when data.podcast fails schema validation', async () => {
+    const { fetch } = fakeFetch(() => ({ body: { data: { podcast: { id: 'x' } } } }));
+    const client = createSyraClient({ fetch });
+    await expect(client.getPodcast('x')).rejects.toThrow();
+  });
+});
+
+// ── podcastUrl ────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.podcastUrl', () => {
+  it('builds the web deep link from the web base URL, not the API host', () => {
+    const client = createSyraClient({
+      baseURL: 'https://api.example.test',
+      webBaseURL: 'https://web.example.test',
+    });
+    expect(client.podcastUrl('507f1f77bcf86cd799439021')).toBe(
+      'https://web.example.test/podcasts/507f1f77bcf86cd799439021',
+    );
+  });
+
+  it('defaults to the production web base URL', () => {
+    const client = createSyraClient();
+    expect(client.podcastUrl('abc')).toBe(`${DEFAULT_SYRA_WEB_BASE_URL}/podcasts/abc`);
+  });
+
+  it('does not use the API base URL for the deep link', () => {
+    const client = createSyraClient({ baseURL: 'https://api.example.test' });
+    expect(client.podcastUrl('abc')).toBe(`${DEFAULT_SYRA_WEB_BASE_URL}/podcasts/abc`);
+    expect(DEFAULT_SYRA_WEB_BASE_URL).not.toBe(DEFAULT_SYRA_BASE_URL);
+  });
+});
+
+// ── podcastArtworkUrl ────────────────────────────────────────────────────────────
+
+describe('createSyraClient.podcastArtworkUrl', () => {
+  const client = createSyraClient({ baseURL: 'https://api.example.test' });
+
+  it('resolves the re-hosted image id to an absolute images URL', () => {
+    expect(client.podcastArtworkUrl({ image: '507f1f77bcf86cd799439022' })).toBe(
+      'https://api.example.test/api/images/507f1f77bcf86cd799439022',
+    );
+  });
+
+  it('prefers a named size from imageSizes', () => {
+    const url = client.podcastArtworkUrl(
+      {
+        image: '507f1f77bcf86cd799439022',
+        imageSizes: {
+          large: {
+            id: '507f1f77bcf86cd799439023',
+            url: '/api/images/507f1f77bcf86cd799439023',
+            width: 640,
+            height: 640,
+          },
+        },
+      },
+      'large',
+    );
+    expect(url).toBe('https://api.example.test/api/images/507f1f77bcf86cd799439023');
+  });
+
+  it('falls back to imageSourceUrl when no Syra image is present', () => {
+    expect(
+      client.podcastArtworkUrl({ imageSourceUrl: 'https://cdn.example.com/cover.jpg' }),
+    ).toBe('https://cdn.example.com/cover.jpg');
+  });
+
+  it('returns undefined when nothing resolvable is present', () => {
+    expect(client.podcastArtworkUrl({})).toBeUndefined();
+    expect(client.podcastArtworkUrl({ image: 'not-an-id' })).toBeUndefined();
+  });
+});

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.
@@ -25,12 +36,24 @@ export interface SearchTracksOptions {
   limit?: number;
 }
 
-/** Minimal shape from which artwork URLs can be derived. */
+export interface SearchPodcastsOptions {
+  /** Maximum number of podcast shows to request from the API. */
+  limit?: 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
@@ -46,6 +69,25 @@ 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). Results are
+   * validated against the podcast-summary schema; malformed rows are dropped.
+   */
+  searchPodcasts(query: string, options?: SearchPodcastsOptions): Promise<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. */
@@ -64,12 +106,21 @@ interface SearchResponseShape {
   results?: { tracks?: unknown[] };
 }
 
+interface PodcastSearchResponseShape {
+  data?: unknown[];
+}
+
+interface PodcastDetailResponseShape {
+  data?: { podcast?: unknown };
+}
+
 /**
  * Create a headless client for the public Syra API. Public reads only — there
  * is no authentication in this version.
  */
 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) {
@@ -174,5 +225,63 @@ 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));
+      }
+
+      const json = (await getJson(
+        `/api/podcasts/search?${params.toString()}`,
+      )) as PodcastSearchResponseShape;
+      const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
+
+      const podcasts: 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);
+        }
+      }
+      return podcasts;
+    },
+
+    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,25 @@
 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,

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>;