@syra.fm/sdk 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @syra.fm/sdk
+
+Headless, isomorphic client for the public [Syra](https://syra.fm) API. Runs on
+Node 18+, browsers, and React Native — no React, React Native, or DOM
+dependencies; the only runtime dependency is [`zod`](https://zod.dev).
+**Public reads only** (no authentication in this version).
+
+## Install
+
+```sh
+bun add @syra.fm/sdk
+```
+
+## Usage
+
+```ts
+import { createSyraClient } from '@syra.fm/sdk';
+
+const syra = createSyraClient(); // defaults to https://api.syra.fm
+
+// Search the catalog (only tracks with a public preview are returned)
+const tracks = await syra.searchTracks('lofi beats', { limit: 10 });
+
+// Fetch a single track
+const track = await syra.getTrack(tracks[0].id);
+
+// Build a public 30s preview URL (directly playable MP3)
+const url = syra.previewUrl(track.id);          // .../api/preview/<id>.mp3?start=0
+const hook = syra.previewUrl(track.id, 45);     // start 45s in
+
+// Resolve artwork to an absolute URL
+const cover = syra.artworkUrl(track, 'large');
+```
+
+## Options
+
+```ts
+createSyraClient({
+  baseURL: 'https://api.syra.fm', // override the API origin
+  fetch,                          // inject a fetch implementation (e.g. node-fetch)
+});
+```
+
+`fetch` defaults to the global `fetch`. It is the seam through which an
+authenticated transport can be layered in a future version.
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `searchTracks(query, { limit })` | Preview-available `TrackSummary[]` matching `query`. |
+| `getTrack(id)` | A single `TrackSummary`, schema-validated. |
+| `previewUrl(id, startSec = 0)` | Public 30s preview URL. |
+| `artworkUrl(trackOrCoverArt, size?)` | Absolute artwork URL, or `undefined`. |
+
+Responses are validated at runtime with the package's own self-contained Zod
+schemas (`trackSummarySchema`), so there are no shared internal dependencies.
+`SyraApiError` (with a `status`) is thrown on non-2xx responses.

package/dist/cjs/client.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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';
+/** 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;
+/**
+ * Create a headless client for the public Syra API. Public reads only — there
+ * is no authentication in this version.
+ */
+function createSyraClient(options = {}) {
+    const baseURL = (options.baseURL ?? exports.DEFAULT_SYRA_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 errors_1.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));
+            }
+            const json = (await getJson(`/api/search?${params.toString()}`));
+            const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
+            const tracks = [];
+            for (const raw of rawTracks) {
+                // A single malformed catalog row must not fail the whole search.
+                const parsed = schema_1.trackSummarySchema.safeParse(raw);
+                if (parsed.success && parsed.data.previewAvailable === true) {
+                    tracks.push(parsed.data);
+                }
+            }
+            return tracks;
+        },
+        async getTrack(id) {
+            const json = await getJson(`/api/tracks/${encodeURIComponent(id)}`);
+            return schema_1.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;
+        },
+    };
+}

package/dist/cjs/errors.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyraApiError = void 0;
+/**
+ * Error thrown when the Syra API returns a non-2xx response.
+ */
+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);
+    }
+}
+exports.SyraApiError = SyraApiError;

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"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;
+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; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "trackSummarySchema", { enumerable: true, get: function () { return schema_1.trackSummarySchema; } });
+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");
+Object.defineProperty(exports, "SyraApiError", { enumerable: true, get: function () { return errors_1.SyraApiError; } });

package/dist/cjs/package.json

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

package/dist/cjs/schema.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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(),
+});

package/dist/esm/client.js

@@ -0,0 +1,108 @@
+import { trackSummarySchema, } 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';
+/** 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;
+/**
+ * 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(/\/+$/, '');
+    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));
+            }
+            const json = (await getJson(`/api/search?${params.toString()}`));
+            const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
+            const tracks = [];
+            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);
+                }
+            }
+            return tracks;
+        },
+        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;
+        },
+    };
+}

package/dist/esm/errors.js

@@ -0,0 +1,12 @@
+/**
+ * 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

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

package/dist/esm/package.json

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

package/dist/esm/schema.js

@@ -0,0 +1,40 @@
+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(),
+});

package/dist/types/client.d.ts

@@ -0,0 +1,43 @@
+import { type TrackSummary, 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";
+export interface SyraClientOptions {
+    /** Base URL of the Syra API. Defaults to {@link DEFAULT_SYRA_BASE_URL}. */
+    baseURL?: string;
+    /**
+     * `fetch` implementation. Defaults to the global `fetch` (Node 18+, browsers,
+     * React Native). Inject one (e.g. `node-fetch`) when no global is available.
+     * This is the seam where an authenticated transport can be layered in later.
+     */
+    fetch?: typeof fetch;
+}
+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 ArtworkSource {
+    coverArt?: string | null;
+    coverArtSizes?: CoverArtSizes | 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.
+     */
+    searchTracks(query: string, options?: SearchTracksOptions): Promise<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. */
+    previewUrl(id: string, startSec?: number): string;
+    /**
+     * Resolve an absolute artwork URL from a track / cover-art reference. Returns
+     * `undefined` when no artwork can be derived.
+     */
+    artworkUrl(source: string | ArtworkSource, size?: ArtworkSize): string | undefined;
+}
+/**
+ * Create a headless client for the public Syra API. Public reads only — there
+ * is no authentication in this version.
+ */
+export declare function createSyraClient(options?: SyraClientOptions): SyraClient;

package/dist/types/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error thrown when the Syra API returns a non-2xx response.
+ */
+export declare class SyraApiError extends Error {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/types/index.d.ts

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