@syra.fm/sdk 0.4.0 → 0.5.0

package/dist/esm/client.js

@@ -1,240 +0,0 @@
-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';
-/** 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',
-    'xxlarge',
-    'xlarge',
-    'large',
-    'medium',
-    '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;
-}
-/**
- * Create a headless client for the public Syra API. Public reads only — there
- * is no authentication in this version.
- */
-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;
-        }
-        const globalFetch = globalThis.fetch;
-        if (typeof globalFetch === 'function') {
-            return globalFetch.bind(globalThis);
-        }
-        throw new Error('@syra.fm/sdk: no global fetch is available. Pass `fetch` in createSyraClient options, ' +
-            'or run on Node 18+, a browser, or React Native.');
-    }
-    async function getJson(path) {
-        const doFetch = resolveFetch();
-        const response = await doFetch(`${baseURL}${path}`, {
-            headers: { Accept: 'application/json' },
-        });
-        if (!response.ok) {
-            throw new SyraApiError(response.status, `Syra API request failed: ${response.status} ${response.statusText} (${path})`);
-        }
-        return response.json();
-    }
-    function resolveImageRef(ref) {
-        if (!ref) {
-            return undefined;
-        }
-        if (/^https?:\/\//i.test(ref)) {
-            return ref;
-        }
-        if (ref.startsWith('/api/images/')) {
-            return `${baseURL}${ref}`;
-        }
-        if (OBJECT_ID_PATTERN.test(ref)) {
-            return `${baseURL}/api/images/${ref}`;
-        }
-        return undefined;
-    }
-    return {
-        async searchTracks(query, searchOptions = {}) {
-            const params = new URLSearchParams({ q: query, category: 'tracks' });
-            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()}`));
-            const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
-            const items = [];
-            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) {
-                    items.push(parsed.data);
-                }
-            }
-            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) {
-            const json = await getJson(`/api/tracks/${encodeURIComponent(id)}`);
-            return trackSummarySchema.parse(json);
-        },
-        previewUrl(id, startSec = 0) {
-            const safeStart = Number.isFinite(startSec) ? Math.max(0, Math.trunc(startSec)) : 0;
-            return `${baseURL}/api/preview/${encodeURIComponent(id)}.mp3?start=${safeStart}`;
-        },
-        artworkUrl(source, size) {
-            if (typeof source === 'string') {
-                return resolveImageRef(source);
-            }
-            if (size && source.coverArtSizes) {
-                const resolved = resolveImageRef(source.coverArtSizes[size]?.url);
-                if (resolved) {
-                    return resolved;
-                }
-            }
-            const fromCoverArt = resolveImageRef(source.coverArt);
-            if (fromCoverArt) {
-                return fromCoverArt;
-            }
-            if (source.coverArtSizes) {
-                for (const key of ARTWORK_FALLBACK_ORDER) {
-                    const resolved = resolveImageRef(source.coverArtSizes[key]?.url);
-                    if (resolved) {
-                        return resolved;
-                    }
-                }
-            }
-            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()}`));
-            const rawPodcasts = Array.isArray(json?.data) ? json.data : [];
-            const items = [];
-            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)}`));
-            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);
-        },
-        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/errors.js

@@ -1,12 +0,0 @@
-/**
- * Error thrown when the Syra API returns a non-2xx response.
- */
-export class SyraApiError extends Error {
-    constructor(status, message) {
-        super(message);
-        this.name = 'SyraApiError';
-        this.status = status;
-        // Restore the prototype chain when targeting ES5-ish runtimes.
-        Object.setPrototypeOf(this, SyraApiError.prototype);
-    }
-}

package/dist/esm/index.js

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

package/dist/esm/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}