@audd/sdk 1.4.9 → 1.5.0

package/dist/index.js

@@ -500,7 +500,7 @@ function parseStream(raw) {
     rawResponse: r
   };
 }
-var STREAM_CALLBACK_RESULT_ENTRY_KEYS = [
+var STREAM_CALLBACK_SONG_KEYS = [
   "artist",
   "title",
   "score",
@@ -508,20 +508,22 @@ var STREAM_CALLBACK_RESULT_ENTRY_KEYS = [
   "release_date",
   "label",
   "song_link",
+  "isrc",
+  "upc",
   "apple_music",
   "spotify",
   "deezer",
   "napster",
   "musicbrainz"
 ];
-function parseStreamCallbackResultEntry(raw) {
-  const r = requireObject(raw, "StreamCallbackResultEntry");
+function parseStreamCallbackSong(raw) {
+  const r = requireObject(raw, "StreamCallbackSong");
   const artist = asString(r.artist);
   const title = asString(r.title);
   const score = asNumber(r.score);
-  if (artist === void 0) throw new TypeError("StreamCallbackResultEntry: artist not string");
-  if (title === void 0) throw new TypeError("StreamCallbackResultEntry: title not string");
-  if (score === void 0) throw new TypeError("StreamCallbackResultEntry: score not number");
+  if (artist === void 0) throw new TypeError("StreamCallbackSong: artist not string");
+  if (title === void 0) throw new TypeError("StreamCallbackSong: title not string");
+  if (score === void 0) throw new TypeError("StreamCallbackSong: score not number");
   const musicbrainz = Array.isArray(r.musicbrainz) ? r.musicbrainz.filter((x) => asObject(x) !== void 0) : void 0;
   return {
     artist,
@@ -531,33 +533,39 @@ function parseStreamCallbackResultEntry(raw) {
     releaseDate: asString(r.release_date),
     label: asString(r.label),
     songLink: asString(r.song_link),
+    isrc: asString(r.isrc),
+    upc: asString(r.upc),
     appleMusic: asObject(r.apple_music),
     spotify: asObject(r.spotify),
     deezer: asObject(r.deezer),
     napster: asObject(r.napster),
     musicbrainz,
-    extras: pickExtras(r, STREAM_CALLBACK_RESULT_ENTRY_KEYS),
-    rawResponse: r
+    extras: pickExtras(r, STREAM_CALLBACK_SONG_KEYS)
   };
 }
-var STREAM_CALLBACK_RESULT_KEYS = [
+var STREAM_CALLBACK_MATCH_KEYS = [
   "radio_id",
   "timestamp",
   "play_length",
   "results"
 ];
-function parseStreamCallbackResult(raw) {
-  const r = requireObject(raw, "StreamCallbackResult");
+function parseStreamCallbackMatch(raw) {
+  const r = requireObject(raw, "StreamCallbackMatch");
   const radioId = asNumber(r.radio_id);
-  if (radioId === void 0) throw new TypeError("StreamCallbackResult: radio_id not number");
+  if (radioId === void 0) throw new TypeError("StreamCallbackMatch: radio_id not number");
   const resultsRaw = r.results;
-  if (!Array.isArray(resultsRaw)) throw new TypeError("StreamCallbackResult: results not array");
+  if (!Array.isArray(resultsRaw)) throw new TypeError("StreamCallbackMatch: results not array");
+  if (resultsRaw.length === 0) throw new TypeError("StreamCallbackMatch: results is empty");
+  const songs = resultsRaw.map(parseStreamCallbackSong);
+  const [first, ...rest] = songs;
+  if (first === void 0) throw new TypeError("StreamCallbackMatch: results is empty");
   return {
     radioId,
     timestamp: asString(r.timestamp),
     playLength: asNumber(r.play_length),
-    results: resultsRaw.map(parseStreamCallbackResultEntry),
-    extras: pickExtras(r, STREAM_CALLBACK_RESULT_KEYS),
+    song: first,
+    alternatives: rest,
+    extras: pickExtras(r, STREAM_CALLBACK_MATCH_KEYS),
     rawResponse: r
   };
 }
@@ -587,39 +595,6 @@ function parseStreamCallbackNotification(raw) {
     rawResponse: r
   };
 }
-function parseStreamCallback(raw) {
-  const r = requireObject(raw, "StreamCallbackPayload");
-  if ("notification" in r) {
-    const notification = parseStreamCallbackNotification(r.notification);
-    const time = asNumber(r.time) ?? null;
-    return {
-      result: null,
-      notification,
-      time,
-      rawPayload: r,
-      get isResult() {
-        return false;
-      },
-      get isNotification() {
-        return true;
-      }
-    };
-  }
-  const inner = requireObject(r.result, "StreamCallbackPayload.result");
-  const result = parseStreamCallbackResult(inner);
-  return {
-    result,
-    notification: null,
-    time: null,
-    rawPayload: r,
-    get isResult() {
-      return true;
-    },
-    get isNotification() {
-      return false;
-    }
-  };
-}
 var LYRICS_KEYS = [
   "artist",
   "title",
@@ -818,6 +793,246 @@ function addReturnToUrl(url, returnMetadata) {
   u.searchParams.set("return", value);
   return u.toString();
 }
+function parseCallback(body) {
+  let raw = body;
+  if (typeof body === "string") {
+    try {
+      raw = JSON.parse(body);
+    } catch (err) {
+      throw new AudDSerializationError(
+        `callback body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        body
+      );
+    }
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new AudDSerializationError(
+      "callback body is not a JSON object",
+      typeof body === "string" ? body : ""
+    );
+  }
+  const r = raw;
+  if ("notification" in r) {
+    let notification;
+    try {
+      notification = parseStreamCallbackNotification(r.notification);
+    } catch (err) {
+      throw new AudDSerializationError(
+        `callback notification: ${err instanceof Error ? err.message : String(err)}`,
+        typeof body === "string" ? body : JSON.stringify(r)
+      );
+    }
+    const t = r.time;
+    if (typeof t === "number") notification.time = t;
+    return { match: null, notification };
+  }
+  if ("result" in r) {
+    let match;
+    try {
+      match = parseStreamCallbackMatch(r.result);
+    } catch (err) {
+      throw new AudDSerializationError(
+        `callback result: ${err instanceof Error ? err.message : String(err)}`,
+        typeof body === "string" ? body : JSON.stringify(r)
+      );
+    }
+    return { match, notification: null };
+  }
+  throw new AudDSerializationError(
+    "callback body has neither result nor notification",
+    typeof body === "string" ? body : JSON.stringify(r)
+  );
+}
+async function handleCallback(req) {
+  if (typeof req.text === "function") {
+    const text = await req.text();
+    return parseCallback(text);
+  }
+  const reqRecord = req;
+  if ("body" in reqRecord && reqRecord.body !== void 0 && reqRecord.body !== null) {
+    const body = reqRecord.body;
+    if (typeof body === "object" && body !== null && Symbol.asyncIterator in body && // Plain Buffer/Uint8Array also has Symbol.iterator — accept those by value.
+    !(body instanceof Uint8Array)) {
+      return parseCallback(await drainAsyncIterable(body));
+    }
+    if (body instanceof Uint8Array) {
+      return parseCallback(new TextDecoder().decode(body));
+    }
+    return parseCallback(body);
+  }
+  if (typeof req === "object" && req !== null && Symbol.asyncIterator in req) {
+    return parseCallback(await drainAsyncIterable(req));
+  }
+  throw new AudDSerializationError(
+    "handleCallback: request has no body, no text() method, and is not async-iterable"
+  );
+}
+async function drainAsyncIterable(it) {
+  const chunks = [];
+  let stringBuf = "";
+  for await (const chunk of it) {
+    if (typeof chunk === "string") {
+      stringBuf += chunk;
+    } else if (chunk instanceof Uint8Array) {
+      chunks.push(chunk);
+    } else if (chunk !== null && chunk !== void 0) {
+      stringBuf += String(chunk);
+    }
+  }
+  if (chunks.length > 0) {
+    let total = 0;
+    for (const c of chunks) total += c.byteLength;
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+      merged.set(c, offset);
+      offset += c.byteLength;
+    }
+    stringBuf = new TextDecoder().decode(merged) + stringBuf;
+  }
+  return stringBuf;
+}
+
+// src/longpollCore.ts
+var HTTP_CLIENT_ERROR_FLOOR = 400;
+var AsyncQueue = class {
+  items = [];
+  waiters = [];
+  done = false;
+  push(value) {
+    if (this.done) return;
+    const w = this.waiters.shift();
+    if (w !== void 0) {
+      w({ value, done: false });
+      return;
+    }
+    this.items.push(value);
+  }
+  finish() {
+    if (this.done) return;
+    this.done = true;
+    while (this.waiters.length > 0) {
+      const w = this.waiters.shift();
+      if (w !== void 0) w({ value: void 0, done: true });
+    }
+  }
+  next() {
+    const item = this.items.shift();
+    if (item !== void 0) return Promise.resolve({ value: item, done: false });
+    if (this.done) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  toIterable() {
+    const next = () => this.next();
+    return {
+      [Symbol.asyncIterator]() {
+        return { next };
+      }
+    };
+  }
+};
+function decodeOne(resp) {
+  if (resp.httpStatus >= HTTP_CLIENT_ERROR_FLOOR) {
+    throw new AudDServerError({
+      errorCode: 0,
+      message: `Longpoll endpoint returned HTTP ${String(resp.httpStatus)}`,
+      httpStatus: resp.httpStatus,
+      requestId: resp.requestId,
+      rawResponse: resp.jsonBody ?? resp.rawText
+    });
+  }
+  const body = resp.jsonBody;
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new AudDSerializationError(
+      "Longpoll response was not a JSON object",
+      resp.rawText
+    );
+  }
+  const dict = body;
+  if ("notification" in dict) {
+    const notification = parseStreamCallbackNotification(dict.notification);
+    const t = dict["time"];
+    if (typeof t === "number") notification.time = t;
+    return { kind: "notification", notification };
+  }
+  if ("result" in dict) {
+    return { kind: "match", match: parseStreamCallbackMatch(dict.result) };
+  }
+  return { kind: "keepalive" };
+}
+function startLongpoll(cfg) {
+  const matches = new AsyncQueue();
+  const notifications = new AsyncQueue();
+  const errors = new AsyncQueue();
+  const controller = new AbortController();
+  let closed = false;
+  const finishAll = () => {
+    matches.finish();
+    notifications.finish();
+    errors.finish();
+  };
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    controller.abort();
+    finishAll();
+  };
+  const run = async () => {
+    let curSince = cfg.sinceTime;
+    while (!closed) {
+      const params = {
+        category: cfg.category,
+        timeout: String(cfg.timeout)
+      };
+      if (curSince !== void 0) params["since_time"] = String(curSince);
+      let resp;
+      try {
+        resp = await cfg.fetchOnce(params, controller.signal);
+      } catch (err) {
+        if (closed) return;
+        if (err instanceof TypeError) {
+          errors.push(new AudDConnectionError(`Network error: ${err.message}`, err));
+        } else if (err !== null && typeof err === "object" && err.name === "AbortError") {
+          if (closed) return;
+          errors.push(new AudDConnectionError("Request was aborted (timeout)", err));
+        } else if (err instanceof Error) {
+          errors.push(err);
+        } else {
+          errors.push(new Error(String(err)));
+        }
+        finishAll();
+        return;
+      }
+      try {
+        const decoded = decodeOne(resp);
+        if (decoded.kind === "match") matches.push(decoded.match);
+        else if (decoded.kind === "notification") notifications.push(decoded.notification);
+      } catch (err) {
+        errors.push(err instanceof Error ? err : new Error(String(err)));
+        finishAll();
+        return;
+      }
+      const dict = resp.jsonBody;
+      if (typeof dict === "object" && dict !== null && !Array.isArray(dict)) {
+        const ts = dict["timestamp"];
+        if (typeof ts === "number") curSince = ts;
+      }
+    }
+  };
+  void run();
+  return {
+    matches: matches.toIterable(),
+    notifications: notifications.toIterable(),
+    errors: errors.toIterable(),
+    close,
+    async [Symbol.asyncDispose]() {
+      close();
+      await Promise.resolve();
+    }
+  };
+}
 
 // src/streams.ts
 var API_BASE = "https://api.audd.io";
@@ -924,69 +1139,58 @@ var Streams = class {
   deriveLongpollCategory(radioId) {
     return deriveLongpollCategory(this.apiToken, radioId);
   }
-  /** Parse a callback POST body into a typed `StreamCallbackPayload`. */
+  /**
+   * 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) {
-    return parseStreamCallback(body);
+    return parseCallback(body);
   }
   /**
-   * Longpoll the AudD subscription endpoint, yielding parsed JSON dicts
-   * (recognition events, notifications, or `{ timeout: ... }` markers).
+   * Long-poll the AudD subscription endpoint.
+   *
+   * 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([...])`.
    *
-   * 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.
+   * 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, opts = {}) {
-    const skipCheck = opts.skipCallbackCheck ?? false;
+  async longpoll(category, opts = {}) {
+    if (opts.skipCallbackCheck !== true) {
+      await this.preflightCallbackUrl();
+    }
     const timeoutSec = opts.timeout ?? 50;
-    const initialSince = opts.sinceTime;
-    const getCallbackUrl = () => this.getCallbackUrl();
-    const httpGet = (params) => this.http.get(`${API_BASE}/longpoll/`, params);
+    const httpClient = this.http;
     const readPolicy = this.readPolicy;
-    return {
-      [Symbol.asyncIterator]() {
-        let preflighted = skipCheck;
-        let curSince = initialSince;
-        return {
-          async next() {
-            if (!preflighted) {
-              try {
-                await getCallbackUrl();
-              } catch (err) {
-                if (err instanceof AudDAPIError && err.errorCode === NO_CALLBACK_ERROR_CODE) {
-                  throw new AudDInvalidRequestError({
-                    errorCode: 0,
-                    message: PREFLIGHT_NO_CALLBACK_HINT,
-                    httpStatus: err.httpStatus,
-                    requestId: err.requestId
-                  });
-                }
-                throw err;
-              }
-              preflighted = true;
-            }
-            const params = {
-              category,
-              timeout: String(timeoutSec)
-            };
-            if (curSince !== void 0) params["since_time"] = String(curSince);
-            const resp = await runRetried(() => httpGet(params), readPolicy);
-            const body = resp.jsonBody;
-            if (typeof body !== "object" || body === null || Array.isArray(body)) {
-              throw new AudDSerializationError(
-                "Unparseable longpoll response",
-                resp.rawText
-              );
-            }
-            const dict = body;
-            const ts = dict["timestamp"];
-            if (typeof ts === "number") curSince = ts;
-            return { value: dict, done: false };
-          }
-        };
+    return startLongpoll({
+      category,
+      timeout: timeoutSec,
+      sinceTime: opts.sinceTime,
+      fetchOnce: (params, signal) => runRetried(
+        () => httpClient.get(`${API_BASE}/longpoll/`, params, { signal }),
+        readPolicy
+      )
+    });
+  }
+  async preflightCallbackUrl() {
+    try {
+      await this.getCallbackUrl();
+    } catch (err) {
+      if (err instanceof AudDAPIError && err.errorCode === NO_CALLBACK_ERROR_CODE) {
+        throw new AudDInvalidRequestError({
+          errorCode: 0,
+          message: PREFLIGHT_NO_CALLBACK_HINT,
+          httpStatus: err.httpStatus,
+          requestId: err.requestId
+        });
       }
-    };
+      throw err;
+    }
   }
 };
 
@@ -1124,7 +1328,7 @@ var Advanced = class {
 var API_BASE3 = "https://api.audd.io";
 var ENTERPRISE_BASE = "https://enterprise.audd.io";
 var DEPRECATED_PARAMS_CODE = 51;
-var HTTP_CLIENT_ERROR_FLOOR = 400;
+var HTTP_CLIENT_ERROR_FLOOR2 = 400;
 var TOKEN_ENV_VAR = "AUDD_API_TOKEN";
 function safeEmit(hook, event) {
   if (hook === void 0) return;
@@ -1172,7 +1376,7 @@ function maybeWarnAndStrip(body) {
 function decodeOrRaise(resp) {
   const body = resp.jsonBody;
   if (typeof body !== "object" || body === null || Array.isArray(body)) {
-    if (resp.httpStatus >= HTTP_CLIENT_ERROR_FLOOR) {
+    if (resp.httpStatus >= HTTP_CLIENT_ERROR_FLOOR2) {
       throw new AudDServerError({
         errorCode: 0,
         message: `HTTP ${String(resp.httpStatus)} with non-JSON response body`,
@@ -1397,6 +1601,6 @@ var AudD = class {
   }
 };
 
-export { AudD, AudDAPIError, AudDAuthenticationError, AudDBlockedError, AudDConnectionError, AudDCustomCatalogAccessError, AudDError, AudDInvalidAudioError, AudDInvalidRequestError, AudDNeedsUpdateError, AudDNotReleasedError, AudDQuotaError, AudDRateLimitError, AudDSerializationError, AudDServerError, AudDStreamLimitError, AudDSubscriptionError, DuplicateReturnParameterError, VERSION, addReturnToUrl, deriveLongpollCategory, errorClassForCode, parseStreamCallback as parseCallback };
+export { AudD, AudDAPIError, AudDAuthenticationError, AudDBlockedError, AudDConnectionError, AudDCustomCatalogAccessError, AudDError, AudDInvalidAudioError, AudDInvalidRequestError, AudDNeedsUpdateError, AudDNotReleasedError, AudDQuotaError, AudDRateLimitError, AudDSerializationError, AudDServerError, AudDStreamLimitError, AudDSubscriptionError, DuplicateReturnParameterError, VERSION, addReturnToUrl, deriveLongpollCategory, errorClassForCode, handleCallback, parseCallback };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map