@audd/sdk 1.4.7 → 1.5.0

package/README.md

@@ -4,16 +4,9 @@
 [![Contract](https://github.com/AudDMusic/audd-node/actions/workflows/contract.yml/badge.svg)](https://github.com/AudDMusic/audd-node/actions/workflows/contract.yml)
 [![npm](https://img.shields.io/npm/v/@audd/sdk.svg)](https://www.npmjs.com/package/@audd/sdk)
 
-Official TypeScript / Node.js SDK for the [AudD](https://audd.io) music
-recognition API.
+Official TypeScript / Node.js SDK for [AudD](https://audd.io) — music recognition from a short audio clip, a long audio file, or a live stream.
 
-AudD identifies music from a short audio clip, a URL, a long file, or a
-live stream. The HTTPS API is a plain form-POST — every endpoint is
-documented at **[docs.audd.io](https://docs.audd.io)** and you can call
-it from anywhere `fetch` works. This package adds typed result models
-with helpers for cover art, streaming-provider URLs, and previews;
-`AbortSignal`-aware async; ESM and CJS dual-build; and a separate
-browser-safe entry point for tokenless longpoll widgets.
+The [API itself](https://docs.audd.io) is so simple that it can be easily used even without an SDK.
 
 ## Quickstart
 
@@ -21,12 +14,14 @@ browser-safe entry point for tokenless longpoll widgets.
 npm install @audd/sdk
 ```
 
+Get your API token at [dashboard.audd.io](https://dashboard.audd.io).
+
 Recognize from a URL:
 
 ```ts
 import { AudD } from "@audd/sdk";
 
-const audd = new AudD("test"); // grab a real token at https://dashboard.audd.io
+const audd = new AudD("test");
 const song = await audd.recognize("https://audd.tech/example.mp3");
 if (song) {
   console.log(`${song.artist} — ${song.title}`);
@@ -132,16 +127,18 @@ console.log(song.rawResponse);  // the whole result object as the server returne
 flat array of matches:
 
 ```ts
-const matches = await audd.recognizeEnterprise("./show.mp3", {
-  return: ["apple_music", "musicbrainz"],
-  limit: 20,
-});
+const matches = await audd.recognizeEnterprise("./show.mp3", { limit: 20 });
 
 for (const m of matches) {
-  console.log(m.timecode, m.score, m.artist, m.title, m.isrc);
+  console.log(m.timecode, m.artist, m.title);
 }
 ```
 
+`EnterpriseMatch` carries the same core tags plus `score`, `startOffset`,
+`endOffset`, `isrc`, `upc`. Access to `isrc`, `upc`, and `score` requires
+a Startup plan or higher — [contact us](mailto:api@audd.io) for enterprise
+features.
+
 The default per-call timeout is **1 hour** for this endpoint (60s for
 standard recognition); override with `timeoutMs`.
 
@@ -243,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
@@ -288,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);
 }
 ```