@backblaze-labs/b2-sdk 0.1.0

package/dist/http/retry.d.ts

@@ -0,0 +1,34 @@
+/** Configuration for retry behavior on transient failures. */
+export interface RetryOptions {
+    /** Maximum number of retry attempts before giving up. */
+    readonly maxRetries: number;
+    /** Upper bound on retry delay in milliseconds, regardless of backoff calculation. */
+    readonly maxRetryDelayMs: number;
+    /** Base delay in milliseconds for the first retry. Doubles on each subsequent attempt. */
+    readonly initialRetryDelayMs: number;
+}
+/** Default retry settings: 5 retries, 1s initial delay, 64s max delay. */
+export declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
+/**
+ * Computes the delay before the next retry using exponential backoff with jitter.
+ * If a `Retry-After` value is provided by the server, it takes precedence over
+ * the calculated backoff (still capped at {@link RetryOptions.maxRetryDelayMs}).
+ *
+ * @param attempt - Zero-based retry attempt index.
+ * @param options - Retry configuration with delay bounds.
+ * @param retryAfter - Server-provided retry delay in seconds, if any.
+ *
+ * @returns The delay in milliseconds before the next retry attempt.
+ */
+export declare function computeBackoff(attempt: number, options: RetryOptions, retryAfter?: number): number;
+/**
+ * Returns a promise that resolves after the given delay. Supports cancellation
+ * via an optional AbortSignal.
+ *
+ * @param ms - Delay in milliseconds.
+ * @param signal - Optional abort signal to cancel the sleep early.
+ *
+ * @returns A promise that resolves when the delay elapses or rejects if aborted.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/http/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/http/retry.js"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;CACrC;AAED,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrE"}

package/dist/http/retry.js

@@ -0,0 +1,36 @@
+const DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 5,
+  maxRetryDelayMs: 64e3,
+  initialRetryDelayMs: 1e3
+};
+function computeBackoff(attempt, options, retryAfter) {
+  if (retryAfter !== void 0 && retryAfter > 0) {
+    return Math.min(retryAfter * 1e3, options.maxRetryDelayMs);
+  }
+  const base = options.initialRetryDelayMs * 2 ** attempt;
+  const jitter = Math.random() * base * 0.5;
+  return Math.min(base + jitter, options.maxRetryDelayMs);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+export {
+  DEFAULT_RETRY_OPTIONS,
+  computeBackoff,
+  sleep
+};
+//# sourceMappingURL=retry.js.map

package/dist/http/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sources":["../../src/http/retry.ts"],"sourcesContent":["/** Configuration for retry behavior on transient failures. */\nexport interface RetryOptions {\n  /** Maximum number of retry attempts before giving up. */\n  readonly maxRetries: number\n  /** Upper bound on retry delay in milliseconds, regardless of backoff calculation. */\n  readonly maxRetryDelayMs: number\n  /** Base delay in milliseconds for the first retry. Doubles on each subsequent attempt. */\n  readonly initialRetryDelayMs: number\n}\n\n/** Default retry settings: 5 retries, 1s initial delay, 64s max delay. */\nexport const DEFAULT_RETRY_OPTIONS: RetryOptions = {\n  maxRetries: 5,\n  maxRetryDelayMs: 64_000,\n  initialRetryDelayMs: 1_000,\n}\n\n/**\n * Computes the delay before the next retry using exponential backoff with jitter.\n * If a `Retry-After` value is provided by the server, it takes precedence over\n * the calculated backoff (still capped at {@link RetryOptions.maxRetryDelayMs}).\n *\n * @param attempt - Zero-based retry attempt index.\n * @param options - Retry configuration with delay bounds.\n * @param retryAfter - Server-provided retry delay in seconds, if any.\n *\n * @returns The delay in milliseconds before the next retry attempt.\n */\nexport function computeBackoff(\n  attempt: number,\n  options: RetryOptions,\n  retryAfter?: number,\n): number {\n  if (retryAfter !== undefined && retryAfter > 0) {\n    return Math.min(retryAfter * 1000, options.maxRetryDelayMs)\n  }\n  const base = options.initialRetryDelayMs * 2 ** attempt\n  const jitter = Math.random() * base * 0.5\n  return Math.min(base + jitter, options.maxRetryDelayMs)\n}\n\n/**\n * Returns a promise that resolves after the given delay. Supports cancellation\n * via an optional AbortSignal.\n *\n * @param ms - Delay in milliseconds.\n * @param signal - Optional abort signal to cancel the sleep early.\n *\n * @returns A promise that resolves when the delay elapses or rejects if aborted.\n */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'))\n      return\n    }\n    const timer = setTimeout(resolve, ms)\n    signal?.addEventListener(\n      'abort',\n      () => {\n        clearTimeout(timer)\n        reject(signal.reason ?? new DOMException('Aborted', 'AbortError'))\n      },\n      { once: true },\n    )\n  })\n}\n"],"names":[],"mappings":"AAWO,MAAM,wBAAsC;AAAA,EACjD,YAAY;AAAA,EACZ,iBAAiB;AAAA,EACjB,qBAAqB;AACvB;AAaO,SAAS,eACd,SACA,SACA,YACQ;AACR,MAAI,eAAe,UAAa,aAAa,GAAG;AAC9C,WAAO,KAAK,IAAI,aAAa,KAAM,QAAQ,eAAe;AAAA,EAC5D;AACA,QAAM,OAAO,QAAQ,sBAAsB,KAAK;AAChD,QAAM,SAAS,KAAK,OAAA,IAAW,OAAO;AACtC,SAAO,KAAK,IAAI,OAAO,QAAQ,QAAQ,eAAe;AACxD;AAWO,SAAS,MAAM,IAAY,QAAqC;AACrE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,QAAI,QAAQ,SAAS;AACnB,aAAO,OAAO,UAAU,IAAI,aAAa,WAAW,YAAY,CAAC;AACjE;AAAA,IACF;AACA,UAAM,QAAQ,WAAW,SAAS,EAAE;AACpC,YAAQ;AAAA,MACN;AAAA,MACA,MAAM;AACJ,qBAAa,KAAK;AAClB,eAAO,OAAO,UAAU,IAAI,aAAa,WAAW,YAAY,CAAC;AAAA,MACnE;AAAA,MACA,EAAE,MAAM,KAAA;AAAA,IAAK;AAAA,EAEjB,CAAC;AACH;"}

