@audd/sdk 1.4.7 → 1.5.0

package/dist/longpollCore-DMBdcGSM.d.ts

@@ -0,0 +1,251 @@
+interface HttpResponse {
+    jsonBody: unknown;
+    httpStatus: number;
+    requestId: string | null;
+    rawText: string;
+}
+type FetchLike = typeof globalThis.fetch;
+interface HttpClientOptions {
+    apiToken: string;
+    fetch?: FetchLike;
+    /** Per-call timeout in ms. Defaults: 60_000 standard, 3_600_000 enterprise. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Form-data field value. Strings go through directly; Blob carries binary
+ * payloads with a filename when constructed via `new File()`.
+ */
+type FormFieldValue = string | Blob | undefined;
+declare class HttpClient {
+    private apiToken;
+    private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
+    constructor(opts: HttpClientOptions);
+    /** Atomically swap the token used for subsequent requests. */
+    setApiToken(newToken: string): void;
+    postForm(url: string, fields: Record<string, FormFieldValue>, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<HttpResponse>;
+    get(url: string, params: Record<string, string | undefined>, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<HttpResponse>;
+    private send;
+}
+
+/**
+ * Typed models. Forward-compatible: each model captures unknown keys into
+ * `extras`, mirroring audd-python's Pydantic `extra="allow"` pattern.
+ */
+/** Streaming providers supported by the lis.tn redirect helper. */
+type StreamingProvider = "spotify" | "apple_music" | "deezer" | "napster" | "youtube";
+interface RecognitionResult {
+    /** Always present on a match. */
+    timecode: string;
+    /** Set on custom-catalog matches. */
+    audioId?: number | undefined;
+    artist?: string | undefined;
+    title?: string | undefined;
+    album?: string | undefined;
+    releaseDate?: string | undefined;
+    label?: string | undefined;
+    songLink?: string | undefined;
+    isrc?: string | undefined;
+    upc?: string | undefined;
+    appleMusic?: Record<string, unknown> | undefined;
+    spotify?: Record<string, unknown> | undefined;
+    deezer?: Record<string, unknown> | undefined;
+    napster?: Record<string, unknown> | undefined;
+    musicbrainz?: ReadonlyArray<Record<string, unknown>> | undefined;
+    /** Forward-compat: any unknown keys from the server. */
+    extras: Record<string, unknown>;
+    /** Full unparsed payload for the caller's own inspection. */
+    rawResponse: Record<string, unknown>;
+    /** True when `audioId` is set (custom-catalog match). */
+    readonly isCustomMatch: boolean;
+    /** True when `audioId` is unset and `artist` or `title` are present. */
+    readonly isPublicMatch: boolean;
+    /** Cover-art URL for `lis.tn`-hosted song_links, else `null`. */
+    readonly thumbnailUrl: string | null;
+    /**
+     * Direct or redirect URL for a streaming provider, with smart fallback.
+     *
+     * Resolution order:
+     * 1. Direct URL from the metadata block (e.g. `apple_music.url`,
+     *    `spotify.external_urls.spotify`, `deezer.link`, `napster.href`) when
+     *    the user requested that provider via `return=`.
+     * 2. lis.tn redirect (`{songLink}?{provider}`) when `songLink` is on lis.tn.
+     * 3. `null` otherwise. YouTube has only the lis.tn-redirect path.
+     */
+    streamingUrl(provider: StreamingProvider): string | null;
+    /** Map of every provider with a resolvable URL — direct or via lis.tn redirect. */
+    streamingUrls(): Partial<Record<StreamingProvider, string>>;
+    /**
+     * First available 30-second preview URL across providers, in priority order:
+     * `apple_music.previews[0].url` → `spotify.preview_url` → `deezer.preview`.
+     *
+     * **Note:** previews are governed by the respective providers' terms of use.
+     * The SDK consumer is responsible for honoring those terms (caching limits,
+     * attribution, redistribution constraints).
+     */
+    previewUrl(): string | null;
+}
+interface EnterpriseMatch {
+    score: number;
+    timecode: string;
+    artist?: string | undefined;
+    title?: string | undefined;
+    album?: string | undefined;
+    releaseDate?: string | undefined;
+    label?: string | undefined;
+    isrc?: string | undefined;
+    upc?: string | undefined;
+    songLink?: string | undefined;
+    startOffset?: number | undefined;
+    endOffset?: number | undefined;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+    readonly thumbnailUrl: string | null;
+    /** lis.tn redirect URL for the given streaming provider, or null if `songLink` is non-lis.tn. */
+    streamingUrl(provider: StreamingProvider): string | null;
+    /** All providers with a resolvable lis.tn redirect URL (or empty when `songLink` is off lis.tn). */
+    streamingUrls(): Partial<Record<StreamingProvider, string>>;
+}
+interface EnterpriseChunkResult {
+    songs: EnterpriseMatch[];
+    offset: string;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+interface Stream {
+    radioId: number;
+    url: string;
+    streamRunning: boolean;
+    longpollCategory?: string | undefined;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+/**
+ * One candidate song in a recognition match.
+ *
+ * Almost every match has exactly one Song; the rare extra candidates that
+ * appear under {@link StreamCallbackMatch.alternatives} may have a *different*
+ * artist or title from the top song — they're variant catalog releases of the
+ * same recording (e.g. a "feat." credit vs. the bare-artist re-release, or
+ * regional edits with different titles), not lower-confidence guesses at the
+ * same track.
+ */
+interface StreamCallbackSong {
+    artist: string;
+    title: string;
+    score: number;
+    album?: string | undefined;
+    releaseDate?: string | undefined;
+    label?: string | undefined;
+    songLink?: string | undefined;
+    isrc?: string | undefined;
+    upc?: string | undefined;
+    appleMusic?: Record<string, unknown> | undefined;
+    spotify?: Record<string, unknown> | undefined;
+    deezer?: Record<string, unknown> | undefined;
+    napster?: Record<string, unknown> | undefined;
+    musicbrainz?: ReadonlyArray<Record<string, unknown>> | undefined;
+    extras: Record<string, unknown>;
+}
+/**
+ * One recognition event from a stream callback or longpoll.
+ *
+ * The top match lives in {@link song}; rare extra candidates live in
+ * {@link alternatives}. Alternatives entries may have a different artist or
+ * title from the top song — they're variant catalog releases of the same
+ * recording, not lower-confidence guesses at the same track.
+ */
+interface StreamCallbackMatch {
+    radioId: number;
+    timestamp?: string | undefined;
+    playLength?: number | undefined;
+    /** Top match — always present. */
+    song: StreamCallbackSong;
+    /** Variant catalog releases (may have different artist/title); empty array when only one match. */
+    alternatives: StreamCallbackSong[];
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+interface StreamCallbackNotification {
+    radioId: number;
+    streamRunning?: boolean | undefined;
+    notificationCode: number;
+    notificationMessage: string;
+    /** Outer `time` field on the callback envelope (epoch seconds). */
+    time?: number | undefined;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+interface LyricsResult {
+    artist: string;
+    title: string;
+    lyrics?: string | undefined;
+    songId?: number | undefined;
+    fullTitle?: string | undefined;
+    artistId?: number | undefined;
+    songLink?: string | undefined;
+    media?: string | undefined;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+
+/**
+ * Shared longpoll loop + handle, used by both the authenticated `Streams`
+ * namespace (token in URL via `HttpClient.get`) and the tokenless
+ * `LongpollConsumer` exported from `audd/longpoll`.
+ *
+ * Browser-safe: no node:crypto, no node:fs, no node:http imports. The whole
+ * file relies on `fetch`-style I/O the caller injects.
+ */
+
+/**
+ * Active long-poll subscription. Two typed `AsyncIterable`s carry the
+ * happy-path output and a third carries any terminal error.
+ *
+ * Consume `matches` and `notifications` independently or in parallel:
+ *
+ * ```ts
+ * const poll = await audd.streams.longpoll(category);
+ * for await (const m of poll.matches) {
+ *   console.log(m.song.artist, m.song.title);
+ * }
+ * ```
+ *
+ * Concurrent consumption:
+ *
+ * ```ts
+ * await Promise.all([
+ *   (async () => { for await (const m of poll.matches) {} })(),
+ *   (async () => { for await (const n of poll.notifications) {} })(),
+ *   (async () => { for await (const e of poll.errors) console.error(e); })(),
+ * ]);
+ * ```
+ *
+ * `close()` (or the `await using` resource-management form) tears down the
+ * background loop and closes all three iterables.
+ */
+interface LongpollPoll {
+    /** Recognition events. */
+    readonly matches: AsyncIterable<StreamCallbackMatch>;
+    /** Stream-lifecycle events ("stream stopped", "can't connect", ...). */
+    readonly notifications: AsyncIterable<StreamCallbackNotification>;
+    /**
+     * Terminal errors. The poll keeps polling on transient HTTP/JSON failures
+     * (subject to the retry policy); errors that surface here are the ones the
+     * loop gives up on. Each fired error is followed by closure of all three
+     * iterables.
+     */
+    readonly errors: AsyncIterable<Error>;
+    /** Stop the background loop. Idempotent. */
+    close(): void;
+    /** `await using` support — calls `close()`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+export { type EnterpriseMatch as E, type FetchLike as F, HttpClient as H, type LongpollPoll as L, type RecognitionResult as R, type StreamCallbackMatch as S, type StreamCallbackNotification as a, type Stream as b, type LyricsResult as c, type EnterpriseChunkResult as d, type StreamCallbackSong as e, type StreamingProvider as f };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audd/sdk",
-  "version": "1.4.7",
+  "version": "1.5.0",
   "description": "Official TypeScript SDK for the AudD music recognition API.",
   "license": "MIT",
   "author": "AudD <api@audd.io>",

package/dist/http-y2YwjfAl.d.cts

@@ -1,37 +0,0 @@
-interface HttpResponse {
-    jsonBody: unknown;
-    httpStatus: number;
-    requestId: string | null;
-    rawText: string;
-}
-type FetchLike = typeof globalThis.fetch;
-interface HttpClientOptions {
-    apiToken: string;
-    fetch?: FetchLike;
-    /** Per-call timeout in ms. Defaults: 60_000 standard, 3_600_000 enterprise. */
-    defaultTimeoutMs?: number;
-}
-/**
- * Form-data field value. Strings go through directly; Blob carries binary
- * payloads with a filename when constructed via `new File()`.
- */
-type FormFieldValue = string | Blob | undefined;
-declare class HttpClient {
-    private apiToken;
-    private readonly fetchImpl;
-    private readonly defaultTimeoutMs;
-    constructor(opts: HttpClientOptions);
-    /** Atomically swap the token used for subsequent requests. */
-    setApiToken(newToken: string): void;
-    postForm(url: string, fields: Record<string, FormFieldValue>, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<HttpResponse>;
-    get(url: string, params: Record<string, string | undefined>, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<HttpResponse>;
-    private send;
-}
-
-export { type FetchLike as F, HttpClient as H };

package/dist/http-y2YwjfAl.d.ts

@@ -1,37 +0,0 @@
-interface HttpResponse {
-    jsonBody: unknown;
-    httpStatus: number;
-    requestId: string | null;
-    rawText: string;
-}
-type FetchLike = typeof globalThis.fetch;
-interface HttpClientOptions {
-    apiToken: string;
-    fetch?: FetchLike;
-    /** Per-call timeout in ms. Defaults: 60_000 standard, 3_600_000 enterprise. */
-    defaultTimeoutMs?: number;
-}
-/**
- * Form-data field value. Strings go through directly; Blob carries binary
- * payloads with a filename when constructed via `new File()`.
- */
-type FormFieldValue = string | Blob | undefined;
-declare class HttpClient {
-    private apiToken;
-    private readonly fetchImpl;
-    private readonly defaultTimeoutMs;
-    constructor(opts: HttpClientOptions);
-    /** Atomically swap the token used for subsequent requests. */
-    setApiToken(newToken: string): void;
-    postForm(url: string, fields: Record<string, FormFieldValue>, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<HttpResponse>;
-    get(url: string, params: Record<string, string | undefined>, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<HttpResponse>;
-    private send;
-}
-
-export { type FetchLike as F, HttpClient as H };