@tidal-music/api 0.28.0 → 0.29.0

package/dist/index.js

@@ -333,16 +333,136 @@ function f(e) {
 	return e.endsWith("/") ? e.substring(0, e.length - 1) : e;
 }
 //#endregion
+//#region src/retry.ts
+var p = {
+	network: {
+		baseDelayMs: 1e3,
+		maxDelayMs: 16e3,
+		maxRetries: 10
+	},
+	status: {
+		baseDelayMs: 500,
+		maxDelayMs: 16e3,
+		maxRetries: 3
+	},
+	timeout: {
+		baseDelayMs: 8e3,
+		maxDelayMs: 32e3,
+		maxRetries: 3
+	}
+}, m = 1e4, h = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]), g = (e) => globalThis.fetch(e);
+function _(e = {}, t = g) {
+	if (e.enabled === !1) return t;
+	let n = y(e);
+	return async (e) => {
+		if (!h.has(e.method.toUpperCase())) return t(e);
+		let r = {
+			network: 0,
+			status: 0,
+			timeout: 0
+		};
+		for (;;) {
+			if (e.signal.aborted) throw S(e.signal.reason);
+			let i = await w(t, e);
+			if (i.kind === "response") {
+				if (!b(i.response.status) || r.status >= n.status.maxRetries) return i.response;
+				await C(x(n.status, r.status), e.signal), r.status += 1;
+				continue;
+			}
+			let a = i.kind;
+			if (r[a] >= n[a].maxRetries) throw i.error;
+			await C(x(n[a], r[a]), e.signal), r[a] += 1;
+		}
+	};
+}
+function v(e, t) {
+	return {
+		baseDelayMs: t?.baseDelayMs ?? e.baseDelayMs,
+		maxDelayMs: t?.maxDelayMs ?? e.maxDelayMs,
+		maxRetries: t?.maxRetries ?? e.maxRetries
+	};
+}
+function y(e) {
+	return {
+		network: v(p.network, e.network),
+		status: v(p.status, e.status),
+		timeout: v(p.timeout, e.timeout)
+	};
+}
+function b(e) {
+	return e === 429 || e >= 500 && e < 600;
+}
+function x(e, t) {
+	let n = .8 + Math.random() * .2;
+	return Math.min(e.baseDelayMs * 2 ** t * n, e.maxDelayMs);
+}
+function S(e) {
+	return e instanceof Error ? e : Error(String(e));
+}
+function C(e, t) {
+	return new Promise((n, r) => {
+		if (t.aborted) {
+			r(S(t.reason));
+			return;
+		}
+		let i, a = () => {
+			clearTimeout(i), r(S(t.reason));
+		};
+		i = setTimeout(() => {
+			t.removeEventListener("abort", a), n();
+		}, e), t.addEventListener("abort", a, { once: !0 });
+	});
+}
+async function w(e, t) {
+	let n = new AbortController(), r = !1, i = setTimeout(() => {
+		r = !0, n.abort();
+	}, m), a = t.signal, o = () => {
+		n.abort();
+	};
+	a.aborted ? n.abort() : a.addEventListener("abort", o, { once: !0 });
+	try {
+		return {
+			kind: "response",
+			response: await T(await e(new Request(t, { signal: n.signal })))
+		};
+	} catch (e) {
+		if (a.aborted) throw e;
+		return r ? {
+			error: e,
+			kind: "timeout"
+		} : {
+			error: e,
+			kind: "network"
+		};
+	} finally {
+		clearTimeout(i), a.removeEventListener("abort", o);
+	}
+}
+async function T(e) {
+	if (!e.body) return e;
+	let t = await e.arrayBuffer();
+	return new Response(t, {
+		headers: e.headers,
+		status: e.status,
+		statusText: e.statusText
+	});
+}
+//#endregion
 //#region src/api.ts
-function p(e, t = "https://openapi.tidal.com/v2/") {
-	let n = { async onRequest({ request: t }) {
+function E(e, t = "https://openapi.tidal.com/v2/", n) {
+	let i = { async onRequest({ request: t }) {
 		let n = await e.getCredentials();
 		return t.headers.set("Authorization", `Bearer ${n.token}`), (t.method === "POST" || t.method === "PATCH" || t.method === "DELETE") && t.headers.set("Content-Type", "application/vnd.api+json"), t;
-	} }, i = r({
+	} }, a = r({
 		baseUrl: t,
+		fetch: _(n),
 		querySerializer: { allowReserved: !0 }
 	});
-	return i.use(n), i;
+	return a.use(i), a;
 }
 //#endregion
-export { p as createAPIClient };
+export { E as createAPIClient };

package/dist/src/api.d.ts

@@ -1,10 +1,13 @@
 import { CredentialsProvider } from '@tidal-music/common';
 import { paths } from './allAPI.generated.js';
+import { RetryOptions } from './retry.js';
 /**
  * Create a Tidal API client with the provided credentials.
  *
  * @param credentialsProvider The credentials provider, from Auth module.
  * @param baseUrl Override the base URL to use for the API client.
+ * @param retryOptions Customize the retry mechanism applied to read-only
+ *   (GET/HEAD/OPTIONS) requests. Pass `{ enabled: false }` to disable it.
  * @returns A Tidal API client.
  */
-export declare function createAPIClient(credentialsProvider: CredentialsProvider, baseUrl?: string): import('openapi-fetch').Client<paths, `${string}/${string}`>;
+export declare function createAPIClient(credentialsProvider: CredentialsProvider, baseUrl?: string, retryOptions?: RetryOptions): import('openapi-fetch').Client<paths, `${string}/${string}`>;

package/dist/src/index.d.ts

@@ -8,3 +8,4 @@
  */
 export type { components } from './allAPI.generated.js';
 export { createAPIClient } from './api.js';
+export type { RetryOptions } from './retry.js';

package/dist/src/retry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * HTTP retry mechanism for the TIDAL API client
+ *
+ * Read-only requests (GET/HEAD/OPTIONS) are retried with exponential backoff
+ * and jitter. The delay before a retry is
+ *
+ *   D = min(B * 2 ** n * j, M)
+ *
+ * where B is the base delay, n is the zero-based retry number, j is a random
+ * jitter factor in [0.8, 1) and M is the maximum delay.
+ *
+ * Write requests (POST/PATCH/PUT/DELETE) are passed through untouched.
+ */
+/** A fetch implementation compatible with openapi-fetch's `fetch` option. */
+type FetchLike = (input: Request) => Promise<Response>;
+type RetryPolicy = {
+    /** Base delay B in milliseconds. */
+    baseDelayMs: number;
+    /** Maximum delay M in milliseconds; the backoff is clamped to this. */
+    maxDelayMs: number;
+    /** Maximum number of retries N, in addition to the initial attempt. */
+    maxRetries: number;
+};
+type RetryCategory = 'network' | 'status' | 'timeout';
+export type RetryOptions = Partial<Record<RetryCategory, Partial<RetryPolicy>>> & {
+    /** Set to `false` to disable retries and the read timeout entirely. */
+    enabled?: boolean;
+};
+/** Per-attempt read timeout in milliseconds. */
+export declare const READ_TIMEOUT_MS = 10000;
+/**
+ * Wraps a fetch implementation with a retry mechanism. The returned function
+ * matches openapi-fetch's `fetch` option signature, so it can be passed
+ * straight to `createClient({ fetch })`.
+ */
+export declare function fetchWithRetry(options?: RetryOptions, baseFetch?: FetchLike): FetchLike;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidal-music/api",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "type": "module",
   "files": [
     "dist"