@audd/sdk 1.5.11 → 1.5.13

package/dist/index.js

@@ -3,7 +3,7 @@ import * as path from 'path';
 import { createHash } from 'crypto';
 
 // src/version.ts
-var VERSION = "1.5.8";
+var VERSION = "1.5.13";
 
 // src/errors.ts
 var AudDError = class extends Error {
@@ -76,6 +76,16 @@ var AudDConnectionError = class extends AudDError {
     this.cause = cause;
   }
 };
+var USER_ABORT_ERROR_NAME = "UserAbortError";
+function userAbortError(cause) {
+  const err = new Error("Request was cancelled by the caller's AbortSignal");
+  err.name = USER_ABORT_ERROR_NAME;
+  err.cause = cause;
+  return err;
+}
+function isUserAbortError(err) {
+  return err !== null && typeof err === "object" && err.name === USER_ABORT_ERROR_NAME;
+}
 var AudDSerializationError = class extends AudDError {
   name = "AudDSerializationError";
   rawText;
@@ -148,6 +158,55 @@ function raiseFromErrorResponse(body, opts) {
   throw new Cls(fields);
 }
 
+// src/events.ts
+function safeEmit(hook, event) {
+  if (hook === void 0) return;
+  try {
+    hook(event);
+  } catch {
+  }
+}
+async function emitAround(hook, method, url, fn) {
+  const startedAt = Date.now();
+  safeEmit(hook, {
+    kind: "request",
+    method,
+    url,
+    requestId: null,
+    httpStatus: null,
+    elapsedMs: null,
+    errorCode: null,
+    extras: {}
+  });
+  let resp;
+  try {
+    resp = await fn();
+  } catch (err) {
+    safeEmit(hook, {
+      kind: "exception",
+      method,
+      url,
+      requestId: null,
+      httpStatus: null,
+      elapsedMs: Date.now() - startedAt,
+      errorCode: null,
+      extras: { name: err instanceof Error ? err.name : String(err) }
+    });
+    throw err;
+  }
+  safeEmit(hook, {
+    kind: "response",
+    method,
+    url,
+    requestId: resp.requestId,
+    httpStatus: resp.httpStatus,
+    elapsedMs: Date.now() - startedAt,
+    errorCode: null,
+    extras: {}
+  });
+  return resp;
+}
+
 // src/userAgent.ts
 function userAgent() {
   const node = typeof process !== "undefined" && process.version ? process.version.replace(/^v/, "") : "unknown";
@@ -225,6 +284,11 @@ var HttpClient = class {
         requestId: response.headers.get("x-request-id"),
         rawText: text
       };
+    } catch (err) {
+      if (userSignal?.aborted === true && err !== null && typeof err === "object" && err.name === "AbortError") {
+        throw userAbortError(err);
+      }
+      throw err;
     } finally {
       clearTimeout(timer);
       if (userSignal !== void 0) {
@@ -249,19 +313,42 @@ function asObject(raw) {
   }
   return void 0;
 }
-function requireObject(raw, what) {
-  const o = asObject(raw);
-  if (o === void 0) throw new TypeError(`${what}: expected object`);
-  return o;
+function asObjectLenient(raw) {
+  return asObject(raw) ?? {};
 }
 function asString(v) {
-  return typeof v === "string" ? v : void 0;
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return void 0;
+}
+function toFiniteNumber(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : void 0;
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (t === "") return void 0;
+    const n = Number(t);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
 }
 function asNumber(v) {
-  return typeof v === "number" ? v : void 0;
+  return toFiniteNumber(v);
+}
+function asInteger(v) {
+  const n = toFiniteNumber(v);
+  return n === void 0 ? void 0 : Math.trunc(n);
 }
 function asBoolean(v) {
-  return typeof v === "boolean" ? v : void 0;
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") {
+    const t = v.trim().toLowerCase();
+    if (t === "true" || t === "1" || t === "yes" || t === "on") return true;
+    if (t === "false" || t === "0" || t === "no" || t === "off" || t === "") return false;
+    return void 0;
+  }
+  return void 0;
 }
 function parseOffsetToSeconds(o) {
   if (o === void 0 || o === null) return void 0;
@@ -356,9 +443,9 @@ var RECOGNITION_KEYS = [
   "musicbrainz"
 ];
 function parseRecognitionResult(raw) {
-  const r = requireObject(raw, "RecognitionResult");
+  const r = asObjectLenient(raw);
   const timecode = asString(r.timecode);
-  const audioId = asNumber(r.audio_id);
+  const audioId = asInteger(r.audio_id);
   const artist = asString(r.artist);
   const title = asString(r.title);
   const songLink = asString(r.song_link);
@@ -431,7 +518,7 @@ var ENTERPRISE_MATCH_KEYS = [
   "end_seconds"
 ];
 function parseEnterpriseMatch(raw) {
-  const r = requireObject(raw, "EnterpriseMatch");
+  const r = asObjectLenient(raw);
   const score = asNumber(r.score);
   const timecode = asString(r.timecode);
   const songLink = asString(r.song_link);
@@ -446,8 +533,8 @@ function parseEnterpriseMatch(raw) {
     isrc: asString(r.isrc),
     upc: asString(r.upc),
     songLink,
-    startOffset: asNumber(r.start_offset),
-    endOffset: asNumber(r.end_offset),
+    startOffset: asInteger(r.start_offset),
+    endOffset: asInteger(r.end_offset),
     startSeconds: void 0,
     endSeconds: void 0,
     extras: pickExtras(r, ENTERPRISE_MATCH_KEYS),
@@ -481,8 +568,8 @@ function parseEnterpriseMatch(raw) {
 }
 var ENTERPRISE_CHUNK_KEYS = ["songs", "offset"];
 function parseEnterpriseChunkResult(raw) {
-  const r = requireObject(raw, "EnterpriseChunkResult");
-  const songsRaw = Array.isArray(r.songs) ? r.songs : [];
+  const r = asObjectLenient(raw);
+  const songsRaw = Array.isArray(r.songs) ? r.songs.filter((s) => asObject(s) !== void 0) : [];
   const offset = asString(r.offset);
   const base = parseOffsetToSeconds(r.offset);
   const songs = songsRaw.map((s) => {
@@ -502,8 +589,8 @@ function parseEnterpriseChunkResult(raw) {
 }
 var STREAM_KEYS = ["radio_id", "url", "stream_running", "longpoll_category"];
 function parseStream(raw) {
-  const r = requireObject(raw, "Stream");
-  const radioId = asNumber(r.radio_id);
+  const r = asObjectLenient(raw);
+  const radioId = asInteger(r.radio_id);
   const url = asString(r.url);
   const streamRunning = asBoolean(r.stream_running);
   return {
@@ -532,7 +619,7 @@ var STREAM_CALLBACK_SONG_KEYS = [
   "musicbrainz"
 ];
 function parseStreamCallbackSong(raw) {
-  const r = requireObject(raw, "StreamCallbackSong");
+  const r = asObjectLenient(raw);
   const artist = asString(r.artist);
   const title = asString(r.title);
   const score = asNumber(r.score);
@@ -562,15 +649,15 @@ var STREAM_CALLBACK_MATCH_KEYS = [
   "results"
 ];
 function parseStreamCallbackMatch(raw) {
-  const r = requireObject(raw, "StreamCallbackMatch");
-  const radioId = asNumber(r.radio_id);
+  const r = asObjectLenient(raw);
+  const radioId = asInteger(r.radio_id);
   const resultsRaw = Array.isArray(r.results) ? r.results : [];
   const songs = resultsRaw.filter((x) => asObject(x) !== void 0).map(parseStreamCallbackSong);
   const [first, ...rest] = songs;
   return {
     radioId,
     timestamp: asString(r.timestamp),
-    playLength: asNumber(r.play_length),
+    playLength: asInteger(r.play_length),
     song: first,
     alternatives: rest,
     extras: pickExtras(r, STREAM_CALLBACK_MATCH_KEYS),
@@ -584,9 +671,9 @@ var STREAM_CALLBACK_NOTIFICATION_KEYS = [
   "notification_message"
 ];
 function parseStreamCallbackNotification(raw) {
-  const r = requireObject(raw, "StreamCallbackNotification");
-  const radioId = asNumber(r.radio_id);
-  const code = asNumber(r.notification_code);
+  const r = asObjectLenient(raw);
+  const radioId = asInteger(r.radio_id);
+  const code = asInteger(r.notification_code);
   const message = asString(r.notification_message);
   return {
     radioId,
@@ -608,16 +695,16 @@ var LYRICS_KEYS = [
   "media"
 ];
 function parseLyricsResult(raw) {
-  const r = requireObject(raw, "LyricsResult");
+  const r = asObjectLenient(raw);
   const artist = asString(r.artist);
   const title = asString(r.title);
   return {
     artist,
     title,
     lyrics: asString(r.lyrics),
-    songId: asNumber(r.song_id),
+    songId: asInteger(r.song_id),
     fullTitle: asString(r.full_title),
-    artistId: asNumber(r.artist_id),
+    artistId: asInteger(r.artist_id),
     songLink: asString(r.song_link),
     media: asString(r.media),
     extras: pickExtras(r, LYRICS_KEYS),
@@ -704,6 +791,22 @@ async function retry(fn, policy) {
   if (haveResp && lastResp !== void 0) return lastResp;
   throw lastError;
 }
+async function runRetried(fn, policy) {
+  try {
+    return await retry(fn, policy);
+  } catch (err) {
+    if (isUserAbortError(err)) {
+      throw new AudDConnectionError("Request was cancelled by the caller's AbortSignal", err);
+    }
+    if (err instanceof TypeError) {
+      throw new AudDConnectionError(`Network error: ${err.message}`, err);
+    }
+    if (err !== null && typeof err === "object" && err.name === "AbortError") {
+      throw new AudDConnectionError("Request was aborted (timeout)", err);
+    }
+    throw err;
+  }
+}
 function looksLikeUrl(s) {
   return s.startsWith("http://") || s.startsWith("https://");
 }
@@ -955,13 +1058,13 @@ function decodeOne(resp) {
     );
   }
   const dict = body;
-  if ("notification" in dict) {
+  if (asObject(dict.notification) !== void 0) {
     const notification = parseStreamCallbackNotification(dict.notification);
     const t = dict["time"];
     if (typeof t === "number") notification.time = t;
     return { kind: "notification", notification };
   }
-  if ("result" in dict) {
+  if (asObject(dict.result) !== void 0) {
     return { kind: "match", match: parseStreamCallbackMatch(dict.result) };
   }
   return { kind: "keepalive" };
@@ -1040,6 +1143,7 @@ function startLongpoll(cfg) {
 
 // src/streams.ts
 var API_BASE = "https://api.audd.io";
+var LONGPOLL_TIMEOUT_MARGIN_SEC = 10;
 var NO_CALLBACK_ERROR_CODE = 19;
 var PREFLIGHT_NO_CALLBACK_HINT = "Longpoll won't deliver events because no callback URL is configured for this account. Set one first via streams.setCallbackUrl(...) \u2014 `https://audd.tech/empty/` is fine if you only want longpolling and don't need a real receiver. To skip this check, pass skipCallbackCheck: true.";
 function decodeSuccess(body, httpStatus, requestId) {
@@ -1064,34 +1168,26 @@ function decodeSuccess(body, httpStatus, requestId) {
     rawResponse: obj
   });
 }
-async function runRetried(fn, policy) {
-  try {
-    return await retry(fn, policy);
-  } catch (err) {
-    if (err instanceof TypeError) {
-      throw new AudDConnectionError(`Network error: ${err.message}`, err);
-    }
-    if (err !== null && typeof err === "object" && err.name === "AbortError") {
-      throw new AudDConnectionError("Request was aborted (timeout)", err);
-    }
-    throw err;
-  }
-}
 var Streams = class {
-  constructor(http, readPolicy, mutatingPolicy, apiToken) {
+  constructor(http, readPolicy, mutatingPolicy, apiToken, onEvent) {
     this.http = http;
     this.readPolicy = readPolicy;
     this.mutatingPolicy = mutatingPolicy;
     this.apiToken = apiToken;
+    this.onEvent = onEvent;
   }
   http;
   readPolicy;
   mutatingPolicy;
   apiToken;
+  onEvent;
   async post(path2, fields, policy) {
-    const resp = await runRetried(
-      () => this.http.postForm(`${API_BASE}/${path2}/`, fields),
-      policy
+    const url = `${API_BASE}/${path2}/`;
+    const resp = await emitAround(
+      this.onEvent,
+      path2,
+      url,
+      () => runRetried(() => this.http.postForm(url, fields), policy)
     );
     return decodeSuccess(resp.jsonBody, resp.httpStatus, resp.requestId);
   }
@@ -1138,11 +1234,11 @@ var Streams = class {
   async list() {
     const result = await this.post("getStreams", {}, this.readPolicy);
     if (!Array.isArray(result)) return [];
-    return result.map(parseStream);
+    return result.filter((x) => asObject(x) !== void 0).map(parseStream);
   }
   /** Compute the 9-char longpoll category locally — pure, no network. */
   deriveLongpollCategory(radioId) {
-    return deriveLongpollCategory(this.apiToken, radioId);
+    return deriveLongpollCategory(this.apiToken(), radioId);
   }
   /**
    * Parse a callback POST body into `{ match, notification }`. Pass an
@@ -1184,13 +1280,21 @@ var Streams = class {
     const timeoutSec = effectiveOpts.timeout ?? 50;
     const httpClient = this.http;
     const readPolicy = this.readPolicy;
+    const onEvent = this.onEvent;
+    const longpollUrl = `${API_BASE}/longpoll/`;
+    const timeoutMs = (timeoutSec + LONGPOLL_TIMEOUT_MARGIN_SEC) * 1e3;
     return startLongpoll({
       category,
       timeout: timeoutSec,
       sinceTime: effectiveOpts.sinceTime,
-      fetchOnce: (params, signal) => runRetried(
-        () => httpClient.get(`${API_BASE}/longpoll/`, params, { signal }),
-        readPolicy
+      fetchOnce: (params, signal) => emitAround(
+        onEvent,
+        "longpoll",
+        longpollUrl,
+        () => runRetried(
+          () => httpClient.get(longpollUrl, params, { signal, timeoutMs }),
+          readPolicy
+        )
       )
     });
   }
@@ -1235,26 +1339,15 @@ function decodeSuccess2(body, httpStatus, requestId) {
     });
   }
 }
-async function runRetried2(fn, policy) {
-  try {
-    return await retry(fn, policy);
-  } catch (err) {
-    if (err instanceof TypeError) {
-      throw new AudDConnectionError(`Network error: ${err.message}`, err);
-    }
-    if (err !== null && typeof err === "object" && err.name === "AbortError") {
-      throw new AudDConnectionError("Request was aborted (timeout)", err);
-    }
-    throw err;
-  }
-}
 var CustomCatalog = class {
-  constructor(http, noRetryPolicy) {
+  constructor(http, noRetryPolicy, onEvent) {
     this.http = http;
     this.noRetryPolicy = noRetryPolicy;
+    this.onEvent = onEvent;
   }
   http;
   noRetryPolicy;
+  onEvent;
   /**
    * **This is NOT how you submit audio for music recognition.** For
    * recognition, use `audd.recognize()` (or `audd.recognizeEnterprise()` for
@@ -1275,42 +1368,36 @@ var CustomCatalog = class {
   async add(opts) {
     const reopen = prepareSource(opts.source);
     const audioId = String(opts.audioId);
-    const resp = await runRetried2(async () => {
-      const prepared = await reopen();
-      const fields = { ...prepared.fields, audio_id: audioId };
-      return this.http.postForm(UPLOAD_URL, fields);
-    }, this.noRetryPolicy);
+    const resp = await emitAround(
+      this.onEvent,
+      "customCatalogAdd",
+      UPLOAD_URL,
+      () => runRetried(async () => {
+        const prepared = await reopen();
+        const fields = { ...prepared.fields, audio_id: audioId };
+        return this.http.postForm(UPLOAD_URL, fields);
+      }, this.noRetryPolicy)
+    );
     decodeSuccess2(resp.jsonBody, resp.httpStatus, resp.requestId);
   }
 };
 
 // src/advanced.ts
 var API_BASE2 = "https://api.audd.io";
-async function runRetried3(fn, policy) {
-  try {
-    return await retry(fn, policy);
-  } catch (err) {
-    if (err instanceof TypeError) {
-      throw new AudDConnectionError(`Network error: ${err.message}`, err);
-    }
-    if (err !== null && typeof err === "object" && err.name === "AbortError") {
-      throw new AudDConnectionError("Request was aborted (timeout)", err);
-    }
-    throw err;
-  }
-}
 var Advanced = class {
   /**
    * @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, recognitionPolicy) {
+  constructor(http, recognitionPolicy, onEvent) {
     this.http = http;
     this.recognitionPolicy = recognitionPolicy;
+    this.onEvent = onEvent;
   }
   http;
   recognitionPolicy;
+  onEvent;
   /** Find lyrics by free-text query. Returns a list of matches (possibly empty). */
   async findLyrics(query) {
     const body = await this.rawRequest("findLyrics", { q: query });
@@ -1334,9 +1421,12 @@ var Advanced = class {
       if (v === void 0) continue;
       fields[k] = String(v);
     }
-    const resp = await runRetried3(
-      () => this.http.postForm(`${API_BASE2}/${method}/`, fields),
-      this.recognitionPolicy
+    const url = `${API_BASE2}/${method}/`;
+    const resp = await emitAround(
+      this.onEvent,
+      method,
+      url,
+      () => runRetried(() => this.http.postForm(url, fields), this.recognitionPolicy)
     );
     const body = resp.jsonBody;
     if (typeof body !== "object" || body === null || Array.isArray(body)) {
@@ -1352,13 +1442,6 @@ var ENTERPRISE_BASE = "https://enterprise.audd.io";
 var DEPRECATED_PARAMS_CODE = 51;
 var HTTP_CLIENT_ERROR_FLOOR2 = 400;
 var TOKEN_ENV_VAR = "AUDD_API_TOKEN";
-function safeEmit(hook, event) {
-  if (hook === void 0) return;
-  try {
-    hook(event);
-  } catch {
-  }
-}
 function resolveToken(apiToken) {
   if (apiToken !== void 0 && apiToken !== "") return apiToken;
   const env = (typeof process !== "undefined" ? process.env[TOKEN_ENV_VAR] : void 0) ?? "";
@@ -1431,7 +1514,7 @@ function decodeOrRaise(resp) {
 function decodeRecognize(resp) {
   const body = decodeOrRaise(resp);
   const result = body["result"];
-  if (result == null) return null;
+  if (asObject(result) === void 0) return null;
   return parseRecognitionResult(result);
 }
 function decodeEnterprise(resp) {
@@ -1440,24 +1523,12 @@ function decodeEnterprise(resp) {
   if (!Array.isArray(chunks)) return [];
   const out = [];
   for (const c of chunks) {
+    if (asObject(c) === void 0) continue;
     const chunk = parseEnterpriseChunkResult(c);
     out.push(...chunk.songs);
   }
   return out;
 }
-async function runRetried4(fn, policy) {
-  try {
-    return await retry(fn, policy);
-  } catch (err) {
-    if (err instanceof TypeError) {
-      throw new AudDConnectionError(`Network error: ${err.message}`, err);
-    }
-    if (err !== null && typeof err === "object" && err.name === "AbortError") {
-      throw new AudDConnectionError("Request was aborted (timeout)", err);
-    }
-    throw err;
-  }
-}
 var AudD = class {
   _http;
   _enterpriseHttp;
@@ -1515,7 +1586,8 @@ var AudD = class {
         this._http,
         this.policyFor("read"),
         this.policyFor("mutating"),
-        this._apiToken
+        () => this._apiToken,
+        this._onEvent
       );
     }
     return this._streams;
@@ -1523,14 +1595,14 @@ var AudD = class {
   /** Sub-namespace for the private fingerprint catalog. NOT for recognition. */
   get customCatalog() {
     if (this._customCatalog === void 0) {
-      this._customCatalog = new CustomCatalog(this._http, this.policyFor("none"));
+      this._customCatalog = new CustomCatalog(this._http, this.policyFor("none"), this._onEvent);
     }
     return this._customCatalog;
   }
   /** Lyrics search + raw-request escape hatch. */
   get advanced() {
     if (this._advanced === void 0) {
-      this._advanced = new Advanced(this._http, this.policyFor("recognition"));
+      this._advanced = new Advanced(this._http, this.policyFor("recognition"), this._onEvent);
     }
     return this._advanced;
   }
@@ -1546,20 +1618,11 @@ var AudD = class {
     const market = opts.market;
     const policy = this.policyFor("recognition");
     const url = `${API_BASE3}/`;
-    const startedAt = Date.now();
-    safeEmit(this._onEvent, {
-      kind: "request",
-      method: "recognize",
+    const resp = await emitAround(
+      this._onEvent,
+      "recognize",
       url,
-      requestId: null,
-      httpStatus: null,
-      elapsedMs: null,
-      errorCode: null,
-      extras: {}
-    });
-    let resp;
-    try {
-      resp = await runRetried4(async () => {
+      () => runRetried(async () => {
         const prepared = await reopen();
         const fields = { ...prepared.fields };
         if (opts.extraParameters) Object.assign(fields, opts.extraParameters);
@@ -1569,30 +1632,8 @@ var AudD = class {
           ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
           ...opts.signal !== void 0 ? { signal: opts.signal } : {}
         });
-      }, policy);
-    } catch (err) {
-      safeEmit(this._onEvent, {
-        kind: "exception",
-        method: "recognize",
-        url,
-        requestId: null,
-        httpStatus: null,
-        elapsedMs: Date.now() - startedAt,
-        errorCode: null,
-        extras: { name: err instanceof Error ? err.name : String(err) }
-      });
-      throw err;
-    }
-    safeEmit(this._onEvent, {
-      kind: "response",
-      method: "recognize",
-      url,
-      requestId: resp.requestId,
-      httpStatus: resp.httpStatus,
-      elapsedMs: Date.now() - startedAt,
-      errorCode: null,
-      extras: {}
-    });
+      }, policy)
+    );
     return decodeRecognize(resp);
   }
   /**
@@ -1605,14 +1646,20 @@ var AudD = class {
     const reopen = prepareSource(source);
     const extra = buildEnterpriseFields(opts);
     const policy = this.policyFor("recognition");
-    const resp = await runRetried4(async () => {
-      const prepared = await reopen();
-      const fields = { ...prepared.fields, ...extra };
-      return this._enterpriseHttp.postForm(`${ENTERPRISE_BASE}/`, fields, {
-        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
-        ...opts.signal !== void 0 ? { signal: opts.signal } : {}
-      });
-    }, policy);
+    const url = `${ENTERPRISE_BASE}/`;
+    const resp = await emitAround(
+      this._onEvent,
+      "recognizeEnterprise",
+      url,
+      () => runRetried(async () => {
+        const prepared = await reopen();
+        const fields = { ...prepared.fields, ...extra };
+        return this._enterpriseHttp.postForm(url, fields, {
+          ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+          ...opts.signal !== void 0 ? { signal: opts.signal } : {}
+        });
+      }, policy)
+    );
     return decodeEnterprise(resp);
   }
   /** Release any underlying resources. (Currently a no-op for `fetch`-based transport.) */