@audd/sdk 1.4.7 → 1.5.0

package/dist/index.d.cts

@@ -1,159 +1,8 @@
-import { H as HttpClient, F as FetchLike } from './http-y2YwjfAl.cjs';
+import { S as StreamCallbackMatch, a as StreamCallbackNotification, H as HttpClient, b as Stream, L as LongpollPoll, c as LyricsResult, F as FetchLike, R as RecognitionResult, E as EnterpriseMatch } from './longpollCore-DMBdcGSM.cjs';
+export { d as EnterpriseChunkResult, e as StreamCallbackSong, f as StreamingProvider } from './longpollCore-DMBdcGSM.cjs';
 
 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.
@@ -201,6 +50,169 @@ interface RetryPolicy {
     backoffMaxMs: number;
 }
 
+/** 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;
+/**
+ * Result of {@link parseCallback} / {@link handleCallback}.
+ *
+ * Exactly one of `match` or `notification` is non-null on success.
+ * Recognition callbacks populate `match`; lifecycle/error callbacks (e.g.
+ * "stream stopped", "can't connect") populate `notification`.
+ */
+interface ParsedCallback {
+    match: StreamCallbackMatch | null;
+    notification: StreamCallbackNotification | null;
+}
+/**
+ * Parse a callback POST body into a typed match or notification.
+ *
+ * Accepts either a parsed JSON object or a string (serialized JSON). Throws
+ * {@link AudDSerializationError} when the body is unparseable JSON, isn't an
+ * object, or carries neither a `result` nor a `notification` block.
+ *
+ * Prefer {@link handleCallback} when you have a Node `http.IncomingMessage`,
+ * a Web `Request`, or anything with a streamed body — that helper reads the
+ * body for you.
+ */
+declare function parseCallback(body: unknown): ParsedCallback;
+/**
+ * Minimum shape we accept from a "request-like" object: anything that exposes
+ * a `body` (already-parsed-or-stringified JSON), or that is itself a stream we
+ * can drain.
+ *
+ * Concretely supports:
+ * - Node `http.IncomingMessage` (async-iterable of `Buffer | string`)
+ * - Web `Request` / `fetch` `Body` (has `.text()`)
+ * - Express/Fastify/Hono request (has a `.body` already populated by a JSON parser)
+ * - Plain `{ body: <parsed-json | string> }` shapes
+ */
+type CallbackRequestLike = {
+    text(): Promise<string>;
+} | {
+    body?: unknown;
+    [k: string]: unknown;
+} | AsyncIterable<unknown>;
+/**
+ * Read and parse a callback POST body off a Node, Web, or framework-style
+ * request. Picks the right strategy by duck-typing:
+ *
+ * 1. If the request exposes a `text()` method (Web `Request`, `fetch` body),
+ *    awaits it and parses the resulting string.
+ * 2. Otherwise, if the request has a `body` property that's already an object
+ *    (Express/Fastify/Hono with a JSON middleware) or string, parses that
+ *    directly without touching the underlying stream.
+ * 3. Otherwise, treats the request as an async-iterable of chunks
+ *    (`http.IncomingMessage`) and concatenates the body before parsing.
+ *
+ * Throws {@link AudDSerializationError} on any parse failure.
+ */
+declare function handleCallback(req: CallbackRequestLike): Promise<ParsedCallback>;
+
 interface SetCallbackUrlOptions {
     returnMetadata?: string | string[];
 }
@@ -245,18 +257,27 @@ declare class Streams {
     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).
+     * Parse a callback POST body into `{ match, notification }`. Pass an
+     * already-parsed JSON value or a string. Exactly one field is non-null on
+     * success. See {@link parseCallback} for details.
+     */
+    parseCallback(body: unknown): ParsedCallback;
+    /**
+     * Long-poll the AudD subscription endpoint.
      *
-     * 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.
+     * Returns a {@link LongpollPoll} handle with three async-iterables —
+     * `matches`, `notifications`, `errors` — that are filled by a background
+     * loop. Iterate them independently or in parallel via `Promise.all([...])`.
+     *
+     * Before the first request the SDK runs a one-time `getCallbackUrl`
+     * preflight: AudD silently discards events for accounts that haven't set a
+     * callback URL, and the preflight surfaces that misconfiguration as an
+     * actionable {@link AudDInvalidRequestError}. Pass `skipCallbackCheck: true`
+     * to bypass.
      */
-    longpoll(category: string, opts?: LongpollOptions): AsyncIterable<Record<string, unknown>>;
+    longpoll(category: string, opts?: LongpollOptions): Promise<LongpollPoll>;
+    private preflightCallbackUrl;
 }
 
 interface CustomCatalogAddOptions {
@@ -422,112 +443,4 @@ declare class AudD {
     [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 };
+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, EnterpriseMatch, type LongpollOptions, LongpollPoll, LyricsResult, type OnEventHook, type ParsedCallback, RecognitionResult, type RecognizeEnterpriseOptions, type RecognizeOptions, type ReturnMetadata, type SetCallbackUrlOptions, type Source, StreamCallbackMatch, StreamCallbackNotification, Stream as StreamRecord, Streams, VERSION, addReturnToUrl, deriveLongpollCategory, errorClassForCode, handleCallback, parseCallback };