@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/errors/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","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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"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error hierarchy for B2 API failures.\n *\n * Every B2 error response maps to a specific {@link B2Error} subclass.\n * Retry behavior is exposed through {@link B2Error.retryable}.\n * Examples include {@link ExpiredAuthTokenError} and {@link CapExceededError}.\n * Use {@link classifyError} to convert a raw error response into the\n * appropriate subclass.\n *\n * Convention: most `B2Error` subclasses represent failures returned by the B2\n * API. The client-side exception is {@link B2RealmConfigurationError}; it\n * extends `B2Error` so realm-validation failures can be handled with the SDK\n * error hierarchy before credentials are sent.\n *\n * Other programming errors and SDK preconditions, such as \"not yet authorized\",\n * \"stream consumed twice\", or \"called before init\", use the native `Error`\n * constructor instead. The direct `Error` outliers are\n * {@link B2InsufficientCapabilityError}, {@link B2RedirectError},\n * {@link B2SsrfError}, {@link NetworkError},\n * {@link ResumeFileIdMismatchError}, {@link UploadResponseBodyError}, and\n * {@link FinishLargeFileResponseBodyError}.\n *\n * @packageDocumentation\n */\n\nimport { redactUrlForError } from '../internal/url-redaction.ts'\nimport {\n  type B2ErrorCode,\n  type B2ErrorResponse,\n  KNOWN_B2_ERROR_CODES,\n  type KnownB2ErrorCode,\n} from '../types/errors.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\n\n/** Thrown when an explicit resumeFileId is not compatible with the requested upload. */\nexport class ResumeFileIdMismatchError extends Error {\n  /** Caller-supplied unfinished large file ID that failed verification. */\n  readonly fileId: LargeFileId\n  /** Requested destination file name. */\n  readonly fileName: string\n\n  /**\n   * Creates a new resume-file ID mismatch error.\n   * @param fileId - Caller-supplied unfinished large file ID that failed verification.\n   * @param fileName - Requested destination file name.\n   */\n  constructor(fileId: LargeFileId, fileName: string) {\n    super(\n      `uploadLargeFile: resumeFileId ${fileId} does not identify a compatible unfinished large file for ${fileName}.`,\n    )\n    this.name = 'ResumeFileIdMismatchError'\n    this.fileId = fileId\n    this.fileName = fileName\n  }\n}\n\n/** Metadata captured from B2 error response headers. */\nexport interface B2ErrorOptions {\n  /** Retry delay in seconds from the `Retry-After` response header, if present. */\n  readonly retryAfter?: number\n  /** B2 request ID from the `X-Bz-Request-Id` response header, if present. */\n  readonly requestId?: string\n}\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?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'ServiceUnavailableError'\n  }\n}\n\n/** Thrown when B2 reports an internal server error. */\nexport class InternalError extends B2Error {\n  /**\n   * Creates a new InternalError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InternalError'\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'TooManyRequestsError'\n  }\n}\n\n/** Thrown when the account has reached the maximum number of buckets. */\nexport class TooManyBucketsError extends B2Error {\n  /**\n   * Creates a new TooManyBucketsError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'TooManyBucketsError'\n  }\n}\n\n/** Thrown when the bucket or request has reached the maximum number of files. */\nexport class TooManyFilesError extends B2Error {\n  /**\n   * Creates a new TooManyFilesError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'TooManyFilesError'\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'FileNotPresentError'\n  }\n}\n\n/** Thrown when a requested B2 resource does not exist. */\nexport class NotFoundError extends B2Error {\n  /**\n   * Creates a new NotFoundError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'NotFoundError'\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'DuplicateBucketNameError'\n  }\n}\n\n/** Thrown when a bucket name is malformed, reserved, or otherwise rejected by B2. */\nexport class InvalidBucketNameError extends B2Error {\n  /**\n   * Creates a new InvalidBucketNameError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidBucketNameError'\n  }\n}\n\n/** Thrown when bucket metadata fails B2 validation. */\nexport class InvalidBucketInfoError extends B2Error {\n  /**\n   * Creates a new InvalidBucketInfoError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidBucketInfoError'\n  }\n}\n\n/** Thrown when a bucket ID is malformed or does not identify a valid bucket. */\nexport class BadBucketIdError extends B2Error {\n  /**\n   * Creates a new BadBucketIdError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'BadBucketIdError'\n  }\n}\n\n/** Thrown when the B2 endpoint does not allow the request method. */\nexport class MethodNotAllowedError extends B2Error {\n  /**\n   * Creates a new MethodNotAllowedError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'MethodNotAllowedError'\n  }\n}\n\n/** Thrown when the request conflicts with current B2 resource state. */\nexport class ConflictError extends B2Error {\n  /**\n   * Creates a new ConflictError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'ConflictError'\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'BadRequestError'\n  }\n}\n\n/** Thrown when B2 cannot parse the JSON request body. */\nexport class BadJsonError extends B2Error {\n  /**\n   * Creates a new BadJsonError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'BadJsonError'\n  }\n}\n\n/** Thrown when a bucket ID has a valid shape but does not identify a usable bucket. */\nexport class InvalidBucketIdError extends B2Error {\n  /**\n   * Creates a new InvalidBucketIdError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidBucketIdError'\n  }\n}\n\n/** Thrown when a numeric request parameter is outside the allowed range. */\nexport class OutOfRangeError extends B2Error {\n  /**\n   * Creates a new OutOfRangeError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'OutOfRangeError'\n  }\n}\n\n/** Thrown when a requested byte range cannot be satisfied. */\nexport class RangeNotSatisfiableError extends B2Error {\n  /**\n   * Creates a new RangeNotSatisfiableError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'RangeNotSatisfiableError'\n  }\n}\n\n/** Thrown when a file name is malformed or otherwise rejected by B2. */\nexport class InvalidFileNameError extends B2Error {\n  /**\n   * Creates a new InvalidFileNameError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidFileNameError'\n  }\n}\n\n/** Thrown when file metadata fails B2 validation. */\nexport class InvalidFileInfoError extends B2Error {\n  /**\n   * Creates a new InvalidFileInfoError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidFileInfoError'\n  }\n}\n\n/** Thrown when a file ID is malformed or does not identify a valid file. */\nexport class InvalidFileIdError extends B2Error {\n  /**\n   * Creates a new InvalidFileIdError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidFileIdError'\n  }\n}\n\n/** Thrown when a multipart upload part number is invalid. */\nexport class InvalidPartNumberError extends B2Error {\n  /**\n   * Creates a new InvalidPartNumberError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\n    super(response, options)\n    this.name = 'InvalidPartNumberError'\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 - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 * When B2 returns `bad_sha1_checksum`, {@link classifyError} instantiates\n * this class so callers can handle checksum failures with `instanceof`.\n * Generic `bad_request` checksum failures continue to classify as\n * {@link BadRequestError}.\n */\nexport class ChecksumMismatchError extends B2Error {\n  /**\n   * Creates a new ChecksumMismatchError instance.\n   * @param response - Parsed B2 error response body.\n   * @param options - Optional metadata from response headers.\n   */\n  constructor(response: B2ErrorResponse, options?: B2ErrorOptions) {\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 URL that was rejected. Stored as a sanitized URL.\n   */\n  constructor(message: string, url: string) {\n    const safeUrl = redactUrlForError(url)\n    super(`${message.split(url).join(safeUrl)} (${safeUrl})`)\n    this.name = 'B2SsrfError'\n    this.url = safeUrl\n  }\n\n  /** Sanitized URL that was rejected. */\n  readonly url: string\n}\n\n/** Thrown when a configured auth realm cannot safely be used for authorization. */\nexport class B2RealmConfigurationError extends B2Error {\n  /**\n   * Creates a new B2RealmConfigurationError instance.\n   *\n   * @param message - Human-readable description of the invalid realm setting.\n   */\n  constructor(message: string) {\n    super({ status: 400, code: 'bad_request', message })\n    this.name = 'B2RealmConfigurationError'\n  }\n}\n\n/** Thrown when the SDK refuses to follow an HTTP redirect automatically. */\nexport class B2RedirectError extends Error {\n  /** Always `false` because a blocked redirect is deterministic. */\n  readonly retryable = false\n  /** Sanitized request URL whose response attempted to redirect. */\n  readonly url: string\n  /** HTTP redirect status code, or 0 for an opaque browser redirect. */\n  readonly status: number\n  /** Sanitized redirect target, or `null` when no Location header was present. */\n  readonly location: string | null\n\n  /**\n   * Creates a new B2RedirectError instance.\n   *\n   * @param url - Request URL whose response attempted to redirect. Stored as a sanitized URL.\n   * @param status - HTTP redirect status code.\n   * @param location - Redirect Location header, if present. Stored as a sanitized URL.\n   */\n  constructor(url: string, status: number, location: string | null) {\n    const safeUrl = redactUrlForError(url)\n    const safeLocation = location !== null ? redactUrlForError(location, { baseUrl: url }) : null\n    super(\n      safeLocation !== null\n        ? `HTTP ${status} redirect blocked for ${safeUrl} to ${safeLocation}`\n        : `HTTP ${status} redirect blocked for ${safeUrl}`,\n    )\n    this.name = 'B2RedirectError'\n    this.url = safeUrl\n    this.status = status\n    this.location = safeLocation\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\n/**\n * Thrown when an upload POST returned a response but its body could not be\n * read. The upload may already have been stored by B2, so retrying this error\n * can create duplicate file versions or parts.\n */\nexport class UploadResponseBodyError extends Error {\n  /** Underlying response body error, when available. */\n  public override readonly cause?: unknown\n\n  /**\n   * Creates a new UploadResponseBodyError instance.\n   * @param message - Human-readable description of the response read failure.\n   * @param options - Optional cause.\n   */\n  constructor(\n    message: string,\n    options: {\n      readonly cause?: unknown\n    } = {},\n  ) {\n    super(message, { cause: options.cause })\n    this.name = 'UploadResponseBodyError'\n    if (options.cause !== undefined) this.cause = options.cause\n  }\n}\n\n/**\n * Thrown when `b2_finish_large_file` returned a response but its body could not\n * be read. The large file may already be committed server-side, so high-level\n * upload paths do not cancel the large file after this error.\n */\nexport class FinishLargeFileResponseBodyError extends Error {\n  /** Ambiguous large file ID that may already be committed server-side. */\n  readonly fileId?: LargeFileId\n  /** Bucket requested by the high-level upload, when available. */\n  readonly bucketId?: BucketId\n  /** File name requested by the high-level upload, when available. */\n  readonly fileName?: string\n\n  /**\n   * Creates a new FinishLargeFileResponseBodyError instance.\n   * @param message - Human-readable description of the response read failure.\n   * @param options - Optional cause and reconciliation metadata.\n   */\n  constructor(\n    message: string,\n    options: {\n      readonly cause?: unknown\n      readonly fileId?: LargeFileId\n      readonly bucketId?: BucketId\n      readonly fileName?: string\n    } = {},\n  ) {\n    super(message, { cause: options.cause })\n    this.name = 'FinishLargeFileResponseBodyError'\n    if (options.cause !== undefined) this.cause = options.cause\n    if (options.fileId !== undefined) this.fileId = options.fileId\n    if (options.bucketId !== undefined) this.bucketId = options.bucketId\n    if (options.fileName !== undefined) this.fileName = options.fileName\n  }\n}\n\nfunction isTransient(status: number, code: B2ErrorCode): boolean {\n  // Request timeout + rate limit.\n  if (status === 408 || status === 429) return true\n  // Transient server errors: internal error (500), bad gateway (502), service\n  // unavailable (503), gateway timeout (504). B2 documents 500 and 503 as\n  // retryable; 502/504 are transient infrastructure failures. 501 (Not\n  // Implemented) is deliberately excluded — it is deterministic, not transient.\n  //\n  // This is keyed on STATUS, not on the `internal_error` code: `RetryTransport`\n  // synthesizes `{ code: 'internal_error' }` for any error response whose body\n  // is not parseable JSON (see transport.ts), including bodyless 4xx like a 404\n  // download miss. Treating that code as transient would wrongly retry 4xx.\n  if (status === 500 || status === 502 || status === 503 || status === 504) 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\nconst knownB2ErrorCodes: ReadonlySet<string> = new Set(KNOWN_B2_ERROR_CODES)\n\nfunction isKnownB2ErrorCode(code: B2ErrorCode): code is KnownB2ErrorCode {\n  return knownB2ErrorCodes.has(code)\n}\n\nfunction assertNever(value: never): never {\n  throw new Error(`Unhandled B2 error code: ${String(value)}`)\n}\n\nfunction classifyKnownError(\n  response: B2ErrorResponse,\n  code: KnownB2ErrorCode,\n  options?: B2ErrorOptions,\n): B2Error {\n  switch (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 'bad_request':\n      return new BadRequestError(response, options)\n    case 'bad_bucket_name':\n    case 'invalid_bucket_name':\n      return new InvalidBucketNameError(response, options)\n    case 'bad_bucket_id':\n      return new BadBucketIdError(response, options)\n    case 'not_found':\n      return new NotFoundError(response, options)\n    case 'method_not_allowed':\n      return new MethodNotAllowedError(response, options)\n    case 'request_timeout':\n      return new RequestTimeoutError(response, options)\n    case 'too_many_requests':\n      return new TooManyRequestsError(response, options)\n    case 'conflict':\n      return new ConflictError(response, options)\n    case 'duplicate_bucket_name':\n      return new DuplicateBucketNameError(response, options)\n    case 'too_many_buckets':\n      return new TooManyBucketsError(response, options)\n    case 'too_many_files':\n      return new TooManyFilesError(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 'service_unavailable':\n      return new ServiceUnavailableError(response, options)\n    case 'internal_error':\n      return new InternalError(response, options)\n    case 'bad_json':\n      return new BadJsonError(response, options)\n    case 'invalid_bucket_id':\n      return new InvalidBucketIdError(response, options)\n    case 'invalid_bucket_info':\n      return new InvalidBucketInfoError(response, options)\n    case 'file_not_present':\n    case 'no_such_file':\n      return new FileNotPresentError(response, options)\n    case 'out_of_range':\n      return new OutOfRangeError(response, options)\n    case 'range_not_satisfiable':\n      return new RangeNotSatisfiableError(response, options)\n    case 'invalid_file_id':\n      return new InvalidFileIdError(response, options)\n    case 'invalid_file_name':\n      return new InvalidFileNameError(response, options)\n    case 'invalid_file_info':\n      return new InvalidFileInfoError(response, options)\n    case 'invalid_part_number':\n      return new InvalidPartNumberError(response, options)\n    case 'bad_sha1_checksum':\n      return new ChecksumMismatchError(response, options)\n    default:\n      return assertNever(code)\n  }\n}\n\nfunction classifyUnknownError(response: B2ErrorResponse, options?: B2ErrorOptions): B2Error {\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\n/**\n * Maps a B2 error response to the appropriate {@link B2Error} subclass.\n * Uses known error codes for exact matching, then falls back to HTTP status\n * codes for unknown future B2 codes.\n *\n * Maintainer note: when B2 documents a new error code, add it to\n * `KNOWN_B2_ERROR_CODES` in `src/types/errors.ts` and add a matching\n * `classifyKnownError` switch case. Unknown codes fall through to the\n * HTTP-status-based heuristic and finally to a generic `B2Error`, which is\n * safe but loses semantic specificity (the caller can't `instanceof` against\n * a precise subclass and the retry decision relies on status alone).\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(response: B2ErrorResponse, options?: B2ErrorOptions): B2Error {\n  // `RetryTransport` and ranged-download parsing synthesize `internal_error`\n  // when a non-JSON response body cannot provide a real B2 code. Only the\n  // documented 500/internal_error pair should classify as InternalError.\n  if (response.code === 'internal_error' && response.status !== 500) {\n    return classifyUnknownError(response, options)\n  }\n\n  if (isKnownB2ErrorCode(response.code)) return classifyKnownError(response, response.code, options)\n\n  return classifyUnknownError(response, options)\n}\n"],"mappings":"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"}

