@syra.fm/sdk 0.3.0 → 0.5.0

package/dist/cjs/schema.js

@@ -1,62 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-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
- * SDK consumes. Intentionally NOT shared with the Syra backend's internal
- * types — the SDK validates only the fields it returns, and tolerantly strips
- * everything else (Zod object schemas drop unknown keys by default), so the API
- * can evolve without breaking external consumers.
- */
-/** A single artwork variant. The backend serializes `url` as `/api/images/:id`. */
-exports.coverArtVariantSchema = zod_1.z.object({
-    id: zod_1.z.string().optional(),
-    url: zod_1.z.string(),
-    width: zod_1.z.number().optional(),
-    height: zod_1.z.number().optional(),
-});
-/** Named artwork variants keyed by size. */
-exports.coverArtSizesSchema = zod_1.z.object({
-    small: exports.coverArtVariantSchema.optional(),
-    medium: exports.coverArtVariantSchema.optional(),
-    large: exports.coverArtVariantSchema.optional(),
-    xlarge: exports.coverArtVariantSchema.optional(),
-    xxlarge: exports.coverArtVariantSchema.optional(),
-    original: exports.coverArtVariantSchema.optional(),
-});
-/**
- * The summary view of a track returned by the public catalog endpoints — just
- * enough to render a song row and play its preview.
- */
-exports.trackSummarySchema = zod_1.z.object({
-    id: zod_1.z.string(),
-    title: zod_1.z.string(),
-    artistId: zod_1.z.string().optional(),
-    artistName: zod_1.z.string(),
-    albumId: zod_1.z.string().optional(),
-    albumName: zod_1.z.string().optional(),
-    duration: zod_1.z.number(),
-    coverArt: zod_1.z.string().optional(),
-    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,181 +0,0 @@
-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',
-    'xxlarge',
-    'xlarge',
-    'large',
-    'medium',
-    'small',
-];
-const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
-/** 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);
-        },
-    };
-}

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, coverArtSizesSchema, coverArtVariantSchema, } from './schema.js';
-export { SyraApiError } from './errors.js';

package/dist/esm/package.json

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

package/dist/esm/schema.js

@@ -1,59 +0,0 @@
-import { z } from 'zod';
-/**
- * Minimal, self-contained schemas for the public Syra API response shapes this
- * SDK consumes. Intentionally NOT shared with the Syra backend's internal
- * types — the SDK validates only the fields it returns, and tolerantly strips
- * everything else (Zod object schemas drop unknown keys by default), so the API
- * can evolve without breaking external consumers.
- */
-/** A single artwork variant. The backend serializes `url` as `/api/images/:id`. */
-export const coverArtVariantSchema = z.object({
-    id: z.string().optional(),
-    url: z.string(),
-    width: z.number().optional(),
-    height: z.number().optional(),
-});
-/** Named artwork variants keyed by size. */
-export const coverArtSizesSchema = z.object({
-    small: coverArtVariantSchema.optional(),
-    medium: coverArtVariantSchema.optional(),
-    large: coverArtVariantSchema.optional(),
-    xlarge: coverArtVariantSchema.optional(),
-    xxlarge: coverArtVariantSchema.optional(),
-    original: coverArtVariantSchema.optional(),
-});
-/**
- * The summary view of a track returned by the public catalog endpoints — just
- * enough to render a song row and play its preview.
- */
-export const trackSummarySchema = z.object({
-    id: z.string(),
-    title: z.string(),
-    artistId: z.string().optional(),
-    artistName: z.string(),
-    albumId: z.string().optional(),
-    albumName: z.string().optional(),
-    duration: z.number(),
-    coverArt: z.string().optional(),
-    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/index.d.ts

@@ -1,5 +0,0 @@
-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, } from './schema';
-export { SyraApiError } from './errors';