@audd/sdk 1.5.6 → 1.5.8

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { S as StreamCallbackMatch, a as StreamCallbackNotification, H as HttpClient, b as Stream, L as LongpollPoll, c as LyricsResult, F as FetchLike, R as RecognitionResult, E as EnterpriseMatch } from './longpollCore-DMBdcGSM.cjs';
 export { d as EnterpriseChunkResult, e as StreamCallbackSong, f as StreamingProvider } from './longpollCore-DMBdcGSM.cjs';
 
-declare const VERSION = "1.4.6";
+declare const VERSION = "1.5.8";
 
 /**
  * Auto-detect what kind of audio source the caller passed and convert to
@@ -38,11 +38,15 @@ type Source = string | URL | Blob | Uint8Array;
  * - RECOGNITION — `recognize`, `recognizeEnterprise`, `advanced.findLyrics`:
  *                 retry on pre-upload connection failures + 5xx.
  *                 DO NOT retry on read-timeout-after-upload (cost protection).
- * - MUTATING    — `streams.add`, `streams.delete`, etc., `customCatalog.add`:
+ * - MUTATING    — `streams.add`, `streams.delete`, etc.:
  *                 retry only on pre-upload connection failures. DO NOT retry
  *                 5xx (the side effect may have happened).
+ * - NONE        — `customCatalog.add`: never retry. Custom-catalog upload is
+ *                 metered; auto-retry on transport failure could double-charge
+ *                 for the same audio fingerprinting. Surface a clean error and
+ *                 let the caller decide.
  */