package/dist/errors/index.d.cts

@@ -1,4 +1,25 @@
 import { B2ErrorCode, B2ErrorResponse } from '../types/errors.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+/** Thrown when an explicit resumeFileId is not compatible with the requested upload. */
+export declare class ResumeFileIdMismatchError extends Error {
+    /** Caller-supplied unfinished large file ID that failed verification. */
+    readonly fileId: LargeFileId;
+    /** Requested destination file name. */
+    readonly fileName: string;
+    /**
+     * Creates a new resume-file ID mismatch error.
+     * @param fileId - Caller-supplied unfinished large file ID that failed verification.
+     * @param fileName - Requested destination file name.
+     */
+    constructor(fileId: LargeFileId, fileName: string);
+}
+/** Metadata captured from B2 error response headers. */
+export interface B2ErrorOptions {
+    /** Retry delay in seconds from the `Retry-After` response header, if present. */
+    readonly retryAfter?: number;
+    /** B2 request ID from the `X-Bz-Request-Id` response header, if present. */
+    readonly requestId?: string;
+}
 /**
  * Base error class for all B2 API errors.
  * Contains the HTTP status, B2 error code, and retry metadata from the response.
@@ -19,122 +40,250 @@ export declare class B2Error extends Error {
      * @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;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        retryAfter?: number;
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when B2 reports an internal server error. */
+export declare class InternalError extends B2Error {
+    /**
+     * Creates a new InternalError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        retryAfter?: number;
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when the account has reached the maximum number of buckets. */
+export declare class TooManyBucketsError extends B2Error {
+    /**
+     * Creates a new TooManyBucketsError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when the bucket or request has reached the maximum number of files. */
+export declare class TooManyFilesError extends B2Error {
+    /**
+     * Creates a new TooManyFilesError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a requested B2 resource does not exist. */
+export declare class NotFoundError extends B2Error {
+    /**
+     * Creates a new NotFoundError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a bucket name is malformed, reserved, or otherwise rejected by B2. */
+export declare class InvalidBucketNameError extends B2Error {
+    /**
+     * Creates a new InvalidBucketNameError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when bucket metadata fails B2 validation. */
+export declare class InvalidBucketInfoError extends B2Error {
+    /**
+     * Creates a new InvalidBucketInfoError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a bucket ID is malformed or does not identify a valid bucket. */
+export declare class BadBucketIdError extends B2Error {
+    /**
+     * Creates a new BadBucketIdError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when the B2 endpoint does not allow the request method. */
+export declare class MethodNotAllowedError extends B2Error {
+    /**
+     * Creates a new MethodNotAllowedError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when the request conflicts with current B2 resource state. */
+export declare class ConflictError extends B2Error {
+    /**
+     * Creates a new ConflictError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /** 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when B2 cannot parse the JSON request body. */
+export declare class BadJsonError extends B2Error {
+    /**
+     * Creates a new BadJsonError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a bucket ID has a valid shape but does not identify a usable bucket. */
+export declare class InvalidBucketIdError extends B2Error {
+    /**
+     * Creates a new InvalidBucketIdError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a numeric request parameter is outside the allowed range. */
+export declare class OutOfRangeError extends B2Error {
+    /**
+     * Creates a new OutOfRangeError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a requested byte range cannot be satisfied. */
+export declare class RangeNotSatisfiableError extends B2Error {
+    /**
+     * Creates a new RangeNotSatisfiableError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a file name is malformed or otherwise rejected by B2. */
+export declare class InvalidFileNameError extends B2Error {
+    /**
+     * Creates a new InvalidFileNameError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when file metadata fails B2 validation. */
+export declare class InvalidFileInfoError extends B2Error {
+    /**
+     * Creates a new InvalidFileInfoError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a file ID is malformed or does not identify a valid file. */
+export declare class InvalidFileIdError extends B2Error {
+    /**
+     * Creates a new InvalidFileIdError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
+}
+/** Thrown when a multipart upload part number is invalid. */
+export declare class InvalidPartNumberError extends B2Error {
+    /**
+     * Creates a new InvalidPartNumberError instance.
+     * @param response - Parsed B2 error response body.
+     * @param options - Optional metadata from response headers.
+     */
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /**
  * Thrown when an upload URL is no longer valid and must be refreshed.
@@ -154,35 +303,26 @@ 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /**
  * 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.
+ * When B2 returns `bad_sha1_checksum`, {@link classifyError} instantiates
+ * this class so callers can handle checksum failures with `instanceof`.
+ * Generic `bad_request` checksum failures continue to classify as
+ * {@link BadRequestError}.
  */
 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.
+     * @param options - Optional metadata from response headers.
      */
-    constructor(response: B2ErrorResponse, options?: {
-        requestId?: string;
-    });
+    constructor(response: B2ErrorResponse, options?: B2ErrorOptions);
 }
 /**
  * Thrown by client-side capability checks when the application key is missing
@@ -213,19 +353,45 @@ export declare class B2InsufficientCapabilityError extends Error {
  * 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.
+     * @param url - The URL that was rejected. Stored as a sanitized URL.
      */
-    constructor(message: string, 
-    /** The full URL that was rejected. */
-    url: string);
+    constructor(message: string, url: string);
+    /** Sanitized URL that was rejected. */
+    readonly url: string;
+}
+/** Thrown when a configured auth realm cannot safely be used for authorization. */
+export declare class B2RealmConfigurationError extends B2Error {
+    /**
+     * Creates a new B2RealmConfigurationError instance.
+     *
+     * @param message - Human-readable description of the invalid realm setting.
+     */
+    constructor(message: string);
+}
+/** Thrown when the SDK refuses to follow an HTTP redirect automatically. */
+export declare class B2RedirectError extends Error {
+    /** Always `false` because a blocked redirect is deterministic. */
+    readonly retryable = false;
+    /** Sanitized request URL whose response attempted to redirect. */
+    readonly url: string;
+    /** HTTP redirect status code, or 0 for an opaque browser redirect. */
+    readonly status: number;
+    /** Sanitized redirect target, or `null` when no Location header was present. */
+    readonly location: string | null;
+    /**
+     * Creates a new B2RedirectError instance.
+     *
+     * @param url - Request URL whose response attempted to redirect. Stored as a sanitized URL.
+     * @param status - HTTP redirect status code.
+     * @param location - Redirect Location header, if present. Stored as a sanitized URL.
+     */
+    constructor(url: string, status: number, location: string | null);
 }
 /** Thrown when a network-level failure occurs (DNS, TCP, TLS). Always retryable. */
 export declare class NetworkError extends Error {
@@ -239,26 +405,63 @@ export declare class NetworkError extends Error {
      */
     constructor(message: string, cause?: unknown | undefined);
 }
+/**
+ * Thrown when an upload POST returned a response but its body could not be
+ * read. The upload may already have been stored by B2, so retrying this error
+ * can create duplicate file versions or parts.
+ */
+export declare class UploadResponseBodyError extends Error {
+    /** Underlying response body error, when available. */
+    readonly cause?: unknown;
+    /**
+     * Creates a new UploadResponseBodyError instance.
+     * @param message - Human-readable description of the response read failure.
+     * @param options - Optional cause.
+     */
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/**
+ * Thrown when `b2_finish_large_file` returned a response but its body could not
+ * be read. The large file may already be committed server-side, so high-level
+ * upload paths do not cancel the large file after this error.
+ */
+export declare class FinishLargeFileResponseBodyError extends Error {
+    /** Ambiguous large file ID that may already be committed server-side. */
+    readonly fileId?: LargeFileId;
+    /** Bucket requested by the high-level upload, when available. */
+    readonly bucketId?: BucketId;
+    /** File name requested by the high-level upload, when available. */
+    readonly fileName?: string;
+    /**
+     * Creates a new FinishLargeFileResponseBodyError instance.
+     * @param message - Human-readable description of the response read failure.
+     * @param options - Optional cause and reconciliation metadata.
+     */
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+        readonly fileId?: LargeFileId;
+        readonly bucketId?: BucketId;
+        readonly fileName?: string;
+    });
+}
 /**
  * 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.
+ * Uses known error codes for exact matching, then falls back to HTTP status
+ * codes for unknown future B2 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.
+ * Maintainer note: when B2 documents a new error code, add it to
+ * `KNOWN_B2_ERROR_CODES` in `src/types/errors.ts` and add a matching
+ * `classifyKnownError` switch case. Unknown codes fall through to the
+ * HTTP-status-based heuristic and finally to a generic `B2Error`, which is
+ * safe but loses semantic specificity (the caller can't `instanceof` against
+ * a precise subclass and the retry decision relies on status alone).
  *
  * @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;
+export declare function classifyError(response: B2ErrorResponse, options?: B2ErrorOptions): B2Error;
 //# sourceMappingURL=index.d.ts.map