@audd/sdk 1.5.6 → 1.5.8

package/README.md

@@ -96,14 +96,14 @@ only what you need — each provider you ask for adds latency:
 
 ```ts
 const song = await audd.recognize("https://audd.tech/example.mp3", {
-  return: ["apple_music", "spotify"],
+  returnMetadata: ["apple_music", "spotify"],
 });
 console.log(song?.appleMusic?.url);   // direct Apple Music link
 console.log(song?.spotify?.uri);      // spotify:track:...
 console.log(song?.previewUrl());      // first preview across requested providers, or null
 ```
 
-Valid `return` values: `apple_music`, `spotify`, `deezer`, `napster`,
+Valid `returnMetadata` values: `apple_music`, `spotify`, `deezer`, `napster`,
 `musicbrainz`. Blocks are `undefined` when not requested.
 
 `streamingUrl(provider)` prefers the direct provider URL when you
@@ -121,6 +121,17 @@ console.log(song.extras);       // any non-typed top-level fields
 console.log(song.rawResponse);  // the whole result object as the server returned it
 ```
 
+For the **request** side, every call accepts an `extraParameters` map for additional form fields the typed options don't cover — undocumented parameters or beta features:
+
+```ts
+await audd.recognize(url, {
+  returnMetadata: "apple_music",
+  extraParameters: { some_beta_flag: "true" },
+});
+```
+
+The same `extraParameters` field is on `RecognizeEnterpriseOptions`, `SetCallbackUrlOptions`, and `AddStreamOptions`. Typed options win on collision.
+
 ## Long files (enterprise)
 
 `recognizeEnterprise` accepts files up to several hours and returns a
@@ -273,6 +284,58 @@ 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.
 
+#### Per-framework wiring
+
+The same `handleCallback(req)` works across Node web frameworks — register
+a POST route and pass the request object in.
+
+`Fastify`:
+
+```ts
+import Fastify from "fastify";
+import { handleCallback } from "@audd/sdk";
+
+const app = Fastify();
+app.post("/audd-callback", async (req, reply) => {
+  const { match } = await handleCallback(req);
+  if (match) console.log(`${match.song.artist} — ${match.song.title}`);
+  return { ok: true };
+});
+```
+
+`Koa`:
+
+```ts
+import Koa from "koa";
+import Router from "@koa/router";
+import bodyParser from "koa-bodyparser";
+import { handleCallback } from "@audd/sdk";
+
+const app = new Koa();
+const router = new Router();
+
+app.use(bodyParser());
+router.post("/audd-callback", async (ctx) => {
+  const { match } = await handleCallback(ctx.request);
+  if (match) console.log(`${match.song.artist} — ${match.song.title}`);
+  ctx.body = { ok: true };
+});
+app.use(router.routes());
+```
+
+`Next.js` (App Router, `app/api/audd-callback/route.ts`):
+
+```ts
+import { NextRequest, NextResponse } from "next/server";
+import { handleCallback } from "@audd/sdk";
+
+export async function POST(req: NextRequest) {
+  const { match } = await handleCallback(req);
+  if (match) console.log(`${match.song.artist} — ${match.song.title}`);
+  return NextResponse.json({ ok: true });
+}
+```
+
 ### Receiving events without a callback URL (longpoll)
 
 Useful when you can't expose a public HTTPS receiver. The poll handle
@@ -286,9 +349,9 @@ callback URL set, and the preflight surfaces that as an actionable
 error. Pass `skipCallbackCheck: true` to bypass.
 
 ```ts
-const category = audd.streams.deriveLongpollCategory(12345); // pure, no network call
-const poll = await audd.streams.longpoll(category, { timeout: 30 });
+const radioId = 1; // any integer you choose — your handle for this stream
 
+const poll = await audd.streams.longpoll({ radioId, timeout: 30 });
 for await (const m of poll.matches) {
   console.log(m.song.artist, m.song.title);
 }

package/dist/index.cjs