-type RetryClass = "read" | "recognition" | "mutating";
+type RetryClass = "read" | "recognition" | "mutating" | "none";
 interface RetryPolicy {
     retryClass: RetryClass;
     maxAttempts: number;
@@ -215,12 +219,22 @@ declare function handleCallback(req: CallbackRequestLike): Promise<ParsedCallbac
 
 interface SetCallbackUrlOptions {
     returnMetadata?: string | string[];
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * (`url`) win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface AddStreamOptions {
     url: string;
     radioId: number;
     /** "before" delivers callbacks at song start; default delivers at song end. */
     callbacks?: "before" | string;
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * (`url`, `radioId`, `callbacks`) win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface LongpollOptions {
     sinceTime?: number;
@@ -318,8 +332,8 @@ interface CustomCatalogAddOptions {
 }
 declare class CustomCatalog {
     private readonly http;
-    private readonly mutatingPolicy;
-    constructor(http: HttpClient, mutatingPolicy: RetryPolicy);
+    private readonly noRetryPolicy;
+    constructor(http: HttpClient, noRetryPolicy: RetryPolicy);
     /**
      * **This is NOT how you submit audio for music recognition.** For
      * recognition, use `audd.recognize()` (or `audd.recognizeEnterprise()` for
@@ -331,6 +345,11 @@ declare class CustomCatalog {
      * 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.
      */
     add(opts: CustomCatalogAddOptions): Promise<void>;
 }
@@ -388,7 +407,7 @@ interface AudDOptions {
 }
 type ReturnMetadata = "apple_music" | "spotify" | "deezer" | "napster" | "musicbrainz" | string;
 interface RecognizeOptions {
-    return?: ReturnMetadata | ReturnMetadata[];
+    returnMetadata?: ReturnMetadata | ReturnMetadata[];
     market?: string;
     /** Per-call timeout in ms; overrides the client default. */
     timeoutMs?: number;
@@ -399,9 +418,14 @@ interface RecognizeOptions {
      * already done metered work and the credit is consumed regardless.
      */
     signal?: AbortSignal;
+    /**
+     * Additional form fields the typed options don't cover — undocumented
+     * parameters, beta features. Typed options win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface RecognizeEnterpriseOptions {
-    return?: ReturnMetadata | ReturnMetadata[];
+    returnMetadata?: ReturnMetadata | ReturnMetadata[];
     skip?: number;
     every?: number;
     limit?: number;
@@ -414,6 +438,11 @@ interface RecognizeEnterpriseOptions {
      * For multi-hour enterprise calls, this is the right way to cancel.
      */
     signal?: AbortSignal;
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 /**
  * The AudD client. Async-only — every method returns a `Promise`.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { S as StreamCallbackMatch, a as StreamCallbackNotification, H as HttpClient, b as Stream, L as LongpollPoll, c as LyricsResult, F as FetchLike, R as RecognitionResult, E as EnterpriseMatch } from './longpollCore-DMBdcGSM.js';
 export { d as EnterpriseChunkResult, e as StreamCallbackSong, f as StreamingProvider } from './longpollCore-DMBdcGSM.js';
 
-declare const VERSION = "1.4.6";
+declare const VERSION = "1.5.8";
 
 /**
  * Auto-detect what kind of audio source the caller passed and convert to
@@ -38,11 +38,15 @@ type Source = string | URL | Blob | Uint8Array;
  * - RECOGNITION — `recognize`, `recognizeEnterprise`, `advanced.findLyrics`:
  *                 retry on pre-upload connection failures + 5xx.
  *                 DO NOT retry on read-timeout-after-upload (cost protection).
- * - MUTATING    — `streams.add`, `streams.delete`, etc., `customCatalog.add`:
+ * - MUTATING    — `streams.add`, `streams.delete`, etc.:
  *                 retry only on pre-upload connection failures. DO NOT retry
  *                 5xx (the side effect may have happened).
+ * - NONE        — `customCatalog.add`: never retry. Custom-catalog upload is
+ *                 metered; auto-retry on transport failure could double-charge
+ *                 for the same audio fingerprinting. Surface a clean error and
+ *                 let the caller decide.
  */
-type RetryClass = "read" | "recognition" | "mutating";
+type RetryClass = "read" | "recognition" | "mutating" | "none";
 interface RetryPolicy {
     retryClass: RetryClass;
     maxAttempts: number;
@@ -215,12 +219,22 @@ declare function handleCallback(req: CallbackRequestLike): Promise<ParsedCallbac
 
 interface SetCallbackUrlOptions {
     returnMetadata?: string | string[];
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * (`url`) win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface AddStreamOptions {
     url: string;
     radioId: number;
     /** "before" delivers callbacks at song start; default delivers at song end. */
     callbacks?: "before" | string;
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * (`url`, `radioId`, `callbacks`) win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface LongpollOptions {
     sinceTime?: number;
@@ -318,8 +332,8 @@ interface CustomCatalogAddOptions {
 }
 declare class CustomCatalog {
     private readonly http;
-    private readonly mutatingPolicy;
-    constructor(http: HttpClient, mutatingPolicy: RetryPolicy);
+    private readonly noRetryPolicy;
+    constructor(http: HttpClient, noRetryPolicy: RetryPolicy);
     /**
      * **This is NOT how you submit audio for music recognition.** For
      * recognition, use `audd.recognize()` (or `audd.recognizeEnterprise()` for
@@ -331,6 +345,11 @@ declare class CustomCatalog {
      * 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.
      */
     add(opts: CustomCatalogAddOptions): Promise<void>;
 }
@@ -388,7 +407,7 @@ interface AudDOptions {
 }
 type ReturnMetadata = "apple_music" | "spotify" | "deezer" | "napster" | "musicbrainz" | string;
 interface RecognizeOptions {
-    return?: ReturnMetadata | ReturnMetadata[];
+    returnMetadata?: ReturnMetadata | ReturnMetadata[];
     market?: string;
     /** Per-call timeout in ms; overrides the client default. */
     timeoutMs?: number;
@@ -399,9 +418,14 @@ interface RecognizeOptions {
      * already done metered work and the credit is consumed regardless.
      */
     signal?: AbortSignal;
+    /**
+     * Additional form fields the typed options don't cover — undocumented
+     * parameters, beta features. Typed options win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 interface RecognizeEnterpriseOptions {
-    return?: ReturnMetadata | ReturnMetadata[];
+    returnMetadata?: ReturnMetadata | ReturnMetadata[];
     skip?: number;
     every?: number;
     limit?: number;
@@ -414,6 +438,11 @@ interface RecognizeEnterpriseOptions {
      * For multi-hour enterprise calls, this is the right way to cancel.
      */
     signal?: AbortSignal;
+    /**
+     * Additional form fields the typed options don't cover. Typed options
+     * win on collision.
+     */
+    extraParameters?: Record<string, string>;
 }
 /**
  * The AudD client. Async-only — every method returns a `Promise`.

package/dist/index.js

@@ -3,7 +3,7 @@ import * as path from 'path';
 import { createHash } from 'crypto';
 
 // src/version.ts
-var VERSION = "1.4.6";
+var VERSION = "1.5.8";
 
 // src/errors.ts
 var AudDError = class extends Error {
@@ -662,6 +662,8 @@ function shouldRetryResponse(resp, retryClass) {
       return s >= HTTP_SERVER_ERROR_FLOOR;
     case "mutating":
       return false;
+    case "none":
+      return false;
   }
 }
 function shouldRetryError(err, retryClass) {
@@ -672,6 +674,8 @@ function shouldRetryError(err, retryClass) {
       return isPreUploadConnectionError(err);
     case "mutating":
       return isPreUploadConnectionError(err);
+    case "none":
+      return false;
   }
 }
 function sleep(ms) {
@@ -1101,7 +1105,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() {
@@ -1110,10 +1116,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);
   }
@@ -1244,12 +1249,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
@@ -1261,6 +1266,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);
@@ -1269,7 +1279,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);
   }
 };
@@ -1362,8 +1372,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);
@@ -1513,7 +1523,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;
   }
@@ -1532,7 +1542,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}/`;
@@ -1552,6 +1562,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, {