@syra.fm/sdk 0.1.0

package/src/client.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect } from 'bun:test';
+import { createSyraClient, SyraApiError, DEFAULT_SYRA_BASE_URL } from './index';
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+function makeTrack(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: '507f1f77bcf86cd799439011',
+    title: 'Test Track',
+    artistId: 'artist-1',
+    artistName: 'Test Artist',
+    duration: 180,
+    isExplicit: false,
+    isAvailable: true,
+    source: 'upload',
+    status: 'ready',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    previewAvailable: true,
+    ...overrides,
+  };
+}
+
+interface FetchCall {
+  url: string;
+}
+
+function fakeFetch(
+  handler: (url: string) => { status?: number; body: unknown },
+): { fetch: typeof fetch; calls: FetchCall[] } {
+  const calls: FetchCall[] = [];
+  const fetchImpl = (async (input: string | URL | Request) => {
+    const url = typeof input === 'string' ? input : input.toString();
+    calls.push({ url });
+    const { status = 200, body } = handler(url);
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      statusText: status === 200 ? 'OK' : 'Error',
+      json: async () => body,
+    } as Response;
+  }) as typeof fetch;
+  return { fetch: fetchImpl, calls };
+}
+
+// ── searchTracks ──────────────────────────────────────────────────────────────
+
+describe('createSyraClient.searchTracks', () => {
+  it('calls /api/search with category=tracks and the limit, returns preview-available tracks', async () => {
+    const { fetch, calls } = fakeFetch(() => ({
+      body: {
+        results: {
+          tracks: [
+            makeTrack({ id: '507f1f77bcf86cd799439011', previewAvailable: true }),
+            makeTrack({ id: '507f1f77bcf86cd799439012', previewAvailable: false }),
+          ],
+        },
+      },
+    }));
+
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+    const tracks = await client.searchTracks('hello', { limit: 10 });
+
+    expect(tracks).toHaveLength(1);
+    expect(tracks[0].id).toBe('507f1f77bcf86cd799439011');
+
+    expect(calls).toHaveLength(1);
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe('/api/search');
+    expect(url.searchParams.get('q')).toBe('hello');
+    expect(url.searchParams.get('category')).toBe('tracks');
+    expect(url.searchParams.get('limit')).toBe('10');
+  });
+
+  it('drops malformed rows without throwing', async () => {
+    const { fetch } = fakeFetch(() => ({
+      body: {
+        results: {
+          tracks: [
+            { id: 'broken' }, // missing required fields → safeParse fails
+            makeTrack({ previewAvailable: true }),
+          ],
+        },
+      },
+    }));
+
+    const client = createSyraClient({ fetch });
+    const tracks = await client.searchTracks('x');
+    expect(tracks).toHaveLength(1);
+  });
+
+  it('returns an empty array when results.tracks is absent', async () => {
+    const { fetch } = fakeFetch(() => ({ body: {} }));
+    const client = createSyraClient({ fetch });
+    expect(await client.searchTracks('x')).toEqual([]);
+  });
+});
+
+// ── getTrack ──────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.getTrack', () => {
+  it('fetches /api/tracks/:id and validates the response', async () => {
+    const { fetch, calls } = fakeFetch(() => ({ body: makeTrack() }));
+    const client = createSyraClient({ baseURL: 'https://api.example.test', fetch });
+
+    const track = await client.getTrack('507f1f77bcf86cd799439011');
+    expect(track.title).toBe('Test Track');
+    expect(calls[0].url).toBe('https://api.example.test/api/tracks/507f1f77bcf86cd799439011');
+  });
+
+  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.getTrack('507f1f77bcf86cd799439011')).rejects.toBeInstanceOf(SyraApiError);
+  });
+
+  it('throws when the response fails schema validation', async () => {
+    const { fetch } = fakeFetch(() => ({ body: { id: 'x' } }));
+    const client = createSyraClient({ fetch });
+    await expect(client.getTrack('x')).rejects.toThrow();
+  });
+});
+
+// ── previewUrl ────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.previewUrl', () => {
+  it('builds the preview URL with a default start of 0', () => {
+    const client = createSyraClient({ baseURL: 'https://api.example.test' });
+    expect(client.previewUrl('abc')).toBe('https://api.example.test/api/preview/abc.mp3?start=0');
+  });
+
+  it('uses the provided start offset and clamps to an integer >= 0', () => {
+    const client = createSyraClient({ baseURL: 'https://api.example.test' });
+    expect(client.previewUrl('abc', 42.9)).toBe('https://api.example.test/api/preview/abc.mp3?start=42');
+    expect(client.previewUrl('abc', -5)).toBe('https://api.example.test/api/preview/abc.mp3?start=0');
+  });
+
+  it('defaults to the production base URL', () => {
+    const client = createSyraClient();
+    expect(client.previewUrl('abc')).toBe(`${DEFAULT_SYRA_BASE_URL}/api/preview/abc.mp3?start=0`);
+  });
+});
+
+// ── artworkUrl ────────────────────────────────────────────────────────────────
+
+describe('createSyraClient.artworkUrl', () => {
+  const client = createSyraClient({ baseURL: 'https://api.example.test' });
+
+  it('resolves a bare ObjectId string to an absolute images URL', () => {
+    expect(client.artworkUrl('507f1f77bcf86cd799439011')).toBe(
+      'https://api.example.test/api/images/507f1f77bcf86cd799439011',
+    );
+  });
+
+  it('prefixes a relative /api/images path', () => {
+    expect(client.artworkUrl('/api/images/507f1f77bcf86cd799439011')).toBe(
+      'https://api.example.test/api/images/507f1f77bcf86cd799439011',
+    );
+  });
+
+  it('passes through an absolute http(s) URL', () => {
+    expect(client.artworkUrl('https://cdn.example.com/x.jpg')).toBe('https://cdn.example.com/x.jpg');
+  });
+
+  it('prefers a named size from coverArtSizes', () => {
+    const url = client.artworkUrl(
+      {
+        coverArt: '/api/images/507f1f77bcf86cd799439011',
+        coverArtSizes: {
+          large: {
+            id: '507f1f77bcf86cd799439012',
+            url: '/api/images/507f1f77bcf86cd799439012',
+            width: 600,
+            height: 600,
+          },
+        },
+      },
+      'large',
+    );
+    expect(url).toBe('https://api.example.test/api/images/507f1f77bcf86cd799439012');
+  });
+
+  it('falls back to coverArt when the requested size is missing', () => {
+    const url = client.artworkUrl(
+      { coverArt: '/api/images/507f1f77bcf86cd799439011', coverArtSizes: {} },
+      'large',
+    );
+    expect(url).toBe('https://api.example.test/api/images/507f1f77bcf86cd799439011');
+  });
+
+  it('returns undefined when nothing resolvable is present', () => {
+    expect(client.artworkUrl({})).toBeUndefined();
+    expect(client.artworkUrl('not-an-id')).toBeUndefined();
+  });
+});

