@audd/sdk 1.5.10 → 1.5.12

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.12";
 
 // 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,10 +313,8 @@ 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;
@@ -263,6 +325,20 @@ function asNumber(v) {
 function asBoolean(v) {
   return typeof v === "boolean" ? v : void 0;
 }
+function parseOffsetToSeconds(o) {
+  if (o === void 0 || o === null) return void 0;
+  if (typeof o === "number") return Number.isFinite(o) ? o : void 0;
+  const t = String(o).trim();
+  if (t === "") return void 0;
+  let total = 0;
+  for (const part of t.split(":")) {
+    if (part.trim() === "") return void 0;
+    const n = Number(part);
+    if (!Number.isFinite(n)) return void 0;
+    total = total * 60 + n;
+  }
+  return total;
+}
 var STREAMING_PROVIDERS = [
   "spotify",
   "apple_music",
@@ -342,7 +418,7 @@ 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 artist = asString(r.artist);
@@ -412,10 +488,12 @@ var ENTERPRISE_MATCH_KEYS = [
   "upc",
   "song_link",
   "start_offset",
-  "end_offset"
+  "end_offset",
+  "start_seconds",
+  "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);
@@ -432,6 +510,8 @@ function parseEnterpriseMatch(raw) {
     songLink,
     startOffset: asNumber(r.start_offset),
     endOffset: asNumber(r.end_offset),
+    startSeconds: void 0,
+    endSeconds: void 0,
     extras: pickExtras(r, ENTERPRISE_MATCH_KEYS),
     rawResponse: r,
     streamingUrl(provider) {
@@ -463,11 +543,20 @@ 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) => {
+    const match = parseEnterpriseMatch(s);
+    if (base !== void 0) {
+      match.startSeconds = base + (match.startOffset ?? 0) / 1e3;
+      match.endSeconds = base + (match.endOffset ?? 0) / 1e3;
+    }
+    return match;
+  });
   return {
-    songs: songsRaw.map(parseEnterpriseMatch),
+    songs,
     offset,
     extras: pickExtras(r, ENTERPRISE_CHUNK_KEYS),
     rawResponse: r
@@ -475,7 +564,7 @@ function parseEnterpriseChunkResult(raw) {
 }
 var STREAM_KEYS = ["radio_id", "url", "stream_running", "longpoll_category"];
 function parseStream(raw) {
-  const r = requireObject(raw, "Stream");
+  const r = asObjectLenient(raw);
   const radioId = asNumber(r.radio_id);
   const url = asString(r.url);
   const streamRunning = asBoolean(r.stream_running);
@@ -505,7 +594,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);
@@ -535,7 +624,7 @@ var STREAM_CALLBACK_MATCH_KEYS = [
   "results"
 ];
 function parseStreamCallbackMatch(raw) {
-  const r = requireObject(raw, "StreamCallbackMatch");
+  const r = asObjectLenient(raw);
   const radioId = asNumber(r.radio_id);
   const resultsRaw = Array.isArray(r.results) ? r.results : [];
   const songs = resultsRaw.filter((x) => asObject(x) !== void 0).map(parseStreamCallbackSong);
@@ -557,7 +646,7 @@ var STREAM_CALLBACK_NOTIFICATION_KEYS = [
   "notification_message"
 ];
 function parseStreamCallbackNotification(raw) {
-  const r = requireObject(raw, "StreamCallbackNotification");
+  const r = asObjectLenient(raw);
   const radioId = asNumber(r.radio_id);
   const code = asNumber(r.notification_code);
   const message = asString(r.notification_message);
@@ -581,7 +670,7 @@ 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 {
@@ -677,6 +766,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://");
 }
@@ -928,13 +1033,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" };
@@ -1013,6 +1118,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) {
@@ -1037,34 +1143,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);
   }
@@ -1111,11 +1209,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
@@ -1157,13 +1255,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
+        )
       )
     });
   }
@@ -1208,26 +1314,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
@@ -1248,42 +1343,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 });
@@ -1307,9 +1396,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)) {
@@ -1325,13 +1417,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) ?? "";
@@ -1354,8 +1439,8 @@ function buildEnterpriseFields(opts) {
   if (opts.skipFirstSeconds !== void 0)
     fields["skip_first_seconds"] = String(opts.skipFirstSeconds);
   if (opts.useTimecode !== void 0) fields["use_timecode"] = opts.useTimecode ? "true" : "false";
-  if (opts.accurateOffsets !== void 0)
-    fields["accurate_offsets"] = opts.accurateOffsets ? "true" : "false";
+  const accurate = opts.accurateOffsets ?? true;
+  fields["accurate_offsets"] = accurate ? "true" : "false";
   return fields;
 }
 function isDeprecationPassThrough(body) {
@@ -1404,7 +1489,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) {
@@ -1413,24 +1498,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;
@@ -1488,7 +1561,8 @@ var AudD = class {
         this._http,
         this.policyFor("read"),
         this.policyFor("mutating"),
-        this._apiToken
+        () => this._apiToken,
+        this._onEvent
       );
     }
     return this._streams;
@@ -1496,14 +1570,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;
   }
@@ -1519,20 +1593,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);
@@ -1542,30 +1607,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);
   }
   /**
@@ -1578,14 +1621,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.) */