package/dist/http/transport.cjs

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const errors_index = require("../errors/index.cjs");
+const retry = require("./retry.cjs");
+const urlGuard = require("./url-guard.cjs");
+const userAgent = require("./user-agent.cjs");
+class FetchTransport {
+  /** User-Agent string sent with every request. */
+  userAgent;
+  /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
+  urlGuard;
+  /**
+   * Creates a new FetchTransport.
+   * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
+   */
+  constructor(options) {
+    this.userAgent = userAgent.getUserAgent(options?.userAgent);
+    this.urlGuard = options?.urlGuard ?? new urlGuard.UrlGuard();
+  }
+  /**
+   * Sends the request using the global `fetch` function.
+   * @param request - The HTTP request to execute.
+   *
+   * @returns The HTTP response.
+   *
+   * @throws B2SsrfError when the URL fails the configured SSRF guard.
+   */
+  async send(request) {
+    this.urlGuard.check(request.url);
+    const headers = new Headers(request.headers);
+    if (!headers.has("User-Agent")) {
+      headers.set("User-Agent", this.userAgent);
+    }
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers,
+      body: request.body ?? null,
+      ...request.signal !== void 0 ? { signal: request.signal } : {}
+    });
+    return {
+      status: response.status,
+      headers: response.headers,
+      body: response.body,
+      json: () => response.json(),
+      text: () => response.text(),
+      arrayBuffer: () => response.arrayBuffer()
+    };
+  }
+}
+class RetryTransport {
+  /** The wrapped transport that performs actual HTTP requests. */
+  inner;
+  /** Resolved retry options (defaults merged with user overrides). */
+  options;
+  /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
+  onReauth;
+  /** Sleep implementation used between retries; injectable for tests. */
+  sleepImpl;
+  /**
+   * Creates a new RetryTransport.
+   * @param opts - Retry transport configuration.
+   */
+  constructor(opts) {
+    this.inner = opts.transport;
+    this.options = { ...retry.DEFAULT_RETRY_OPTIONS, ...opts.retry };
+    if (opts.onReauth !== void 0) this.onReauth = opts.onReauth;
+    this.sleepImpl = opts.sleepImpl ?? retry.sleep;
+  }
+  /**
+   * Sends the request with automatic retry on transient failures.
+   * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
+   * @param originalRequest - The HTTP request to execute. The caller's
+   *   reference is not mutated; on reauth, a copy with a refreshed
+   *   Authorization header is sent.
+   *
+   * @returns The HTTP response.
+   */
+  async send(originalRequest) {
+    let request = originalRequest;
+    let lastError;
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      if (attempt > 0 && lastError) {
+        const retryAfter = lastError instanceof errors_index.NetworkError ? void 0 : lastError.retryAfter;
+        const delay = retry.computeBackoff(attempt - 1, this.options, retryAfter);
+        await this.sleepImpl(delay, request.signal);
+      }
+      try {
+        const response = await this.inner.send(request);
+        if (response.status >= 200 && response.status < 300) {
+          return response;
+        }
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = {
+            status: response.status,
+            code: "internal_error",
+            message: `HTTP ${response.status}`
+          };
+        }
+        const retryAfterHeader = response.headers.get("Retry-After");
+        const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : void 0;
+        const requestId = response.headers.get("X-Bz-Request-Id") ?? void 0;
+        const error = errors_index.classifyError(errorBody, {
+          ...retryAfterSec !== void 0 ? { retryAfter: retryAfterSec } : {},
+          ...requestId !== void 0 ? { requestId } : {}
+        });
+        if (error instanceof errors_index.ExpiredAuthTokenError && this.onReauth) {
+          const freshToken = await this.onReauth();
+          request = {
+            ...request,
+            headers: { ...request.headers ?? {}, Authorization: freshToken }
+          };
+          continue;
+        }
+        if (!error.retryable || attempt === this.options.maxRetries) {
+          throw error;
+        }
+        lastError = error;
+      } catch (err) {
+        if (err instanceof errors_index.B2Error || err instanceof errors_index.NetworkError) {
+          throw err;
+        }
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw err;
+        }
+        const networkErr = new errors_index.NetworkError(
+          err instanceof Error ? err.message : "Network error",
+          err
+        );
+        if (attempt === this.options.maxRetries) {
+          throw networkErr;
+        }
+        lastError = networkErr;
+      }
+    }
+    throw lastError ?? new errors_index.NetworkError("Max retries exceeded");
+  }
+}
+exports.FetchTransport = FetchTransport;
+exports.RetryTransport = RetryTransport;
+//# sourceMappingURL=transport.cjs.map

