@audd/sdk 1.4.7

package/dist/index.d.ts

@@ -0,0 +1,533 @@
+import { H as HttpClient, F as FetchLike } from './http-y2YwjfAl.js';
+
+declare const VERSION = "1.4.6";
+
+/**
+ * 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;
+    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>;
+}
+interface StreamCallbackResultEntry {
+    artist: string;
+    title: string;
+    score: number;
+    album?: string | undefined;
+    releaseDate?: string | undefined;
+    label?: string | undefined;
+    songLink?: 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>;
+    rawResponse: Record<string, unknown>;
+}
+interface StreamCallbackResult {
+    radioId: number;
+    timestamp?: string | undefined;
+    playLength?: number | undefined;
+    results: StreamCallbackResultEntry[];
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+interface StreamCallbackNotification {
+    radioId: number;
+    streamRunning?: boolean | undefined;
+    notificationCode: number;
+    notificationMessage: string;
+    extras: Record<string, unknown>;
+    rawResponse: Record<string, unknown>;
+}
+/**
+ * Discriminated union: a parsed callback payload is either a recognition
+ * result or a notification.
+ */
+interface StreamCallbackPayload {
+    /** Set when this is a recognition result delivery. */
+    result: StreamCallbackResult | null;
+    /** Set when this is a stream-state notification. */
+    notification: StreamCallbackNotification | null;
+    /** Notification time (epoch seconds). */
+    time: number | null;
+    /** Original parsed JSON body. */
+    rawPayload: Record<string, unknown>;
+    readonly isResult: boolean;
+    readonly isNotification: boolean;
+}
+declare function parseStreamCallback(raw: unknown): StreamCallbackPayload;
+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>;
+}
+
+/**
+ * Auto-detect what kind of audio source the caller passed and convert to
+ * the right multipart fields.
+ *
+ * Returns a *re-opener* — a 0-arg callable that yields fresh form fields
+ * on each call. The HTTP layer invokes it inside the retry-wrapped request
+ * closure, so retried attempts get fresh body content rather than an
+ * exhausted stream / spent buffer.
+ *
+ * Specifically: `fetch()` does NOT auto-rewind a `Blob` constructed over a
+ * stream once the body is consumed; the re-opener pattern is mandatory in
+ * Node/browsers (the audd-python C1 review note discusses this — Python's
+ * httpx auto-seeks; ours doesn't always).
+ */
+
+/**
+ * Audio source the caller passes to `recognize` / `recognizeEnterprise` /
+ * `customCatalog.add`. Auto-detected:
+ *
+ * - `string` starting with `http://` or `https://` → URL parameter
+ * - `string` other → resolved as a filesystem path on Node (TypeError in browsers)
+ * - `URL` → URL parameter
+ * - `Blob` / `File` → multipart upload
+ * - `Uint8Array` / `Buffer` → multipart upload
+ */
+type Source = string | URL | Blob | Uint8Array;
+
+/**
+ * Cost-aware retry classes.
+ *
+ * - READ        — idempotent reads (`streams.list`, `streams.getCallbackUrl`):
+ *                 retry on 408/429/5xx + any connection error.
+ * - RECOGNITION — `recognize`, `recognizeEnterprise`, `advanced.findLyrics`:
+ *                 retry on pre-upload connection failures + 5xx.
+ *                 DO NOT retry on read-timeout-after-upload (cost protection).
+ * - MUTATING    — `streams.add`, `streams.delete`, etc., `customCatalog.add`:
+ *                 retry only on pre-upload connection failures. DO NOT retry
+ *                 5xx (the side effect may have happened).
+ */
+type RetryClass = "read" | "recognition" | "mutating";
+interface RetryPolicy {
+    retryClass: RetryClass;
+    maxAttempts: number;
+    backoffFactorMs: number;
+    backoffMaxMs: number;
+}
+
+interface SetCallbackUrlOptions {
+    returnMetadata?: string | string[];
+}
+interface AddStreamOptions {
+    url: string;
+    radioId: number;
+    /** "before" delivers callbacks at song start; default delivers at song end. */
+    callbacks?: "before" | string;
+}
+interface LongpollOptions {
+    sinceTime?: number;
+    /** Server-side timeout in seconds (default 50). */
+    timeout?: number;
+    /** Bypass the default-on `getCallbackUrl` preflight. */
+    skipCallbackCheck?: boolean;
+}
+declare class Streams {
+    private readonly http;
+    private readonly readPolicy;
+    private readonly mutatingPolicy;
+    private readonly apiToken;
+    constructor(http: HttpClient, readPolicy: RetryPolicy, mutatingPolicy: RetryPolicy, apiToken: string);
+    private post;
+    /**
+     * Set the callback URL where AudD will POST recognition events.
+     *
+     * @param url   The URL to register.
+     * @param opts.returnMetadata Optional metadata block list — appended as
+     * `?return=...` to the URL. Raises `DuplicateReturnParameterError` if the
+     * URL already contains a `?return=` parameter.
+     */
+    setCallbackUrl(url: string, opts?: SetCallbackUrlOptions): Promise<void>;
+    /** Get the currently registered callback URL. */
+    getCallbackUrl(): Promise<string>;
+    /** Register a new stream for real-time recognition. */
+    add(opts: AddStreamOptions): Promise<void>;
+    /** Update the upstream URL of an existing stream. */
+    setUrl(radioId: number, url: string): Promise<void>;
+    /** Delete an existing stream. */
+    delete(radioId: number): Promise<void>;
+    /** List all streams on this account. */
+    list(): Promise<Stream[]>;
+    /** Compute the 9-char longpoll category locally — pure, no network. */
+    deriveLongpollCategory(radioId: number): string;
+    /** Parse a callback POST body into a typed `StreamCallbackPayload`. */
+    parseCallback(body: unknown): StreamCallbackPayload;
+    /**
+     * Longpoll the AudD subscription endpoint, yielding parsed JSON dicts
+     * (recognition events, notifications, or `{ timeout: ... }` markers).
+     *
+     * By default, performs a one-time `getCallbackUrl` preflight. If the
+     * server returns code 19 (no callback URL configured), throws
+     * `AudDInvalidRequestError` with an actionable hint. Pass
+     * `skipCallbackCheck: true` to bypass.
+     */
+    longpoll(category: string, opts?: LongpollOptions): AsyncIterable<Record<string, unknown>>;
+}
+
+interface CustomCatalogAddOptions {
+    audioId: number;
+    source: Source;
+}
+declare class CustomCatalog {
+    private readonly http;
+    private readonly mutatingPolicy;
+    constructor(http: HttpClient, mutatingPolicy: RetryPolicy);
+    /**
+     * **This is NOT how you submit audio for music recognition.** For
+     * recognition, use `audd.recognize()` (or `audd.recognizeEnterprise()` for
+     * files longer than 25 seconds). This method adds a song to your
+     * **private fingerprint catalog** so AudD's recognition can later identify
+     * *your own* tracks for *your account only*. Requires special access —
+     * contact api@audd.io if you need it enabled.
+     *
+     * Calling this again with the same `audioId` re-fingerprints that slot.
+     * There is no public list/delete endpoint; track `audioId` ↔ song
+     * mappings on your side.
+     */
+    add(opts: CustomCatalogAddOptions): Promise<void>;
+}
+
+declare class Advanced {
+    private readonly http;
+    private readonly recognitionPolicy;
+    /**
+     * @param recognitionPolicy The findLyrics endpoint is metered and shouldn't
+     * double-bill on post-upload read timeout: Advanced uses RECOGNITION retry
+     * policy, not READ.
+     */
+    constructor(http: HttpClient, recognitionPolicy: RetryPolicy);
+    /** Find lyrics by free-text query. Returns a list of matches (possibly empty). */
+    findLyrics(query: string): Promise<LyricsResult[]>;
+    /**
+     * Hit any AudD endpoint by method name and return the raw JSON object.
+     * Useful for endpoints not yet wrapped by typed methods on this SDK.
+     */
+    rawRequest(method: string, params?: Record<string, string | number | boolean | undefined>): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Inspection event kinds emitted by the SDK request lifecycle.
+ * Hooks receive these via the `onEvent` callback.
+ */
+type AudDEventKind = "request" | "response" | "exception";
+/**
+ * Inspection event emitted by the SDK request lifecycle.
+ * Frozen, plain-data; never includes the api_token or request body bytes.
+ */
+interface AudDEvent {
+    kind: AudDEventKind;
+    /** AudD method name, e.g. "recognize", "addStream". */
+    method: string;
+    url: string;
+    requestId: string | null;
+    httpStatus: number | null;
+    elapsedMs: number | null;
+    errorCode: number | null;
+    extras: Record<string, unknown>;
+}
+type OnEventHook = (event: AudDEvent) => void;
+interface AudDOptions {
+    /** Required, but may be omitted if `AUDD_API_TOKEN` is in the environment. */
+    apiToken?: string;
+    /** Maximum retry attempts (default 3). */
+    maxRetries?: number;
+    /** Initial backoff in ms (default 500), jittered, exponential. */
+    backoffFactorMs?: number;
+    /** Custom fetch (e.g., for proxy/mTLS). */
+    fetch?: FetchLike;
+    /** Inspection hook (see {@link AudDEvent}). Off by default. */
+    onEvent?: OnEventHook;
+}
+type ReturnMetadata = "apple_music" | "spotify" | "deezer" | "napster" | "musicbrainz" | string;
+interface RecognizeOptions {
+    return?: ReturnMetadata | ReturnMetadata[];
+    market?: string;
+    /** Per-call timeout in ms; overrides the client default. */
+    timeoutMs?: number;
+    /**
+     * User-supplied AbortSignal for cancellation.
+     *
+     * **Note:** cancellation aborts the local request. The server may have
+     * already done metered work and the credit is consumed regardless.
+     */
+    signal?: AbortSignal;
+}
+interface RecognizeEnterpriseOptions {
+    return?: ReturnMetadata | ReturnMetadata[];
+    skip?: number;
+    every?: number;
+    limit?: number;
+    skipFirstSeconds?: number;
+    useTimecode?: boolean;
+    accurateOffsets?: boolean;
+    timeoutMs?: number;
+    /**
+     * User-supplied AbortSignal for cancellation. See {@link RecognizeOptions.signal}.
+     * For multi-hour enterprise calls, this is the right way to cancel.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The AudD client. Async-only — every method returns a `Promise`.
+ *
+ * ```ts
+ * const audd = new AudD({ apiToken: "test" });
+ * const result = await audd.recognize("https://audd.tech/example.mp3");
+ * ```
+ *
+ * Closes underlying resources via `close()` (or `[Symbol.asyncDispose]` if
+ * the runtime supports explicit-resource-management).
+ */
+declare class AudD {
+    private readonly _http;
+    private readonly _enterpriseHttp;
+    private readonly _maxRetries;
+    private readonly _backoffFactorMs;
+    private _apiToken;
+    private _onEvent;
+    private _streams;
+    private _customCatalog;
+    private _advanced;
+    /** Construct with just an api_token. Falls back to AUDD_API_TOKEN env var if omitted. */
+    constructor(apiToken?: string);
+    /** Construct with an api_token and additional options (timeouts, retries, custom fetch, onEvent hook). */
+    constructor(apiToken: string, opts: Omit<AudDOptions, "apiToken">);
+    /** Construct with an options object (any combination of apiToken + extras). */
+    constructor(opts: AudDOptions);
+    /** Current api_token. Returns the in-effect token after any rotations. */
+    get apiToken(): string;
+    /**
+     * Rotate the api_token used for subsequent requests. In-flight requests
+     * continue with the old token (no abort).
+     */
+    setApiToken(newToken: string): void;
+    private policyFor;
+    /** Sub-namespace for stream management + longpoll. Lazy-instantiated. */
+    get streams(): Streams;
+    /** Sub-namespace for the private fingerprint catalog. NOT for recognition. */
+    get customCatalog(): CustomCatalog;
+    /** Lyrics search + raw-request escape hatch. */
+    get advanced(): Advanced;
+    /**
+     * Recognize a short audio clip (≤25s) from a URL, file path, Blob, or bytes.
+     *
+     * Returns `null` when the server returns `status=success` with `result=null`
+     * (no match) — distinct from a thrown error.
+     */
+    recognize(source: Source, opts?: RecognizeOptions): Promise<RecognitionResult | null>;
+    /**
+     * Enterprise recognition (long files). Returns a flat array of matches
+     * across all chunks in the upstream response.
+     *
+     * Recommended: pass `limit: N` to cap result count when developing.
+     */
+    recognizeEnterprise(source: Source, opts?: RecognizeEnterpriseOptions): Promise<EnterpriseMatch[]>;
+    /** Release any underlying resources. (Currently a no-op for `fetch`-based transport.) */
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** Exception hierarchy for AudD API errors. */
+interface AudDApiErrorFields {
+    errorCode: number;
+    message: string;
+    httpStatus: number;
+    requestId: string | null;
+    requestedParams: Record<string, unknown>;
+    requestMethod: string | null;
+    brandedMessage: string | null;
+    rawResponse: unknown;
+}
+type AudDApiErrorInit = Partial<AudDApiErrorFields> & Pick<AudDApiErrorFields, "errorCode" | "message" | "httpStatus">;
+/** Base for everything thrown by this SDK. */
+declare class AudDError extends Error {
+    name: string;
+}
+/** Server returned `status: error`. Carries the AudD error code + the full echo. */
+declare class AudDAPIError extends AudDError {
+    name: string;
+    errorCode: number;
+    httpStatus: number;
+    requestId: string | null;
+    requestedParams: Record<string, unknown>;
+    requestMethod: string | null;
+    brandedMessage: string | null;
+    rawResponse: unknown;
+    /** Original `error_message` from the server. (`Error.message` may be overridden by subclasses.) */
+    serverMessage: string;
+    constructor(init: AudDApiErrorInit);
+}
+declare class AudDAuthenticationError extends AudDAPIError {
+    name: string;
+}
+declare class AudDQuotaError extends AudDAPIError {
+    name: string;
+}
+declare class AudDSubscriptionError extends AudDAPIError {
+    name: string;
+}
+declare class AudDCustomCatalogAccessError extends AudDSubscriptionError {
+    name: string;
+}
+declare class AudDInvalidRequestError extends AudDAPIError {
+    name: string;
+}
+declare class AudDInvalidAudioError extends AudDAPIError {
+    name: string;
+}
+declare class AudDRateLimitError extends AudDAPIError {
+    name: string;
+}
+declare class AudDStreamLimitError extends AudDAPIError {
+    name: string;
+}
+declare class AudDNotReleasedError extends AudDAPIError {
+    name: string;
+}
+declare class AudDBlockedError extends AudDAPIError {
+    name: string;
+}
+declare class AudDNeedsUpdateError extends AudDAPIError {
+    name: string;
+}
+declare class AudDServerError extends AudDAPIError {
+    name: string;
+}
+declare class AudDConnectionError extends AudDError {
+    name: string;
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare class AudDSerializationError extends AudDError {
+    name: string;
+    rawText: string;
+    constructor(message: string, rawText?: string);
+}
+type AudDAPIErrorCtor = new (init: AudDApiErrorInit) => AudDAPIError;
+declare function errorClassForCode(code: number): AudDAPIErrorCtor;
+
+/**
+ * Raised by `addReturnToUrl` (and therefore by `streams.setCallbackUrl`)
+ * when the URL already contains a `return` query parameter and a
+ * `returnMetadata` argument is also passed — conflicting intent.
+ */
+declare class DuplicateReturnParameterError extends AudDInvalidRequestError {
+    name: string;
+    constructor();
+}
+/**
+ * Compute the 9-char longpoll category locally from the API token + radio_id.
+ *
+ * Formula (per docs.audd.io/streams.md): hex-MD5 of (hex-MD5 of api_token,
+ * concatenated with the radio_id rendered as a decimal string), truncated
+ * to the first 9 hex chars.
+ *
+ * Pure function — no network call. Lets servers share a longpoll category
+ * with browser/mobile clients without leaking the api_token.
+ */
+declare function deriveLongpollCategory(apiToken: string, radioId: number): string;
+/**
+ * Append `?return=<metadata>` (or merge as `&return=`) to the callback URL.
+ *
+ * - If `returnMetadata` is `undefined`, returns the URL unchanged.
+ * - If the URL already has a `return` query parameter, raises rather than
+ *   silently overwriting.
+ */
+declare function addReturnToUrl(url: string, returnMetadata: string | string[] | undefined): string;
+
+export { type AddStreamOptions, Advanced, AudD, AudDAPIError, AudDAuthenticationError, AudDBlockedError, AudDConnectionError, AudDCustomCatalogAccessError, AudDError, type AudDEvent, type AudDEventKind, AudDInvalidAudioError, AudDInvalidRequestError, AudDNeedsUpdateError, AudDNotReleasedError, type AudDOptions, AudDQuotaError, AudDRateLimitError, AudDSerializationError, AudDServerError, AudDStreamLimitError, AudDSubscriptionError, CustomCatalog, type CustomCatalogAddOptions, DuplicateReturnParameterError, type EnterpriseChunkResult, type EnterpriseMatch, type LongpollOptions, type LyricsResult, type OnEventHook, type RecognitionResult, type RecognizeEnterpriseOptions, type RecognizeOptions, type ReturnMetadata, type SetCallbackUrlOptions, type Source, type StreamCallbackNotification, type StreamCallbackPayload, type StreamCallbackResult, type StreamCallbackResultEntry, type Stream as StreamRecord, type StreamingProvider, Streams, VERSION, addReturnToUrl, deriveLongpollCategory, errorClassForCode, parseStreamCallback as parseCallback };