@backblaze-labs/b2-sdk 0.1.0

package/dist/errors/index.d.ts

@@ -0,0 +1,264 @@
+import { B2ErrorCode, B2ErrorResponse } from '../types/errors.js';
+/**
+ * Base error class for all B2 API errors.
+ * Contains the HTTP status, B2 error code, and retry metadata from the response.
+ */
+export declare class B2Error extends Error {
+    /** HTTP status code returned by the B2 API. */
+    readonly status: number;
+    /** B2 error code identifying the error type (e.g. `expired_auth_token`). */
+    readonly code: B2ErrorCode;
+    /** B2 request ID from the `X-Bz-Request-Id` response header, if present. */
+    readonly requestId?: string;
+    /** Retry delay in seconds from the `Retry-After` response header, if present. */
+    readonly retryAfter?: number;
+    /** Whether this error is transient and the request can be retried. */
+    readonly retryable: boolean;
+    /**
+     * Creates a new B2Error instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional retry and request metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        retryAfter?: number;
+        requestId?: string;
+    });
+}
+/** Thrown when the auth token has expired. Triggers automatic re-authorization. */
+export declare class ExpiredAuthTokenError extends B2Error {
+    /**
+     * Creates a new ExpiredAuthTokenError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when the auth token is invalid or unauthorized. */
+export declare class BadAuthTokenError extends B2Error {
+    /**
+     * Creates a new BadAuthTokenError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when the B2 service is temporarily unavailable (HTTP 503). */
+export declare class ServiceUnavailableError extends B2Error {
+    /**
+     * Creates a new ServiceUnavailableError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        retryAfter?: number;
+        requestId?: string;
+    });
+}
+/** Thrown when a request times out on the server side (HTTP 408). */
+export declare class RequestTimeoutError extends B2Error {
+    /**
+     * Creates a new RequestTimeoutError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when the client has sent too many requests (HTTP 429). */
+export declare class TooManyRequestsError extends B2Error {
+    /**
+     * Creates a new TooManyRequestsError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        retryAfter?: number;
+        requestId?: string;
+    });
+}
+/** Thrown when a storage, transaction, or download cap has been exceeded. */
+export declare class CapExceededError extends B2Error {
+    /**
+     * Creates a new CapExceededError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when the application key does not have permission for the requested operation. */
+export declare class AccessDeniedError extends B2Error {
+    /**
+     * Creates a new AccessDeniedError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when the requested file does not exist. */
+export declare class FileNotPresentError extends B2Error {
+    /**
+     * Creates a new FileNotPresentError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown when creating a bucket with a name that already exists in the account. */
+export declare class DuplicateBucketNameError extends B2Error {
+    /**
+     * Creates a new DuplicateBucketNameError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/** Thrown for general bad request errors (HTTP 400) not covered by a more specific subclass. */
+export declare class BadRequestError extends B2Error {
+    /**
+     * Creates a new BadRequestError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/**
+ * Thrown when an upload URL is no longer valid and must be refreshed.
+ *
+ * Forward-compat insurance: B2 does not currently surface a distinct
+ * error code for this case, so {@link classifyError} never actually
+ * instantiates this class today. It's part of the public API so
+ * consumers can pre-write `instanceof` checks; when B2 documents a
+ * `bad_upload_url` (or similar) error code, the `classifyError`
+ * switch gets a matching case and existing consumer code starts
+ * catching the typed error without any changes on their side.
+ *
+ * Until then, expect `BadRequestError` for upload-URL invalidation
+ * scenarios — that's what B2 currently returns.
+ */
+export declare class BadUploadUrlError extends B2Error {
+    /**
+     * Creates a new BadUploadUrlError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/**
+ * Thrown when the uploaded file's SHA-1 checksum does not match the
+ * expected value.
+ *
+ * Forward-compat insurance: the B2 API currently rejects mismatched
+ * uploads with a generic `bad_request` code, so {@link classifyError}
+ * never actually instantiates this class today. It's part of the
+ * public API so consumers can pre-write `instanceof` checks; when B2
+ * documents a dedicated checksum-mismatch code, the `classifyError`
+ * switch gets a matching case and existing consumer code starts
+ * catching the typed error without any changes on their side.
+ *
+ * Until then, expect `BadRequestError` for SHA-1 mismatch scenarios.
+ */
+export declare class ChecksumMismatchError extends B2Error {
+    /**
+     * Creates a new ChecksumMismatchError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - The error details including HTTP status, error code, message, and optional request ID.
+     */
+    constructor(response: B2ErrorResponse, options?: {
+        requestId?: string;
+    });
+}
+/**
+ * Thrown by client-side capability checks when the application key is missing
+ * capabilities required by an operation. Not raised by the server.
+ */
+export declare class B2InsufficientCapabilityError extends Error {
+    /** Capabilities that were required for the operation. */
+    readonly required: readonly string[];
+    /** Capabilities that the current key actually has. */
+    readonly available: readonly string[];
+    /** Capabilities present in `required` but not in `available`. */
+    readonly missing: readonly string[];
+    /**
+     * Creates a new B2InsufficientCapabilityError instance.
+     *
+     * @param required - Capabilities the operation requires.
+     * @param available - Capabilities the current key holds.
+     * @param missing - The subset of required that isn't available.
+     */
+    constructor(required: readonly string[], available: readonly string[], missing: readonly string[]);
+}
+/**
+ * Thrown when the SDK is asked to fetch a URL whose host is outside the
+ * authorized B2 realm. Defense against SSRF / URL-substitution attacks where
+ * a compromised or hostile B2 endpoint returns an upload URL pointing at an
+ * internal service (e.g. cloud metadata at `169.254.169.254`).
+ *
+ * Not retryable.
+ */
+export declare class B2SsrfError extends Error {
+    /** The full URL that was rejected. */
+    readonly url: string;
+    /** Always `false` — this is a security failure, not transient. */
+    readonly retryable = false;
+    /**
+     * Creates a new {@link B2SsrfError}.
+     *
+     * @param message - Human-readable description of which URL was rejected and why.
+     * @param url - The full URL that was rejected.
+     */
+    constructor(message: string, 
+    /** The full URL that was rejected. */
+    url: string);
+}
+/** Thrown when a network-level failure occurs (DNS, TCP, TLS). Always retryable. */
+export declare class NetworkError extends Error {
+    readonly cause?: unknown | undefined;
+    /** Always `true` since network errors are transient. */
+    readonly retryable = true;
+    /**
+     * Creates a new NetworkError instance.
+     * @param message - Human-readable description of the network failure.
+     * @param cause - The underlying error that caused this failure, if any.
+     */
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Maps a B2 error response to the appropriate {@link B2Error} subclass.
+ * Uses the error code for exact matching, then falls back to HTTP status codes.
+ *
+ * Maintainer note: when B2 documents a new error code, add a `case`
+ * branch below pointing at the matching {@link B2Error} subclass. Unknown
+ * codes fall through to the HTTP-status-based heuristic and finally to a
+ * generic `B2Error` — that's safe but loses semantic specificity (the
+ * caller can't `instanceof` against a precise subclass and the retry
+ * decision relies on status alone). The `B2ErrorCode` union in
+ * `src/types/errors.ts` should also gain the new code at the same time
+ * so the switch is exhaustive again.
+ *
+ * @param response - Parsed B2 error response body.
+ * @param options - Optional retry and request metadata from response headers.
+ *
+ * @returns A typed B2Error subclass instance.
+ */
+export declare function classifyError(response: B2ErrorResponse, options?: {
+    retryAfter?: number;
+    requestId?: string;
+}): B2Error;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.js"],"names":[],"mappings":"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"}

package/dist/errors/index.js

@@ -0,0 +1,268 @@
+class B2Error extends Error {
+  /** HTTP status code returned by the B2 API. */
+  status;
+  /** B2 error code identifying the error type (e.g. `expired_auth_token`). */
+  code;
+  /** B2 request ID from the `X-Bz-Request-Id` response header, if present. */
+  requestId;
+  /** Retry delay in seconds from the `Retry-After` response header, if present. */
+  retryAfter;
+  /** Whether this error is transient and the request can be retried. */
+  retryable;
+  /**
+   * Creates a new B2Error instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - Optional retry and request metadata from response headers.
+   */
+  constructor(response, options) {
+    super(response.message);
+    this.name = "B2Error";
+    this.status = response.status;
+    this.code = response.code;
+    if (options?.retryAfter !== void 0) this.retryAfter = options.retryAfter;
+    if (options?.requestId !== void 0) this.requestId = options.requestId;
+    this.retryable = isTransient(response.status, response.code);
+  }
+}
+class ExpiredAuthTokenError extends B2Error {
+  /**
+   * Creates a new ExpiredAuthTokenError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "ExpiredAuthTokenError";
+  }
+}
+class BadAuthTokenError extends B2Error {
+  /**
+   * Creates a new BadAuthTokenError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "BadAuthTokenError";
+  }
+}
+class ServiceUnavailableError extends B2Error {
+  /**
+   * Creates a new ServiceUnavailableError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "ServiceUnavailableError";
+  }
+}
+class RequestTimeoutError extends B2Error {
+  /**
+   * Creates a new RequestTimeoutError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "RequestTimeoutError";
+  }
+}
+class TooManyRequestsError extends B2Error {
+  /**
+   * Creates a new TooManyRequestsError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "TooManyRequestsError";
+  }
+}
+class CapExceededError extends B2Error {
+  /**
+   * Creates a new CapExceededError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "CapExceededError";
+  }
+}
+class AccessDeniedError extends B2Error {
+  /**
+   * Creates a new AccessDeniedError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "AccessDeniedError";
+  }
+}
+class FileNotPresentError extends B2Error {
+  /**
+   * Creates a new FileNotPresentError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "FileNotPresentError";
+  }
+}
+class DuplicateBucketNameError extends B2Error {
+  /**
+   * Creates a new DuplicateBucketNameError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "DuplicateBucketNameError";
+  }
+}
+class BadRequestError extends B2Error {
+  /**
+   * Creates a new BadRequestError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "BadRequestError";
+  }
+}
+class BadUploadUrlError extends B2Error {
+  /**
+   * Creates a new BadUploadUrlError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "BadUploadUrlError";
+  }
+}
+class ChecksumMismatchError extends B2Error {
+  /**
+   * Creates a new ChecksumMismatchError instance.
+   * @param response - Parsed B2 error response body.
+   * @param options - The error details including HTTP status, error code, message, and optional request ID.
+   */
+  constructor(response, options) {
+    super(response, options);
+    this.name = "ChecksumMismatchError";
+  }
+}
+class B2InsufficientCapabilityError extends Error {
+  /** Capabilities that were required for the operation. */
+  required;
+  /** Capabilities that the current key actually has. */
+  available;
+  /** Capabilities present in `required` but not in `available`. */
+  missing;
+  /**
+   * Creates a new B2InsufficientCapabilityError instance.
+   *
+   * @param required - Capabilities the operation requires.
+   * @param available - Capabilities the current key holds.
+   * @param missing - The subset of required that isn't available.
+   */
+  constructor(required, available, missing) {
+    super(`Application key is missing capabilities: ${missing.join(", ")}`);
+    this.name = "B2InsufficientCapabilityError";
+    this.required = required;
+    this.available = available;
+    this.missing = missing;
+  }
+}
+class B2SsrfError extends Error {
+  /**
+   * Creates a new {@link B2SsrfError}.
+   *
+   * @param message - Human-readable description of which URL was rejected and why.
+   * @param url - The full URL that was rejected.
+   */
+  constructor(message, url) {
+    super(message);
+    this.url = url;
+    this.name = "B2SsrfError";
+  }
+  /** Always `false` — this is a security failure, not transient. */
+  retryable = false;
+}
+class NetworkError extends Error {
+  /**
+   * Creates a new NetworkError instance.
+   * @param message - Human-readable description of the network failure.
+   * @param cause - The underlying error that caused this failure, if any.
+   */
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "NetworkError";
+  }
+  /** Always `true` since network errors are transient. */
+  retryable = true;
+}
+function isTransient(status, code) {
+  if (status === 408 || status === 429 || status === 503) return true;
+  if (code === "expired_auth_token") return true;
+  if (code === "service_unavailable" || code === "request_timeout") return true;
+  return false;
+}
+function classifyError(response, options) {
+  switch (response.code) {
+    case "expired_auth_token":
+      return new ExpiredAuthTokenError(response, options);
+    case "bad_auth_token":
+    case "unauthorized":
+      return new BadAuthTokenError(response, options);
+    case "service_unavailable":
+      return new ServiceUnavailableError(response, options);
+    case "request_timeout":
+      return new RequestTimeoutError(response, options);
+    case "cap_exceeded":
+    case "storage_cap_exceeded":
+    case "transaction_cap_exceeded":
+    case "download_cap_exceeded":
+      return new CapExceededError(response, options);
+    case "access_denied":
+      return new AccessDeniedError(response, options);
+    case "file_not_present":
+    case "no_such_file":
+      return new FileNotPresentError(response, options);
+    case "duplicate_bucket_name":
+      return new DuplicateBucketNameError(response, options);
+    case "bad_sha1_checksum":
+      return new ChecksumMismatchError(response, options);
+    case "bad_request":
+      return new BadRequestError(response, options);
+  }
+  if (response.status === 429) return new TooManyRequestsError(response, options);
+  if (response.status === 503) return new ServiceUnavailableError(response, options);
+  if (response.status === 408) return new RequestTimeoutError(response, options);
+  return new B2Error(response, options);
+}
+export {
+  AccessDeniedError,
+  B2Error,
+  B2InsufficientCapabilityError,
+  B2SsrfError,
+  BadAuthTokenError,
+  BadRequestError,
+  BadUploadUrlError,
+  CapExceededError,
+  ChecksumMismatchError,
+  DuplicateBucketNameError,
+  ExpiredAuthTokenError,
+  FileNotPresentError,
+  NetworkError,
+  RequestTimeoutError,
+  ServiceUnavailableError,
+  TooManyRequestsError,
+  classifyError
+};
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error hierarchy for B2 API failures.\n *\n * Every B2 error response is mapped to a specific {@link B2Error} subclass\n * (e.g. {@link ExpiredAuthTokenError}, {@link CapExceededError}) with pre-computed\n * {@link B2Error.retryable | retryable} flags. Use {@link classifyError} to convert\n * a raw error response into the appropriate subclass.\n *\n * Convention: `B2Error` and its subclasses represent failures returned by\n * the B2 API. Programming errors and SDK preconditions (e.g. \"not yet\n * authorized\", \"stream consumed twice\", \"called before init\") use the\n * native `Error` constructor instead. Two outliers extend `Error` directly\n * rather than `B2Error` because they originate inside the SDK before any\n * B2 request is made: {@link B2InsufficientCapabilityError} (raised by\n * `B2Client.hasCapabilities`) and {@link B2SsrfError} (raised by the\n * default `UrlGuard` before `fetch`).\n *\n * @packageDocumentation\n */\n\nimport type { B2ErrorCode, B2ErrorResponse } from '../types/errors.ts'\n\n/**\n * Base error class for all B2 API errors.\n * Contains the HTTP status, B2 error code, and retry metadata from the response.\n */\nexport class B2Error extends Error {\n  /** HTTP status code returned by the B2 API. */\n  readonly status: number\n  /** B2 error code identifying the error type (e.g. `expired_auth_token`). */\n  readonly code: B2ErrorCode\n  /** B2 request ID from the `X-Bz-Request-Id` response header, if present. */\n  readonly requestId?: string\n  /** Retry delay in seconds from the `Retry-After` response header, if present. */\n  readonly retryAfter?: number\n  /** Whether this error is transient and the request can be retried. */\n  readonly retryable: boolean\n\n  /**\n   * Creates a new B2Error instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional retry and request metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: { retryAfter?: number; requestId?: string }) {\n    super(response.message)\n    this.name = 'B2Error'\n    this.status = response.status\n    this.code = response.code\n    if (options?.retryAfter !== undefined) this.retryAfter = options.retryAfter\n    if (options?.requestId !== undefined) this.requestId = options.requestId\n    this.retryable = isTransient(response.status, response.code)\n  }\n}\n\n/** Thrown when the auth token has expired. Triggers automatic re-authorization. */\nexport class ExpiredAuthTokenError extends B2Error {\n  /**\n   * Creates a new ExpiredAuthTokenError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'ExpiredAuthTokenError'\n  }\n}\n\n/** Thrown when the auth token is invalid or unauthorized. */\nexport class BadAuthTokenError extends B2Error {\n  /**\n   * Creates a new BadAuthTokenError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'BadAuthTokenError'\n  }\n}\n\n/** Thrown when the B2 service is temporarily unavailable (HTTP 503). */\nexport class ServiceUnavailableError extends B2Error {\n  /**\n   * Creates a new ServiceUnavailableError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { retryAfter?: number; requestId?: string }) {\n    super(response, options)\n    this.name = 'ServiceUnavailableError'\n  }\n}\n\n/** Thrown when a request times out on the server side (HTTP 408). */\nexport class RequestTimeoutError extends B2Error {\n  /**\n   * Creates a new RequestTimeoutError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'RequestTimeoutError'\n  }\n}\n\n/** Thrown when the client has sent too many requests (HTTP 429). */\nexport class TooManyRequestsError extends B2Error {\n  /**\n   * Creates a new TooManyRequestsError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { retryAfter?: number; requestId?: string }) {\n    super(response, options)\n    this.name = 'TooManyRequestsError'\n  }\n}\n\n/** Thrown when a storage, transaction, or download cap has been exceeded. */\nexport class CapExceededError extends B2Error {\n  /**\n   * Creates a new CapExceededError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'CapExceededError'\n  }\n}\n\n/** Thrown when the application key does not have permission for the requested operation. */\nexport class AccessDeniedError extends B2Error {\n  /**\n   * Creates a new AccessDeniedError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'AccessDeniedError'\n  }\n}\n\n/** Thrown when the requested file does not exist. */\nexport class FileNotPresentError extends B2Error {\n  /**\n   * Creates a new FileNotPresentError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'FileNotPresentError'\n  }\n}\n\n/** Thrown when creating a bucket with a name that already exists in the account. */\nexport class DuplicateBucketNameError extends B2Error {\n  /**\n   * Creates a new DuplicateBucketNameError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'DuplicateBucketNameError'\n  }\n}\n\n/** Thrown for general bad request errors (HTTP 400) not covered by a more specific subclass. */\nexport class BadRequestError extends B2Error {\n  /**\n   * Creates a new BadRequestError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'BadRequestError'\n  }\n}\n\n/**\n * Thrown when an upload URL is no longer valid and must be refreshed.\n *\n * Forward-compat insurance: B2 does not currently surface a distinct\n * error code for this case, so {@link classifyError} never actually\n * instantiates this class today. It's part of the public API so\n * consumers can pre-write `instanceof` checks; when B2 documents a\n * `bad_upload_url` (or similar) error code, the `classifyError`\n * switch gets a matching case and existing consumer code starts\n * catching the typed error without any changes on their side.\n *\n * Until then, expect `BadRequestError` for upload-URL invalidation\n * scenarios — that's what B2 currently returns.\n */\nexport class BadUploadUrlError extends B2Error {\n  /**\n   * Creates a new BadUploadUrlError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'BadUploadUrlError'\n  }\n}\n\n/**\n * Thrown when the uploaded file's SHA-1 checksum does not match the\n * expected value.\n *\n * Forward-compat insurance: the B2 API currently rejects mismatched\n * uploads with a generic `bad_request` code, so {@link classifyError}\n * never actually instantiates this class today. It's part of the\n * public API so consumers can pre-write `instanceof` checks; when B2\n * documents a dedicated checksum-mismatch code, the `classifyError`\n * switch gets a matching case and existing consumer code starts\n * catching the typed error without any changes on their side.\n *\n * Until then, expect `BadRequestError` for SHA-1 mismatch scenarios.\n */\nexport class ChecksumMismatchError extends B2Error {\n  /**\n   * Creates a new ChecksumMismatchError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - The error details including HTTP status, error code, message, and optional request ID.\n   */\n  constructor(response: B2ErrorResponse, options?: { requestId?: string }) {\n    super(response, options)\n    this.name = 'ChecksumMismatchError'\n  }\n}\n\n/**\n * Thrown by client-side capability checks when the application key is missing\n * capabilities required by an operation. Not raised by the server.\n */\nexport class B2InsufficientCapabilityError extends Error {\n  /** Capabilities that were required for the operation. */\n  readonly required: readonly string[]\n  /** Capabilities that the current key actually has. */\n  readonly available: readonly string[]\n  /** Capabilities present in `required` but not in `available`. */\n  readonly missing: readonly string[]\n\n  /**\n   * Creates a new B2InsufficientCapabilityError instance.\n   *\n   * @param required - Capabilities the operation requires.\n   * @param available - Capabilities the current key holds.\n   * @param missing - The subset of required that isn't available.\n   */\n  constructor(\n    required: readonly string[],\n    available: readonly string[],\n    missing: readonly string[],\n  ) {\n    super(`Application key is missing capabilities: ${missing.join(', ')}`)\n    this.name = 'B2InsufficientCapabilityError'\n    this.required = required\n    this.available = available\n    this.missing = missing\n  }\n}\n\n/**\n * Thrown when the SDK is asked to fetch a URL whose host is outside the\n * authorized B2 realm. Defense against SSRF / URL-substitution attacks where\n * a compromised or hostile B2 endpoint returns an upload URL pointing at an\n * internal service (e.g. cloud metadata at `169.254.169.254`).\n *\n * Not retryable.\n */\nexport class B2SsrfError extends Error {\n  /** Always `false` — this is a security failure, not transient. */\n  readonly retryable = false\n\n  /**\n   * Creates a new {@link B2SsrfError}.\n   *\n   * @param message - Human-readable description of which URL was rejected and why.\n   * @param url - The full URL that was rejected.\n   */\n  constructor(\n    message: string,\n    /** The full URL that was rejected. */\n    public readonly url: string,\n  ) {\n    super(message)\n    this.name = 'B2SsrfError'\n  }\n}\n\n/** Thrown when a network-level failure occurs (DNS, TCP, TLS). Always retryable. */\nexport class NetworkError extends Error {\n  /** Always `true` since network errors are transient. */\n  readonly retryable = true\n\n  /**\n   * Creates a new NetworkError instance.\n   * @param message - Human-readable description of the network failure.\n   * @param cause - The underlying error that caused this failure, if any.\n   */\n  constructor(\n    message: string,\n    public override readonly cause?: unknown,\n  ) {\n    super(message)\n    this.name = 'NetworkError'\n  }\n}\n\nfunction isTransient(status: number, code: B2ErrorCode): boolean {\n  if (status === 408 || status === 429 || status === 503) return true\n  if (code === 'expired_auth_token') return true\n  if (code === 'service_unavailable' || code === 'request_timeout') return true\n  return false\n}\n\n/**\n * Maps a B2 error response to the appropriate {@link B2Error} subclass.\n * Uses the error code for exact matching, then falls back to HTTP status codes.\n *\n * Maintainer note: when B2 documents a new error code, add a `case`\n * branch below pointing at the matching {@link B2Error} subclass. Unknown\n * codes fall through to the HTTP-status-based heuristic and finally to a\n * generic `B2Error` — that's safe but loses semantic specificity (the\n * caller can't `instanceof` against a precise subclass and the retry\n * decision relies on status alone). The `B2ErrorCode` union in\n * `src/types/errors.ts` should also gain the new code at the same time\n * so the switch is exhaustive again.\n *\n * @param response - Parsed B2 error response body.\n * @param options - Optional retry and request metadata from response headers.\n *\n * @returns A typed B2Error subclass instance.\n */\nexport function classifyError(\n  response: B2ErrorResponse,\n  options?: { retryAfter?: number; requestId?: string },\n): B2Error {\n  switch (response.code) {\n    case 'expired_auth_token':\n      return new ExpiredAuthTokenError(response, options)\n    case 'bad_auth_token':\n    case 'unauthorized':\n      return new BadAuthTokenError(response, options)\n    case 'service_unavailable':\n      return new ServiceUnavailableError(response, options)\n    case 'request_timeout':\n      return new RequestTimeoutError(response, options)\n    case 'cap_exceeded':\n    case 'storage_cap_exceeded':\n    case 'transaction_cap_exceeded':\n    case 'download_cap_exceeded':\n      return new CapExceededError(response, options)\n    case 'access_denied':\n      return new AccessDeniedError(response, options)\n    case 'file_not_present':\n    case 'no_such_file':\n      return new FileNotPresentError(response, options)\n    case 'duplicate_bucket_name':\n      return new DuplicateBucketNameError(response, options)\n    case 'bad_sha1_checksum':\n      return new ChecksumMismatchError(response, options)\n    case 'bad_request':\n      return new BadRequestError(response, options)\n    default:\n      break\n  }\n\n  if (response.status === 429) return new TooManyRequestsError(response, options)\n  if (response.status === 503) return new ServiceUnavailableError(response, options)\n  if (response.status === 408) return new RequestTimeoutError(response, options)\n\n  return new B2Error(response, options)\n}\n"],"names":[],"mappings":"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"}

package/dist/http/retry.cjs

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+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 }
+    );
+  });
+}
+exports.DEFAULT_RETRY_OPTIONS = DEFAULT_RETRY_OPTIONS;
+exports.computeBackoff = computeBackoff;
+exports.sleep = sleep;
+//# sourceMappingURL=retry.cjs.map

package/dist/http/retry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.cjs","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/retry.d.cts

@@ -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.cts.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"}