@@ -25,7 +25,7 @@ function _interopNamespace(e) {
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
 
 // src/version.ts
-var VERSION = "1.4.6";
+var VERSION = "1.5.8";
 
 // src/errors.ts
 var AudDError = class extends Error {
@@ -684,6 +684,8 @@ function shouldRetryResponse(resp, retryClass) {
       return s >= HTTP_SERVER_ERROR_FLOOR;
     case "mutating":
       return false;
+    case "none":
+      return false;
   }
 }
 function shouldRetryError(err, retryClass) {
@@ -694,6 +696,8 @@ function shouldRetryError(err, retryClass) {
       return isPreUploadConnectionError(err);
     case "mutating":
       return isPreUploadConnectionError(err);
+    case "none":
+      return false;
   }
 }
 function sleep(ms) {
@@ -1123,7 +1127,9 @@ var Streams = class {
    */
   async setCallbackUrl(url, opts = {}) {
     const finalUrl = addReturnToUrl(url, opts.returnMetadata);
-    await this.post("setCallbackUrl", { url: finalUrl }, this.mutatingPolicy);
+    const fields = opts.extraParameters ? { ...opts.extraParameters } : {};
+    fields["url"] = finalUrl;
+    await this.post("setCallbackUrl", fields, this.mutatingPolicy);
   }
   /** Get the currently registered callback URL. */
   async getCallbackUrl() {
@@ -1132,10 +1138,9 @@ var Streams = class {
   }
   /** Register a new stream for real-time recognition. */
   async add(opts) {
-    const fields = {
-      url: opts.url,
-      radio_id: String(opts.radioId)
-    };
+    const fields = opts.extraParameters ? { ...opts.extraParameters } : {};
+    fields["url"] = opts.url;
+    fields["radio_id"] = String(opts.radioId);
     if (opts.callbacks !== void 0) fields["callbacks"] = opts.callbacks;
     await this.post("addStream", fields, this.mutatingPolicy);
   }
@@ -1266,12 +1271,12 @@ async function runRetried2(fn, policy) {
   }
 }
 var CustomCatalog = class {
-  constructor(http, mutatingPolicy) {
+  constructor(http, noRetryPolicy) {
     this.http = http;
-    this.mutatingPolicy = mutatingPolicy;
+    this.noRetryPolicy = noRetryPolicy;
   }
   http;
-  mutatingPolicy;
+  noRetryPolicy;
   /**
    * **This is NOT how you submit audio for music recognition.** For
    * recognition, use `audd.recognize()` (or `audd.recognizeEnterprise()` for
@@ -1283,6 +1288,11 @@ var CustomCatalog = class {
    * Calling this again with the same `audioId` re-fingerprints that slot.
    * There is no public list/delete endpoint; track `audioId` ↔ song
    * mappings on your side.
+   *
+   * **No automatic retry.** Custom-catalog upload is metered, and a transport
+   * failure could otherwise cause a silent re-upload that double-charges. Any
+   * 5xx or pre-upload connection error surfaces as a clean exception — the
+   * caller decides whether to retry.
    */
   async add(opts) {
     const reopen = prepareSource(opts.source);
@@ -1291,7 +1301,7 @@ var CustomCatalog = class {
       const prepared = await reopen();
       const fields = { ...prepared.fields, audio_id: audioId };
       return this.http.postForm(UPLOAD_URL, fields);
-    }, this.mutatingPolicy);
+    }, this.noRetryPolicy);
     decodeSuccess2(resp.jsonBody, resp.httpStatus, resp.requestId);
   }
 };
@@ -1384,8 +1394,8 @@ function formatReturn(value) {
   return Array.isArray(value) ? value.join(",") : value;
 }
 function buildEnterpriseFields(opts) {
-  const fields = {};
-  const ret = formatReturn(opts.return);
+  const fields = opts.extraParameters ? { ...opts.extraParameters } : {};
+  const ret = formatReturn(opts.returnMetadata);
   if (ret !== void 0) fields["return"] = ret;
   if (opts.skip !== void 0) fields["skip"] = String(opts.skip);
   if (opts.every !== void 0) fields["every"] = String(opts.every);
@@ -1535,7 +1545,7 @@ 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("mutating"));
+      this._customCatalog = new CustomCatalog(this._http, this.policyFor("none"));
     }
     return this._customCatalog;
   }
@@ -1554,7 +1564,7 @@ var AudD = class {
    */
   async recognize(source, opts = {}) {
     const reopen = prepareSource(source);
-    const ret = formatReturn(opts.return);
+    const ret = formatReturn(opts.returnMetadata);
     const market = opts.market;
     const policy = this.policyFor("recognition");
     const url = `${API_BASE3}/`;
@@ -1574,6 +1584,7 @@ var AudD = class {
       resp = await runRetried4(async () => {
         const prepared = await reopen();
         const fields = { ...prepared.fields };
+        if (opts.extraParameters) Object.assign(fields, opts.extraParameters);
         if (ret !== void 0) fields["return"] = ret;
         if (market !== void 0) fields["market"] = market;
         return this._http.postForm(url, fields, {