package/dist/http/transport.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.cjs","sources":["../../src/http/transport.ts"],"sourcesContent":["import { B2Error, ExpiredAuthTokenError, NetworkError, classifyError } from '../errors/index.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport { DEFAULT_RETRY_OPTIONS, type RetryOptions, computeBackoff, sleep } from './retry.ts'\nimport { UrlGuard } from './url-guard.ts'\nimport { getUserAgent } from './user-agent.ts'\n\n/** Describes an outgoing HTTP request to the B2 API. */\nexport interface HttpRequest {\n  /** Fully qualified URL to send the request to. */\n  readonly url: string\n  /** HTTP method. B2 uses GET for downloads (HEAD to fetch only headers) and POST for all other operations. */\n  readonly method: 'GET' | 'HEAD' | 'POST'\n  /** Request headers. Authorization and content-type are typically included. */\n  readonly headers?: Record<string, string>\n  /** Request body. Used for POST requests (JSON payloads or file uploads). */\n  readonly body?: BodyInit | null\n  /** Optional abort signal for request cancellation. */\n  readonly signal?: AbortSignal\n}\n\n/** Represents a parsed HTTP response from the B2 API. */\nexport interface HttpResponse {\n  /** HTTP status code. */\n  readonly status: number\n  /** Response headers. */\n  readonly headers: Headers\n  /** Response body as a readable stream, or null for empty responses. */\n  readonly body: ReadableStream<Uint8Array> | null\n  /** Parses the response body as JSON. */\n  json<T>(): Promise<T>\n  /** Reads the response body as a UTF-8 string. */\n  text(): Promise<string>\n  /** Reads the response body as an ArrayBuffer. */\n  arrayBuffer(): Promise<ArrayBuffer>\n}\n\n/**\n * Transport layer abstraction for sending HTTP requests.\n * Implementations handle the actual network I/O and can be composed\n * (e.g. wrapping a {@link FetchTransport} with a {@link RetryTransport}).\n */\nexport interface HttpTransport {\n  /** Sends an HTTP request and returns the response. */\n  send(request: HttpRequest): Promise<HttpResponse>\n}\n\n/**\n * Default transport implementation using the global `fetch` API.\n * Automatically sets the User-Agent header on each request and applies the\n * SSRF {@link UrlGuard} (if configured) before opening the connection.\n */\nexport class FetchTransport implements HttpTransport {\n  /** User-Agent string sent with every request. */\n  private readonly userAgent: string\n  /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */\n  readonly urlGuard: UrlGuard\n\n  /**\n   * Creates a new FetchTransport.\n   * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.\n   */\n  constructor(options?: { userAgent?: string; urlGuard?: UrlGuard }) {\n    this.userAgent = getUserAgent(options?.userAgent)\n    this.urlGuard = options?.urlGuard ?? new UrlGuard()\n  }\n\n  /**\n   * Sends the request using the global `fetch` function.\n   * @param request - The HTTP request to execute.\n   *\n   * @returns The HTTP response.\n   *\n   * @throws B2SsrfError when the URL fails the configured SSRF guard.\n   */\n  async send(request: HttpRequest): Promise<HttpResponse> {\n    this.urlGuard.check(request.url)\n\n    const headers = new Headers(request.headers)\n    if (!headers.has('User-Agent')) {\n      headers.set('User-Agent', this.userAgent)\n    }\n\n    const response = await fetch(request.url, {\n      method: request.method,\n      headers,\n      body: request.body ?? null,\n      ...(request.signal !== undefined ? { signal: request.signal } : {}),\n    })\n\n    return {\n      status: response.status,\n      headers: response.headers,\n      body: response.body,\n      json: <T>() => response.json() as Promise<T>,\n      text: () => response.text(),\n      arrayBuffer: () => response.arrayBuffer(),\n    }\n  }\n}\n\n/** Configuration for {@link RetryTransport}. */\nexport interface RetryTransportOptions {\n  /** The underlying transport to delegate requests to. */\n  readonly transport: HttpTransport\n  /** Override default retry settings (max retries, delays). */\n  readonly retry?: Partial<RetryOptions>\n  /**\n   * Callback invoked on expired auth token errors. Must refresh\n   * credentials AND return the fresh auth token. The transport\n   * substitutes the new token into `request.headers.Authorization`\n   * before retrying — without this, the retried request would still\n   * carry the expired token captured by the original caller and the\n   * loop would never make progress.\n   */\n  readonly onReauth?: () => Promise<string>\n  /**\n   * Sleep implementation used between retry attempts. Defaults to the real\n   * `sleep` from `./retry.js`. Test code can inject a no-op to avoid real\n   * delays without relying on module mocking (which differs across runners).\n   *\n   * @internal\n   */\n  readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>\n}\n\n/**\n * Transport wrapper that adds automatic retry with exponential backoff.\n * Handles transient B2 errors (408, 429, 503), expired auth tokens,\n * and network failures. Delegates to an inner {@link HttpTransport}.\n */\nexport class RetryTransport implements HttpTransport {\n  /** The wrapped transport that performs actual HTTP requests. */\n  private readonly inner: HttpTransport\n  /** Resolved retry options (defaults merged with user overrides). */\n  private readonly options: RetryOptions\n  /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */\n  private readonly onReauth?: () => Promise<string>\n  /** Sleep implementation used between retries; injectable for tests. */\n  private readonly sleepImpl: (ms: number, signal?: AbortSignal) => Promise<void>\n\n  /**\n   * Creates a new RetryTransport.\n   * @param opts - Retry transport configuration.\n   */\n  constructor(opts: RetryTransportOptions) {\n    this.inner = opts.transport\n    this.options = { ...DEFAULT_RETRY_OPTIONS, ...opts.retry }\n    if (opts.onReauth !== undefined) this.onReauth = opts.onReauth\n    this.sleepImpl = opts.sleepImpl ?? sleep\n  }\n\n  /**\n   * Sends the request with automatic retry on transient failures.\n   * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.\n   * @param originalRequest - The HTTP request to execute. The caller's\n   *   reference is not mutated; on reauth, a copy with a refreshed\n   *   Authorization header is sent.\n   *\n   * @returns The HTTP response.\n   */\n  async send(originalRequest: HttpRequest): Promise<HttpResponse> {\n    // `request` is reassigned (not mutated) when reauth produces a\n    // fresh Authorization header, so the caller's `originalRequest`\n    // stays untouched.\n    let request: HttpRequest = originalRequest\n    let lastError: B2Error | NetworkError | undefined\n\n    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {\n      if (attempt > 0 && lastError) {\n        const retryAfter = lastError instanceof NetworkError ? undefined : lastError.retryAfter\n        const delay = computeBackoff(attempt - 1, this.options, retryAfter)\n        await this.sleepImpl(delay, request.signal)\n      }\n\n      try {\n        const response = await this.inner.send(request)\n\n        if (response.status >= 200 && response.status < 300) {\n          return response\n        }\n\n        let errorBody: B2ErrorResponse\n        try {\n          errorBody = await response.json<B2ErrorResponse>()\n        } catch {\n          errorBody = {\n            status: response.status,\n            code: 'internal_error',\n            message: `HTTP ${response.status}`,\n          }\n        }\n\n        const retryAfterHeader = response.headers.get('Retry-After')\n        const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined\n        const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n        const error = classifyError(errorBody, {\n          ...(retryAfterSec !== undefined ? { retryAfter: retryAfterSec } : {}),\n          ...(requestId !== undefined ? { requestId } : {}),\n        })\n\n        if (error instanceof ExpiredAuthTokenError && this.onReauth) {\n          // Reauth returns the FRESH token; build a new request with a\n          // shallow-copied headers object so the Authorization swap\n          // doesn't mutate the caller's original request (which they\n          // may hold for retry / introspection). Without this swap the\n          // retry would carry the expired token captured at\n          // request-build time and bounce off the server again,\n          // exhausting the retry budget.\n          const freshToken = await this.onReauth()\n          request = {\n            ...request,\n            headers: { ...(request.headers ?? {}), Authorization: freshToken },\n          }\n          continue\n        }\n\n        if (!error.retryable || attempt === this.options.maxRetries) {\n          throw error\n        }\n\n        lastError = error\n      } catch (err) {\n        if (err instanceof B2Error || err instanceof NetworkError) {\n          throw err\n        }\n\n        if (err instanceof DOMException && err.name === 'AbortError') {\n          throw err\n        }\n\n        const networkErr = new NetworkError(\n          err instanceof Error ? err.message : 'Network error',\n          err,\n        )\n\n        if (attempt === this.options.maxRetries) {\n          throw networkErr\n        }\n\n        lastError = networkErr\n      }\n    }\n\n    throw lastError ?? new NetworkError('Max retries exceeded')\n  }\n}\n"],"names":["getUserAgent","UrlGuard","DEFAULT_RETRY_OPTIONS","sleep","NetworkError","computeBackoff","classifyError","ExpiredAuthTokenError","B2Error"],"mappings":"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"}

package/dist/http/transport.d.cts

@@ -0,0 +1,122 @@
+import { RetryOptions } from './retry.js';
+import { UrlGuard } from './url-guard.js';
+/** Describes an outgoing HTTP request to the B2 API. */
+export interface HttpRequest {
+    /** Fully qualified URL to send the request to. */
+    readonly url: string;
+    /** HTTP method. B2 uses GET for downloads (HEAD to fetch only headers) and POST for all other operations. */
+    readonly method: 'GET' | 'HEAD' | 'POST';
+    /** Request headers. Authorization and content-type are typically included. */
+    readonly headers?: Record<string, string>;
+    /** Request body. Used for POST requests (JSON payloads or file uploads). */
+    readonly body?: BodyInit | null;
+    /** Optional abort signal for request cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** Represents a parsed HTTP response from the B2 API. */
+export interface HttpResponse {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Response headers. */
+    readonly headers: Headers;
+    /** Response body as a readable stream, or null for empty responses. */
+    readonly body: ReadableStream<Uint8Array> | null;
+    /** Parses the response body as JSON. */
+    json<T>(): Promise<T>;
+    /** Reads the response body as a UTF-8 string. */
+    text(): Promise<string>;
+    /** Reads the response body as an ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Transport layer abstraction for sending HTTP requests.
+ * Implementations handle the actual network I/O and can be composed
+ * (e.g. wrapping a {@link FetchTransport} with a {@link RetryTransport}).
+ */
+export interface HttpTransport {
+    /** Sends an HTTP request and returns the response. */
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Default transport implementation using the global `fetch` API.
+ * Automatically sets the User-Agent header on each request and applies the
+ * SSRF {@link UrlGuard} (if configured) before opening the connection.
+ */
+export declare class FetchTransport implements HttpTransport {
+    /** User-Agent string sent with every request. */
+    private readonly userAgent;
+    /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
+    readonly urlGuard: UrlGuard;
+    /**
+     * Creates a new FetchTransport.
+     * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
+     */
+    constructor(options?: {
+        userAgent?: string;
+        urlGuard?: UrlGuard;
+    });
+    /**
+     * Sends the request using the global `fetch` function.
+     * @param request - The HTTP request to execute.
+     *
+     * @returns The HTTP response.
+     *
+     * @throws B2SsrfError when the URL fails the configured SSRF guard.
+     */
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/** Configuration for {@link RetryTransport}. */
+export interface RetryTransportOptions {
+    /** The underlying transport to delegate requests to. */
+    readonly transport: HttpTransport;
+    /** Override default retry settings (max retries, delays). */
+    readonly retry?: Partial<RetryOptions>;
+    /**
+     * Callback invoked on expired auth token errors. Must refresh
+     * credentials AND return the fresh auth token. The transport
+     * substitutes the new token into `request.headers.Authorization`
+     * before retrying — without this, the retried request would still
+     * carry the expired token captured by the original caller and the
+     * loop would never make progress.
+     */
+    readonly onReauth?: () => Promise<string>;
+    /**
+     * Sleep implementation used between retry attempts. Defaults to the real
+     * `sleep` from `./retry.js`. Test code can inject a no-op to avoid real
+     * delays without relying on module mocking (which differs across runners).
+     *
+     * @internal
+     */
+    readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Transport wrapper that adds automatic retry with exponential backoff.
+ * Handles transient B2 errors (408, 429, 503), expired auth tokens,
+ * and network failures. Delegates to an inner {@link HttpTransport}.
+ */
+export declare class RetryTransport implements HttpTransport {
+    /** The wrapped transport that performs actual HTTP requests. */
+    private readonly inner;
+    /** Resolved retry options (defaults merged with user overrides). */
+    private readonly options;
+    /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
+    private readonly onReauth?;
+    /** Sleep implementation used between retries; injectable for tests. */
+    private readonly sleepImpl;
+    /**
+     * Creates a new RetryTransport.
+     * @param opts - Retry transport configuration.
+     */
+    constructor(opts: RetryTransportOptions);
+    /**
+     * Sends the request with automatic retry on transient failures.
+     * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
+     * @param originalRequest - The HTTP request to execute. The caller's
+     *   reference is not mutated; on reauth, a copy with a refreshed
+     *   Authorization header is sent.
+     *
+     * @returns The HTTP response.
+     */
+    send(originalRequest: HttpRequest): Promise<HttpResponse>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/http/transport.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/http/transport.js"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,YAAY,EAAyB,MAAM,YAAY,CAAA;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;IAChD,wCAAwC;IACxC,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,iDAAiD;IACjD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAClD;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,mHAAmH;IACnH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;;OAGG;gBACS,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE;IAKjE;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAwBxD;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzE;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAuB;IACjD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAE/E;;;OAGG;gBACS,IAAI,EAAE,qBAAqB;IAOvC;;;;;;;;OAQG;IACG,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAsFhE"}

package/dist/http/transport.d.ts

@@ -0,0 +1,122 @@
+import { RetryOptions } from './retry.js';
+import { UrlGuard } from './url-guard.js';
+/** Describes an outgoing HTTP request to the B2 API. */
+export interface HttpRequest {
+    /** Fully qualified URL to send the request to. */
+    readonly url: string;
+    /** HTTP method. B2 uses GET for downloads (HEAD to fetch only headers) and POST for all other operations. */
+    readonly method: 'GET' | 'HEAD' | 'POST';
+    /** Request headers. Authorization and content-type are typically included. */
+    readonly headers?: Record<string, string>;
+    /** Request body. Used for POST requests (JSON payloads or file uploads). */
+    readonly body?: BodyInit | null;
+    /** Optional abort signal for request cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** Represents a parsed HTTP response from the B2 API. */
+export interface HttpResponse {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Response headers. */
+    readonly headers: Headers;
+    /** Response body as a readable stream, or null for empty responses. */
+    readonly body: ReadableStream<Uint8Array> | null;
+    /** Parses the response body as JSON. */
+    json<T>(): Promise<T>;
+    /** Reads the response body as a UTF-8 string. */
+    text(): Promise<string>;
+    /** Reads the response body as an ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Transport layer abstraction for sending HTTP requests.
+ * Implementations handle the actual network I/O and can be composed
+ * (e.g. wrapping a {@link FetchTransport} with a {@link RetryTransport}).
+ */
+export interface HttpTransport {
+    /** Sends an HTTP request and returns the response. */
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Default transport implementation using the global `fetch` API.
+ * Automatically sets the User-Agent header on each request and applies the
+ * SSRF {@link UrlGuard} (if configured) before opening the connection.
+ */
+export declare class FetchTransport implements HttpTransport {
+    /** User-Agent string sent with every request. */
+    private readonly userAgent;
+    /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
+    readonly urlGuard: UrlGuard;
+    /**
+     * Creates a new FetchTransport.
+     * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
+     */
+    constructor(options?: {
+        userAgent?: string;
+        urlGuard?: UrlGuard;
+    });
+    /**
+     * Sends the request using the global `fetch` function.
+     * @param request - The HTTP request to execute.
+     *
+     * @returns The HTTP response.
+     *
+     * @throws B2SsrfError when the URL fails the configured SSRF guard.
+     */
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/** Configuration for {@link RetryTransport}. */
+export interface RetryTransportOptions {
+    /** The underlying transport to delegate requests to. */
+    readonly transport: HttpTransport;
+    /** Override default retry settings (max retries, delays). */
+    readonly retry?: Partial<RetryOptions>;
+    /**
+     * Callback invoked on expired auth token errors. Must refresh
+     * credentials AND return the fresh auth token. The transport
+     * substitutes the new token into `request.headers.Authorization`
+     * before retrying — without this, the retried request would still
+     * carry the expired token captured by the original caller and the
+     * loop would never make progress.
+     */
+    readonly onReauth?: () => Promise<string>;
+    /**
+     * Sleep implementation used between retry attempts. Defaults to the real
+     * `sleep` from `./retry.js`. Test code can inject a no-op to avoid real
+     * delays without relying on module mocking (which differs across runners).
+     *
+     * @internal
+     */
+    readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Transport wrapper that adds automatic retry with exponential backoff.
+ * Handles transient B2 errors (408, 429, 503), expired auth tokens,
+ * and network failures. Delegates to an inner {@link HttpTransport}.
+ */
+export declare class RetryTransport implements HttpTransport {
+    /** The wrapped transport that performs actual HTTP requests. */
+    private readonly inner;
+    /** Resolved retry options (defaults merged with user overrides). */
+    private readonly options;
+    /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
+    private readonly onReauth?;
+    /** Sleep implementation used between retries; injectable for tests. */
+    private readonly sleepImpl;
+    /**
+     * Creates a new RetryTransport.
+     * @param opts - Retry transport configuration.
+     */
+    constructor(opts: RetryTransportOptions);
+    /**
+     * Sends the request with automatic retry on transient failures.
+     * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
+     * @param originalRequest - The HTTP request to execute. The caller's
+     *   reference is not mutated; on reauth, a copy with a refreshed
+     *   Authorization header is sent.
+     *
+     * @returns The HTTP response.
+     */
+    send(originalRequest: HttpRequest): Promise<HttpResponse>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/http/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/http/transport.js"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,YAAY,EAAyB,MAAM,YAAY,CAAA;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;IAChD,wCAAwC;IACxC,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,iDAAiD;IACjD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAClD;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,mHAAmH;IACnH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;;OAGG;gBACS,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE;IAKjE;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAwBxD;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzE;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAuB;IACjD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAE/E;;;OAGG;gBACS,IAAI,EAAE,qBAAqB;IAOvC;;;;;;;;OAQG;IACG,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAsFhE"}

package/dist/http/transport.js

@@ -0,0 +1,143 @@
+import { classifyError, ExpiredAuthTokenError, B2Error, NetworkError } from "../errors/index.js";
+import { DEFAULT_RETRY_OPTIONS, sleep, computeBackoff } from "./retry.js";
+import { UrlGuard } from "./url-guard.js";
+import { getUserAgent } from "./user-agent.js";
+class FetchTransport {
+  /** User-Agent string sent with every request. */
+  userAgent;
+  /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */
+  urlGuard;
+  /**
+   * Creates a new FetchTransport.
+   * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.
+   */
+  constructor(options) {
+    this.userAgent = getUserAgent(options?.userAgent);
+    this.urlGuard = options?.urlGuard ?? new UrlGuard();
+  }
+  /**
+   * Sends the request using the global `fetch` function.
+   * @param request - The HTTP request to execute.
+   *
+   * @returns The HTTP response.
+   *
+   * @throws B2SsrfError when the URL fails the configured SSRF guard.
+   */
+  async send(request) {
+    this.urlGuard.check(request.url);
+    const headers = new Headers(request.headers);
+    if (!headers.has("User-Agent")) {
+      headers.set("User-Agent", this.userAgent);
+    }
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers,
+      body: request.body ?? null,
+      ...request.signal !== void 0 ? { signal: request.signal } : {}
+    });
+    return {
+      status: response.status,
+      headers: response.headers,
+      body: response.body,
+      json: () => response.json(),
+      text: () => response.text(),
+      arrayBuffer: () => response.arrayBuffer()
+    };
+  }
+}
+class RetryTransport {
+  /** The wrapped transport that performs actual HTTP requests. */
+  inner;
+  /** Resolved retry options (defaults merged with user overrides). */
+  options;
+  /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */
+  onReauth;
+  /** Sleep implementation used between retries; injectable for tests. */
+  sleepImpl;
+  /**
+   * Creates a new RetryTransport.
+   * @param opts - Retry transport configuration.
+   */
+  constructor(opts) {
+    this.inner = opts.transport;
+    this.options = { ...DEFAULT_RETRY_OPTIONS, ...opts.retry };
+    if (opts.onReauth !== void 0) this.onReauth = opts.onReauth;
+    this.sleepImpl = opts.sleepImpl ?? sleep;
+  }
+  /**
+   * Sends the request with automatic retry on transient failures.
+   * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.
+   * @param originalRequest - The HTTP request to execute. The caller's
+   *   reference is not mutated; on reauth, a copy with a refreshed
+   *   Authorization header is sent.
+   *
+   * @returns The HTTP response.
+   */
+  async send(originalRequest) {
+    let request = originalRequest;
+    let lastError;
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      if (attempt > 0 && lastError) {
+        const retryAfter = lastError instanceof NetworkError ? void 0 : lastError.retryAfter;
+        const delay = computeBackoff(attempt - 1, this.options, retryAfter);
+        await this.sleepImpl(delay, request.signal);
+      }
+      try {
+        const response = await this.inner.send(request);
+        if (response.status >= 200 && response.status < 300) {
+          return response;
+        }
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = {
+            status: response.status,
+            code: "internal_error",
+            message: `HTTP ${response.status}`
+          };
+        }
+        const retryAfterHeader = response.headers.get("Retry-After");
+        const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : void 0;
+        const requestId = response.headers.get("X-Bz-Request-Id") ?? void 0;
+        const error = classifyError(errorBody, {
+          ...retryAfterSec !== void 0 ? { retryAfter: retryAfterSec } : {},
+          ...requestId !== void 0 ? { requestId } : {}
+        });
+        if (error instanceof ExpiredAuthTokenError && this.onReauth) {
+          const freshToken = await this.onReauth();
+          request = {
+            ...request,
+            headers: { ...request.headers ?? {}, Authorization: freshToken }
+          };
+          continue;
+        }
+        if (!error.retryable || attempt === this.options.maxRetries) {
+          throw error;
+        }
+        lastError = error;
+      } catch (err) {
+        if (err instanceof B2Error || err instanceof NetworkError) {
+          throw err;
+        }
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw err;
+        }
+        const networkErr = new NetworkError(
+          err instanceof Error ? err.message : "Network error",
+          err
+        );
+        if (attempt === this.options.maxRetries) {
+          throw networkErr;
+        }
+        lastError = networkErr;
+      }
+    }
+    throw lastError ?? new NetworkError("Max retries exceeded");
+  }
+}
+export {
+  FetchTransport,
+  RetryTransport
+};
+//# sourceMappingURL=transport.js.map