@syra.fm/sdk 0.1.0 → 0.3.0

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.3.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;
 }
@@ -46,7 +70,7 @@ function fakeFetch(
 // ── searchTracks ──────────────────────────────────────────────────────────────
 
 describe('createSyraClient.searchTracks', () => {
-  it('calls /api/search with category=tracks and the limit, returns preview-available tracks', async () => {
+  it('calls /api/search with category=tracks and the limit, returns a page of preview-available tracks', async () => {
     const { fetch, calls } = fakeFetch(() => ({
       body: {
         results: {
@@ -55,14 +79,20 @@ describe('createSyraClient.searchTracks', () => {
             makeTrack({ id: '507f1f77bcf86cd799439012', previewAvailable: false }),
           ],
         },
+        hasMore: false,
+        limit: 10,
+        offset: 0,
       },
     }));
 
     const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
-    const tracks = await client.searchTracks('hello', { limit: 10 });
+    const page = await client.searchTracks('hello', { limit: 10 });
 
-    expect(tracks).toHaveLength(1);
-    expect(tracks[0].id).toBe('507f1f77bcf86cd799439011');
+    expect(page.items).toHaveLength(1);
+    expect(page.items[0].id).toBe('507f1f77bcf86cd799439011');
+    expect(page.hasMore).toBe(false);
+    expect(page.limit).toBe(10);
+    expect(page.offset).toBe(0);
 
     expect(calls).toHaveLength(1);
     const url = new URL(calls[0].url);
@@ -70,6 +100,53 @@ describe('createSyraClient.searchTracks', () => {
     expect(url.searchParams.get('q')).toBe('hello');
     expect(url.searchParams.get('category')).toBe('tracks');
     expect(url.searchParams.get('limit')).toBe('10');
+    expect(url.searchParams.has('offset')).toBe(false);
+  });
+
+  it('sends the offset param and reports hasMore/offset/limit from the backend', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        results: { tracks: [makeTrack()] },
+        hasMore: true,
+        limit: 20,
+        offset: 40,
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.searchTracks('hello', { limit: 20, offset: 40 });
+
+    expect(page.items).toHaveLength(1);
+    expect(page.hasMore).toBe(true);
+    expect(page.limit).toBe(20);
+    expect(page.offset).toBe(40);
+
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('offset')).toBe('40');
+    expect(url.searchParams.get('limit')).toBe('20');
+  });
+
+  it('reports backend hasMore even when client-side preview filtering empties the page', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: {
+        results: {
+          tracks: [
+            makeTrack({ previewAvailable: false }),
+            makeTrack({ previewAvailable: false }),
+          ],
+        },
+        hasMore: true,
+        limit: 2,
+        offset: 0,
+      },
+    }));
+
+    const client = createSyraClient({ fetch });
+    const page = await client.searchTracks('x', { limit: 2 });
+
+    // All rows were filtered out, but the page is NOT the last one.
+    expect(page.items).toHaveLength(0);
+    expect(page.hasMore).toBe(true);
   });
 
   it('drops malformed rows without throwing', async () => {
@@ -85,14 +162,17 @@ describe('createSyraClient.searchTracks', () => {
     }));
 
     const client = createSyraClient({ fetch });
-    const tracks = await client.searchTracks('x');
-    expect(tracks).toHaveLength(1);
+    const page = await client.searchTracks('x');
+    expect(page.items).toHaveLength(1);
   });
 
-  it('returns an empty array when results.tracks is absent', async () => {
+  it('returns an empty page with hasMore=false when results.tracks is absent', async () => {
     const { fetch } = fakeFetch(() => ({ body: {} }));
     const client = createSyraClient({ fetch });
-    expect(await client.searchTracks('x')).toEqual([]);
+    const page = await client.searchTracks('x');
+    expect(page.items).toEqual([]);
+    expect(page.hasMore).toBe(false);
+    expect(page.offset).toBe(0);
   });
 });
 
@@ -194,3 +274,174 @@ describe('createSyraClient.artworkUrl', () => {
     expect(client.artworkUrl('not-an-id')).toBeUndefined();
   });
 });
+
+// ── searchPodcasts ──────────────────────────────────────────────────────────────
+
+describe('createSyraClient.searchPodcasts', () => {
+  it('calls /api/podcasts/search with q and limit, returns a page of parsed shows', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        data: [
+          makePodcast({ id: '507f1f77bcf86cd799439021' }),
+          makePodcast({ id: '507f1f77bcf86cd799439023', title: 'Second Show' }),
+        ],
+        hasMore: false,
+        limit: 5,
+        offset: 0,
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.searchPodcasts('news', { limit: 5 });
+
+    expect(page.items).toHaveLength(2);
+    expect(page.items[0].id).toBe('507f1f77bcf86cd799439021');
+    expect(page.items[0].author).toBe('Test Publisher');
+    expect(page.hasMore).toBe(false);
+    expect(page.limit).toBe(5);
+    expect(page.offset).toBe(0);
+
+    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');
+    expect(url.searchParams.has('offset')).toBe(false);
+  });
+
+  it('sends the offset param and reports hasMore/offset from the backend', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: { data: [makePodcast()], hasMore: true, limit: 10, offset: 20 },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const page = await client.searchPodcasts('news', { limit: 10, offset: 20 });
+
+    expect(page.hasMore).toBe(true);
+    expect(page.limit).toBe(10);
+    expect(page.offset).toBe(20);
+
+    const url = new URL(calls[0].url);
+    expect(url.searchParams.get('offset')).toBe('20');
+  });
+
+  it('omits the limit and offset params 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);
+    expect(url.searchParams.has('offset')).toBe(false);
+  });
+
+  it('drops malformed rows without throwing', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: { data: [{ id: 'broken' }, makePodcast()] },
+    }));
+    const client = createSyraClient({ fetch });
+    const page = await client.searchPodcasts('x');
+    expect(page.items).toHaveLength(1);
+  });
+
+  it('returns an empty page with hasMore=false when data is absent', async () => {
+    const { fetch } = fakeFetch(() => ({ body: {} }));
+    const client = createSyraClient({ fetch });
+    const page = await client.searchPodcasts('x');
+    expect(page.items).toEqual([]);
+    expect(page.hasMore).toBe(false);
+    expect(page.offset).toBe(0);
+  });
+});
+
+// ── 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();
+  });
+});