@audd/sdk 1.4.9 → 1.5.0

package/README.md

@@ -240,40 +240,86 @@ await audd.streams.add({
 const streams = await audd.streams.list();
 ```
 
-Parse incoming callback POSTs into a typed payload:
+### Handling callback POSTs
+
+Drop `handleCallback` into any HTTP handler — Express, Fastify, Hono,
+or the bare `node:http` module. It duck-types the request: a Web
+`Request`, a Node `IncomingMessage`, or a framework request whose body
+has already been parsed all work without configuration.
 
 ```ts
-const payload = audd.streams.parseCallback(reqBodyJson);
-if (payload.isResult) {
-  for (const r of payload.result!.results) {
-    console.log(r.artist, r.title, r.score);
+import express from "express";
+import { handleCallback } from "@audd/sdk";
+
+const app = express();
+app.use(express.json());
+
+app.post("/audd-callback", async (req, res) => {
+  const { match, notification } = await handleCallback(req);
+  if (match) {
+    console.log(`${match.song.artist} - ${match.song.title}  score=${match.song.score}`);
+    for (const alt of match.alternatives) {
+      // alternatives are variant catalog releases — different artist/title is possible
+      console.log(`  alt: ${alt.artist} - ${alt.title}`);
+    }
+  } else if (notification) {
+    console.log(`#${notification.notificationCode} ${notification.notificationMessage}`);
   }
-} else if (payload.isNotification) {
-  console.log(payload.notification!.notificationCode,
-              payload.notification!.notificationMessage);
-}
+  res.json({ ok: true });
+});
 ```
 
+If you already have the body bytes (queue consumer, replay tool), call
+`parseCallback(body)` directly — it accepts a parsed JSON object or a
+JSON string and returns the same `{ match, notification }` shape.
+
 ### Receiving events without a callback URL (longpoll)
 
-Useful when you can't expose a public HTTPS receiver. Before the first
-event, the SDK runs a one-time `getCallbackUrl` preflight — AudD
-silently discards events for accounts without any callback URL set, so
-this catches the trap early. Pass `skipCallbackCheck: true` to opt out.
+Useful when you can't expose a public HTTPS receiver. The poll handle
+exposes three async-iterables — `matches`, `notifications`, `errors` —
+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 without any
+callback URL set, and the preflight surfaces that as an actionable
+error. Pass `skipCallbackCheck: true` to bypass.
 
 ```ts
-for await (const event of audd.streams.longpoll(category, { timeout: 30 })) {
-  console.log(event);
+const category = audd.streams.deriveLongpollCategory(12345); // pure, no network call
+const poll = await audd.streams.longpoll(category, { timeout: 30 });
+
+for await (const m of poll.matches) {
+  console.log(m.song.artist, m.song.title);
 }
 ```
 
-`category` is a 9-character string derived locally from your token and
-`radioId`:
+Consume matches and notifications concurrently:
 
 ```ts
-const category = audd.streams.deriveLongpollCategory(12345);
+await Promise.all([
+  (async () => {
+    for await (const m of poll.matches) {
+      console.log("match:", m.song.artist, m.song.title);
+    }
+  })(),
+  (async () => {
+    for await (const n of poll.notifications) {
+      console.log("notification:", n.notificationMessage);
+    }
+  })(),
+  (async () => {
+    for await (const err of poll.errors) {
+      console.error(err);
+      poll.close();
+    }
+  })(),
+]);
 ```
 
+`poll.close()` (or the `await using` resource-management form) tears
+down the background loop and completes all three iterables.
+
 ### Browser / widget consumers
 
 The `audd/longpoll` sub-entry exports a tokenless `LongpollConsumer` for
@@ -285,8 +331,9 @@ client out of the resulting bundle.
 import { LongpollConsumer } from "@audd/sdk/longpoll";
 
 const consumer = new LongpollConsumer("abc123def");
-for await (const event of consumer.iterate({ timeout: 30 })) {
-  console.log(event);
+const poll = consumer.iterate({ timeout: 30 });
+for await (const m of poll.matches) {
+  console.log(m.song.artist, m.song.title);
 }
 ```
 

package/dist/index.cjs

@@ -522,7 +522,7 @@ function parseStream(raw) {
     rawResponse: r
   };
 }
-var STREAM_CALLBACK_RESULT_ENTRY_KEYS = [
+var STREAM_CALLBACK_SONG_KEYS = [
   "artist",
   "title",
   "score",
@@ -530,20 +530,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,
@@ -553,33 +555,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
   };
 }
@@ -609,39 +617,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",
@@ -840,6 +815,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";
@@ -946,69 +1161,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;
+    }
   }
 };
 
@@ -1146,7 +1350,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;
@@ -1194,7 +1398,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`,
@@ -1441,6 +1645,7 @@ exports.VERSION = VERSION;
 exports.addReturnToUrl = addReturnToUrl;
 exports.deriveLongpollCategory = deriveLongpollCategory;
 exports.errorClassForCode = errorClassForCode;
-exports.parseCallback = parseStreamCallback;
+exports.handleCallback = handleCallback;
+exports.parseCallback = parseCallback;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map