@audd/sdk 1.5.4 → 1.5.6

package/dist/index.d.cts

@@ -228,6 +228,19 @@ interface LongpollOptions {
     timeout?: number;
     /** Bypass the default-on `getCallbackUrl` preflight. */
     skipCallbackCheck?: boolean;
+    /**
+     * Radio id to subscribe to — the SDK derives the 9-char category locally
+     * from `(api_token, radio_id)`. Mutually exclusive with `category`. Only
+     * meaningful on the object-form call site (`longpoll({ radioId: 42 })`).
+     */
+    radioId?: number;
+    /**
+     * Pre-derived 9-char longpoll category. Mutually exclusive with `radioId`.
+     * Only meaningful on the object-form call site
+     * (`longpoll({ category: "abc123def" })`); the positional string form
+     * `longpoll("abc123def")` is the more common way to pass a category.
+     */
+    category?: string;
 }
 declare class Streams {
     private readonly http;
@@ -266,6 +279,17 @@ declare class Streams {
     /**
      * Long-poll the AudD subscription endpoint.
      *
+     * Two call shapes:
+     *
+     * - **Common case** — pass an options object with `radioId`; the SDK
+     *   derives the 9-char category locally from `(api_token, radio_id)`:
+     *   `longpoll({ radioId: 42 })`.
+     * - **Tokenless / pre-derived category** — pass the category as a positional
+     *   string (`longpoll("abc123def")`) or via the object form
+     *   (`longpoll({ category: "abc123def" })`). Useful when the category was
+     *   shared with you (e.g. a browser/mobile client running without the
+     *   api_token).
+     *
      * 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([...])`.
@@ -275,8 +299,16 @@ declare class Streams {
      * callback URL, and the preflight surfaces that misconfiguration as an
      * actionable {@link AudDInvalidRequestError}. Pass `skipCallbackCheck: true`
      * to bypass.
+     *
+     * Throws {@link AudDInvalidRequestError} if the object form supplies both
+     * `radioId` and `category`, or neither.
      */
     longpoll(category: string, opts?: LongpollOptions): Promise<LongpollPoll>;
+    longpoll(opts: LongpollOptions & ({
+        radioId: number;
+    } | {
+        category: string;
+    })): Promise<LongpollPoll>;
     private preflightCallbackUrl;
 }
 

package/dist/index.d.ts

@@ -228,6 +228,19 @@ interface LongpollOptions {
     timeout?: number;
     /** Bypass the default-on `getCallbackUrl` preflight. */
     skipCallbackCheck?: boolean;
+    /**
+     * Radio id to subscribe to — the SDK derives the 9-char category locally
+     * from `(api_token, radio_id)`. Mutually exclusive with `category`. Only
+     * meaningful on the object-form call site (`longpoll({ radioId: 42 })`).
+     */
+    radioId?: number;
+    /**
+     * Pre-derived 9-char longpoll category. Mutually exclusive with `radioId`.
+     * Only meaningful on the object-form call site
+     * (`longpoll({ category: "abc123def" })`); the positional string form
+     * `longpoll("abc123def")` is the more common way to pass a category.
+     */
+    category?: string;
 }
 declare class Streams {
     private readonly http;
@@ -266,6 +279,17 @@ declare class Streams {
     /**
      * Long-poll the AudD subscription endpoint.
      *
+     * Two call shapes:
+     *
+     * - **Common case** — pass an options object with `radioId`; the SDK
+     *   derives the 9-char category locally from `(api_token, radio_id)`:
+     *   `longpoll({ radioId: 42 })`.
+     * - **Tokenless / pre-derived category** — pass the category as a positional
+     *   string (`longpoll("abc123def")`) or via the object form
+     *   (`longpoll({ category: "abc123def" })`). Useful when the category was
+     *   shared with you (e.g. a browser/mobile client running without the
+     *   api_token).
+     *
      * 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([...])`.
@@ -275,8 +299,16 @@ declare class Streams {
      * callback URL, and the preflight surfaces that misconfiguration as an
      * actionable {@link AudDInvalidRequestError}. Pass `skipCallbackCheck: true`
      * to bypass.
+     *
+     * Throws {@link AudDInvalidRequestError} if the object form supplies both
+     * `radioId` and `category`, or neither.
      */
     longpoll(category: string, opts?: LongpollOptions): Promise<LongpollPoll>;
+    longpoll(opts: LongpollOptions & ({
+        radioId: number;
+    } | {
+        category: string;
+    })): Promise<LongpollPoll>;
     private preflightCallbackUrl;
 }
 

package/dist/index.js

@@ -1147,30 +1147,42 @@ var Streams = class {
   parseCallback(body) {
     return parseCallback(body);
   }
-  /**
-   * 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([...])`.
-   *
-   * 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.
-   */
-  async longpoll(category, opts = {}) {
-    if (opts.skipCallbackCheck !== true) {
+  async longpoll(arg1, opts = {}) {
+    let category;
+    let effectiveOpts;
+    if (typeof arg1 === "string") {
+      category = arg1;
+      effectiveOpts = opts;
+    } else {
+      effectiveOpts = arg1;
+      const hasRadioId = arg1.radioId !== void 0;
+      const hasCategory = arg1.category !== void 0;
+      if (hasRadioId && hasCategory) {
+        throw new AudDInvalidRequestError({
+          errorCode: 0,
+          message: "longpoll(): pass exactly one of `radioId` or `category` \u2014 got both.",
+          httpStatus: 0
+        });
+      }
+      if (!hasRadioId && !hasCategory) {
+        throw new AudDInvalidRequestError({
+          errorCode: 0,
+          message: "longpoll(): pass exactly one of `radioId` or `category` \u2014 got neither.",
+          httpStatus: 0
+        });
+      }
+      category = hasRadioId ? this.deriveLongpollCategory(arg1.radioId) : arg1.category;
+    }
+    if (effectiveOpts.skipCallbackCheck !== true) {
       await this.preflightCallbackUrl();
     }
-    const timeoutSec = opts.timeout ?? 50;
+    const timeoutSec = effectiveOpts.timeout ?? 50;
     const httpClient = this.http;
     const readPolicy = this.readPolicy;
     return startLongpoll({
       category,
       timeout: timeoutSec,
-      sinceTime: opts.sinceTime,
+      sinceTime: effectiveOpts.sinceTime,
       fetchOnce: (params, signal) => runRetried(
         () => httpClient.get(`${API_BASE}/longpoll/`, params, { signal }),
         readPolicy