@audd/sdk 1.5.7 → 1.5.9

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

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 {
@@ -1127,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() {
@@ -1136,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);
   }
@@ -1393,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);
@@ -1563,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}/`;
@@ -1583,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, {