package/src/client.ts

@@ -0,0 +1,178 @@
+import {
+  trackSummarySchema,
+  type TrackSummary,
+  type CoverArtSizes,
+  type ArtworkSize,
+} from './schema';
+import { SyraApiError } from './errors';
+
+/** Default base URL of the public Syra API. */
+export 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;
+}
+
+/** Order used to pick the best available artwork variant when none is named. */
+const ARTWORK_FALLBACK_ORDER: ArtworkSize[] = [
+  'original',
+  'xxlarge',
+  'xlarge',
+  'large',
+  'medium',
+  'small',
+];
+
+const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;
+
+interface SearchResponseShape {
+  results?: { tracks?: 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(/\/+$/, '');
+
+  function resolveFetch(): typeof fetch {
+    if (options.fetch) {
+      return options.fetch;
+    }
+    const globalFetch = (globalThis as { fetch?: typeof fetch }).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: string): Promise<unknown> {
+    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: string | null | undefined): string | undefined {
+    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()}`)) as SearchResponseShape;
+      const rawTracks = Array.isArray(json?.results?.tracks) ? json.results.tracks : [];
+
+      const tracks: TrackSummary[] = [];
+      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/src/errors.ts

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

package/src/index.ts

@@ -0,0 +1,22 @@
+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';

package/src/schema.ts

@@ -0,0 +1,50 @@
+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(),
+});
+export type CoverArtVariant = z.infer<typeof coverArtVariantSchema>;
+
+/** 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(),
+});
+export type CoverArtSizes = z.infer<typeof coverArtSizesSchema>;
+
+/** Artwork size name. */
+export type ArtworkSize = keyof CoverArtSizes;
+
+/**
+ * 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(),
+});
+export type TrackSummary = z.infer<typeof trackSummarySchema>;