@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/upload/abort-scope.d.ts

@@ -0,0 +1,48 @@
+/** Shared abort scope for multipart work that fans out into concurrent tasks. */
+export interface AbortScope {
+    /** Signal linked to the caller signal and to task-level failures. */
+    readonly signal: AbortSignal;
+    /** Abort the scope if it has not already been aborted. */
+    abort(reason: unknown): void;
+    /** Detach any upstream abort listener. */
+    dispose(): void;
+}
+/**
+ * Creates an abort scope linked to an optional upstream signal.
+ * Task failures can abort the same scope so sibling tasks stop promptly.
+ * @param upstream - Caller-provided abort signal, if any.
+ *
+ * @returns A linked abort scope.
+ */
+export declare function createAbortScope(upstream: AbortSignal | undefined): AbortScope;
+/**
+ * Throws the abort reason or first task rejection from a settled task set.
+ * @param settled - Results from `Promise.allSettled`.
+ * @param abortScope - Scope that coordinated the tasks.
+ *
+ * @throws The abort reason or first rejected task reason.
+ */
+export declare function throwRejectedOrAbortReason(settled: readonly PromiseSettledResult<unknown>[], abortScope: AbortScope): void;
+/**
+ * Returns the observable reason for an aborted signal.
+ * @param signal - Aborted signal to inspect.
+ *
+ * @returns The signal's reason, or a standard AbortError when the runtime did not provide one.
+ */
+export declare function abortReason(signal: AbortSignal): unknown;
+/**
+ * Races a request promise against an abort signal.
+ *
+ * The underlying request must still receive the same signal so transports can
+ * cancel their network work. This helper makes callers stop waiting promptly
+ * even when a test double or custom transport ignores the signal.
+ *
+ * @param promise - Request promise to observe.
+ * @param signal - Signal that should stop waiting for the request.
+ *
+ * @returns The request result if it settles before the signal aborts.
+ *
+ * @throws The abort reason if the signal aborts first, or the request rejection.
+ */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+//# sourceMappingURL=abort-scope.d.ts.map

package/dist/upload/abort-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-scope.d.ts","sourceRoot":"","sources":["../../src/upload/abort-scope.js"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,0DAA0D;IAC1D,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAC5B,0CAA0C;IAC1C,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,GAAG,UAAU,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,oBAAoB,CAAC,OAAO,CAAC,EAAE,EACjD,UAAU,EAAE,UAAU,GACrB,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAqB3F"}

package/dist/upload/abort-scope.js

@@ -0,0 +1,88 @@
+//#region src/upload/abort-scope.ts
+/**
+* Creates an abort scope linked to an optional upstream signal.
+* Task failures can abort the same scope so sibling tasks stop promptly.
+* @param upstream - Caller-provided abort signal, if any.
+*
+* @returns A linked abort scope.
+*/
+function createAbortScope(upstream) {
+	const controller = new AbortController();
+	let upstreamAbort;
+	const abort = (reason) => {
+		if (!controller.signal.aborted) controller.abort(reason);
+	};
+	if (upstream?.aborted === true) abort(upstream.reason);
+	else if (upstream !== void 0) {
+		upstreamAbort = () => abort(upstream.reason);
+		upstream.addEventListener("abort", upstreamAbort, { once: true });
+	}
+	return {
+		signal: controller.signal,
+		abort,
+		dispose() {
+			if (upstreamAbort !== void 0) upstream?.removeEventListener("abort", upstreamAbort);
+		}
+	};
+}
+/**
+* Throws the abort reason or first task rejection from a settled task set.
+* @param settled - Results from `Promise.allSettled`.
+* @param abortScope - Scope that coordinated the tasks.
+*
+* @throws The abort reason or first rejected task reason.
+*/
+function throwRejectedOrAbortReason(settled, abortScope) {
+	const rejected = settled.find((result) => result.status === "rejected");
+	if (rejected === void 0) return;
+	if (abortScope.signal.aborted && abortScope.signal.reason !== void 0) throw abortScope.signal.reason;
+	/* v8 ignore next -- Defensive fallback for unexpected task rejections outside the abort scope. */
+	throw rejected.reason;
+}
+/**
+* Returns the observable reason for an aborted signal.
+* @param signal - Aborted signal to inspect.
+*
+* @returns The signal's reason, or a standard AbortError when the runtime did not provide one.
+*/
+function abortReason(signal) {
+	return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+/**
+* Races a request promise against an abort signal.
+*
+* The underlying request must still receive the same signal so transports can
+* cancel their network work. This helper makes callers stop waiting promptly
+* even when a test double or custom transport ignores the signal.
+*
+* @param promise - Request promise to observe.
+* @param signal - Signal that should stop waiting for the request.
+*
+* @returns The request result if it settles before the signal aborts.
+*
+* @throws The abort reason if the signal aborts first, or the request rejection.
+*/
+async function raceWithAbort(promise, signal) {
+	if (signal.aborted) {
+		promise.catch(() => {});
+		throw abortReason(signal);
+	}
+	let removeAbortListener;
+	const abort = new Promise((_, reject) => {
+		const onAbort = () => reject(abortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		return await Promise.race([promise, abort]);
+	} catch (err) {
+		if (signal.aborted) promise.catch(() => {});
+		throw err;
+	} finally {
+		removeAbortListener?.();
+	}
+}
+//#endregion
+export { abortReason, createAbortScope, raceWithAbort, throwRejectedOrAbortReason };
+
+//# sourceMappingURL=abort-scope.js.map

package/dist/upload/abort-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-scope.js","names":[],"sources":["../../src/upload/abort-scope.ts"],"sourcesContent":["/** Shared abort scope for multipart work that fans out into concurrent tasks. */\nexport interface AbortScope {\n  /** Signal linked to the caller signal and to task-level failures. */\n  readonly signal: AbortSignal\n  /** Abort the scope if it has not already been aborted. */\n  abort(reason: unknown): void\n  /** Detach any upstream abort listener. */\n  dispose(): void\n}\n\n/**\n * Creates an abort scope linked to an optional upstream signal.\n * Task failures can abort the same scope so sibling tasks stop promptly.\n * @param upstream - Caller-provided abort signal, if any.\n *\n * @returns A linked abort scope.\n */\nexport function createAbortScope(upstream: AbortSignal | undefined): AbortScope {\n  const controller = new AbortController()\n  let upstreamAbort: (() => void) | undefined\n  const abort = (reason: unknown): void => {\n    if (!controller.signal.aborted) controller.abort(reason)\n  }\n\n  if (upstream?.aborted === true) {\n    abort(upstream.reason)\n  } else if (upstream !== undefined) {\n    upstreamAbort = () => abort(upstream.reason)\n    upstream.addEventListener('abort', upstreamAbort, { once: true })\n  }\n\n  return {\n    signal: controller.signal,\n    abort,\n    dispose() {\n      if (upstreamAbort !== undefined) upstream?.removeEventListener('abort', upstreamAbort)\n    },\n  }\n}\n\n/**\n * Throws the abort reason or first task rejection from a settled task set.\n * @param settled - Results from `Promise.allSettled`.\n * @param abortScope - Scope that coordinated the tasks.\n *\n * @throws The abort reason or first rejected task reason.\n */\nexport function throwRejectedOrAbortReason(\n  settled: readonly PromiseSettledResult<unknown>[],\n  abortScope: AbortScope,\n): void {\n  const rejected = settled.find(\n    (result): result is PromiseRejectedResult => result.status === 'rejected',\n  )\n  if (rejected === undefined) return\n  if (abortScope.signal.aborted && abortScope.signal.reason !== undefined) {\n    throw abortScope.signal.reason\n  }\n  /* v8 ignore next -- Defensive fallback for unexpected task rejections outside the abort scope. */\n  throw rejected.reason\n}\n\n/**\n * Returns the observable reason for an aborted signal.\n * @param signal - Aborted signal to inspect.\n *\n * @returns The signal's reason, or a standard AbortError when the runtime did not provide one.\n */\nexport function abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\n/**\n * Races a request promise against an abort signal.\n *\n * The underlying request must still receive the same signal so transports can\n * cancel their network work. This helper makes callers stop waiting promptly\n * even when a test double or custom transport ignores the signal.\n *\n * @param promise - Request promise to observe.\n * @param signal - Signal that should stop waiting for the request.\n *\n * @returns The request result if it settles before the signal aborts.\n *\n * @throws The abort reason if the signal aborts first, or the request rejection.\n */\nexport async function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {\n  if (signal.aborted) {\n    promise.catch(() => {})\n    throw abortReason(signal)\n  }\n\n  let removeAbortListener: (() => void) | undefined\n  const abort = new Promise<never>((_, reject) => {\n    const onAbort = (): void => reject(abortReason(signal))\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n  })\n\n  try {\n    return await Promise.race([promise, abort])\n  } catch (err) {\n    if (signal.aborted) promise.catch(() => {})\n    throw err\n  } finally {\n    removeAbortListener?.()\n  }\n}\n"],"mappings":";;;;;;;;AAiBA,SAAgB,iBAAiB,UAA+C;CAC9E,MAAM,aAAa,IAAI,gBAAgB;CACvC,IAAI;CACJ,MAAM,SAAS,WAA0B;EACvC,IAAI,CAAC,WAAW,OAAO,SAAS,WAAW,MAAM,MAAM;CACzD;CAEA,IAAI,UAAU,YAAY,MACxB,MAAM,SAAS,MAAM;MAChB,IAAI,aAAa,KAAA,GAAW;EACjC,sBAAsB,MAAM,SAAS,MAAM;EAC3C,SAAS,iBAAiB,SAAS,eAAe,EAAE,MAAM,KAAK,CAAC;CAClE;CAEA,OAAO;EACL,QAAQ,WAAW;EACnB;EACA,UAAU;GACR,IAAI,kBAAkB,KAAA,GAAW,UAAU,oBAAoB,SAAS,aAAa;EACvF;CACF;AACF;;;;;;;;AASA,SAAgB,2BACd,SACA,YACM;CACN,MAAM,WAAW,QAAQ,MACtB,WAA4C,OAAO,WAAW,UACjE;CACA,IAAI,aAAa,KAAA,GAAW;CAC5B,IAAI,WAAW,OAAO,WAAW,WAAW,OAAO,WAAW,KAAA,GAC5D,MAAM,WAAW,OAAO;;CAG1B,MAAM,SAAS;AACjB;;;;;;;AAQA,SAAgB,YAAY,QAA8B;CACxD,OAAO,OAAO,UAAU,IAAI,aAAa,WAAW,YAAY;AAClE;;;;;;;;;;;;;;;AAgBA,eAAsB,cAAiB,SAAqB,QAAiC;CAC3F,IAAI,OAAO,SAAS;EAClB,QAAQ,YAAY,CAAC,CAAC;EACtB,MAAM,YAAY,MAAM;CAC1B;CAEA,IAAI;CACJ,MAAM,QAAQ,IAAI,SAAgB,GAAG,WAAW;EAC9C,MAAM,gBAAsB,OAAO,YAAY,MAAM,CAAC;EACtD,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,4BAA4B,OAAO,oBAAoB,SAAS,OAAO;CACzE,CAAC;CAED,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,KAAK,CAAC;CAC5C,SAAS,KAAK;EACZ,IAAI,OAAO,SAAS,QAAQ,YAAY,CAAC,CAAC;EAC1C,MAAM;CACR,UAAU;EACR,sBAAsB;CACxB;AACF"}

package/dist/upload/cancel.cjs

@@ -1,10 +1,185 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const bestEffort = require("../util/best-effort.cjs");
-async function cancelLargeFileBestEffort(raw, accountInfo, fileId) {
-  await bestEffort.bestEffort(
-    () => raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId })
-  );
+const require_errors_index = require("../errors/index.cjs");
+const require_best_effort = require("../util/best-effort.cjs");
+//#region src/upload/cancel.ts
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+var DEFAULT_CLEANUP_TIMEOUT_MS = 3e4;
+var fallbackCleanupDisposers = /* @__PURE__ */ new WeakMap();
+/**
+* Cancels an unfinished large file on a best-effort basis. Used at every
+* error-handling boundary in the multipart upload, write-stream, and
+* server-side copy paths to roll back in-progress uploads without
+* letting a cancellation failure mask the underlying error the caller
+* is about to see.
+*
+* Centralising the call removes a five-line `bestEffort` block that
+* recurred at six sites with identical shape — the only thing that
+* changed was the captured `fileId` and the surrounding error trail.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state for the API URL + token.
+* @param fileId - The in-progress large file ID to cancel.
+* @param options - Optional request controls and cleanup-failure observer.
+*
+* @returns A promise that always resolves, regardless of the cancel
+*   call's outcome.
+*/
+async function cancelLargeFileBestEffort(raw, accountInfo, fileId, options) {
+	await require_best_effort.bestEffort(async () => {
+		const requestOptions = cleanupRequestOptions(options?.signal);
+		await waitForCleanup(raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }, requestOptions), requestOptions.signal);
+	}, (error) => options?.onCleanupFailure?.({
+		fileId,
+		error,
+		reason: "cancel-failed"
+	}));
 }
+/**
+* Returns cleanup request controls with a live timeout signal.
+*
+* @param signal - Caller-provided abort signal, if any.
+* @param timeoutMs - Maximum time to spend waiting for cleanup.
+*
+* @returns Request controls with a signal independent of an already-aborted caller signal.
+*/
+function cleanupRequestOptions(signal, timeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS) {
+	return { signal: createCleanupSignal(signal, timeoutMs) };
+}
+function createCleanupSignal(signal, timeoutMs) {
+	if (typeof AbortSignal.timeout === "function") {
+		if (signal === void 0 || signal.aborted) return AbortSignal.timeout(timeoutMs);
+		if (typeof AbortSignal.any === "function") return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+	}
+	return createFallbackCleanupSignal(signal, timeoutMs);
+}
+function createFallbackCleanupSignal(signal, timeoutMs) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => {
+		abortFallbackCleanup(controller, cleanupTimeoutReason(), cleanup);
+	}, timeoutMs);
+	const onAbort = () => {
+		const reason = signal === void 0 ? cleanupDomException("Cleanup aborted", "AbortError") : cleanupAbortReason(signal);
+		abortFallbackCleanup(controller, reason, cleanup);
+	};
+	const cleanup = () => {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", onAbort);
+		fallbackCleanupDisposers.delete(controller.signal);
+	};
+	fallbackCleanupDisposers.set(controller.signal, cleanup);
+	if (signal === void 0 || signal.aborted) return controller.signal;
+	signal.addEventListener("abort", onAbort, { once: true });
+	controller.signal.addEventListener("abort", cleanup, { once: true });
+	return controller.signal;
+}
+function abortFallbackCleanup(controller, reason, cleanup) {
+	if (!controller.signal.aborted) controller.abort(reason);
+	cleanup();
+}
+async function waitForCleanup(request, signal) {
+	if (signal.aborted) throw cleanupAbortReason(signal);
+	let removeAbortListener;
+	const aborted = new Promise((_resolve, reject) => {
+		const onAbort = () => reject(cleanupAbortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		await Promise.race([request, aborted]);
+	} finally {
+		removeAbortListener?.();
+		fallbackCleanupDisposers.get(signal)?.();
+		request.catch(() => {});
+	}
+}
+function cleanupAbortReason(signal) {
+	return signal.reason ?? cleanupDomException("Cleanup aborted", "AbortError");
+}
+function cleanupTimeoutReason() {
+	return cleanupDomException("Cleanup timed out", "TimeoutError");
+}
+function cleanupDomException(message, name) {
+	if (typeof DOMException === "function") return new DOMException(message, name);
+	const error = new Error(message);
+	error.name = name;
+	return error;
+}
+/**
+* Emits an observable cleanup event when cancellation is deliberately skipped
+* because `b2_finish_large_file` may already have committed the file.
+* @param fileId - Large file whose final state is ambiguous.
+* @param error - Ambiguous finish error that will be thrown to the caller.
+* @param onCleanupFailure - Optional observer for cleanup-related events.
+*/
+function notifyAmbiguousLargeFileCleanupSkipped(fileId, error, onCleanupFailure) {
+	try {
+		onCleanupFailure?.({
+			fileId,
+			error,
+			reason: "finish-ambiguous"
+		});
+	} catch {}
+}
+/**
+* Adds high-level reconciliation metadata to an ambiguous finish response-body
+* error and notifies the cleanup observer that cancellation was skipped.
+*
+* @param err - Raw finish response-body error from the low-level client.
+* @param options - Large-file context used for reconciliation.
+*
+* @returns The enriched {@link FinishLargeFileResponseBodyError}.
+*/
+function handleAmbiguousFinishLargeFileResponseBodyError(err, options) {
+	const enriched = err.fileId === options.fileId && err.bucketId === options.bucketId && err.fileName === options.fileName ? err : new require_errors_index.FinishLargeFileResponseBodyError(err.message, {
+		cause: err.cause ?? err,
+		fileId: options.fileId,
+		bucketId: options.bucketId,
+		fileName: options.fileName
+	});
+	notifyAmbiguousLargeFileCleanupSkipped(options.fileId, enriched, options.onCleanupFailure);
+	return enriched;
+}
+/**
+* Performs the shared large-file failure policy: ambiguous finish-body errors
+* are enriched and left uncancelled, while all pre-finish errors trigger
+* best-effort cancellation.
+*
+* @param err - Error from a multipart upload/copy/write-stream path.
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param context - Large file metadata used for cleanup and diagnostics.
+* @param options - Cleanup policy controls.
+*
+* @returns The error that should be surfaced to the caller.
+*/
+async function resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options = {}) {
+	if (err instanceof require_errors_index.FinishLargeFileResponseBodyError) return handleAmbiguousFinishLargeFileResponseBodyError(err, context);
+	if (options.cancelOnError ?? true) await cancelLargeFileBestEffort(raw, accountInfo, context.fileId, {
+		...context.signal !== void 0 ? { signal: context.signal } : {},
+		...context.onCleanupFailure !== void 0 ? { onCleanupFailure: context.onCleanupFailure } : {}
+	});
+	return err;
+}
+/**
+* Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths
+* that can surface the error directly.
+* @param err - Error from a multipart upload/copy/write-stream path.
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param context - Large file metadata used for cleanup and diagnostics.
+* @param options - Cleanup policy controls.
+*
+* @throws The resolved large-file error after cleanup policy is applied.
+*/
+async function cleanupAfterLargeFileError(err, raw, accountInfo, context, options) {
+	throw await resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options);
+}
+//#endregion
+exports.DEFAULT_CLEANUP_TIMEOUT_MS = DEFAULT_CLEANUP_TIMEOUT_MS;
 exports.cancelLargeFileBestEffort = cancelLargeFileBestEffort;
-//# sourceMappingURL=cancel.cjs.map
+exports.cleanupAfterLargeFileError = cleanupAfterLargeFileError;
+exports.cleanupRequestOptions = cleanupRequestOptions;
+exports.handleAmbiguousFinishLargeFileResponseBodyError = handleAmbiguousFinishLargeFileResponseBodyError;
+exports.notifyAmbiguousLargeFileCleanupSkipped = notifyAmbiguousLargeFileCleanupSkipped;
+exports.resolveLargeFileErrorAfterCleanup = resolveLargeFileErrorAfterCleanup;
+
+//# sourceMappingURL=cancel.cjs.map

package/dist/upload/cancel.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"cancel.cjs","sources":["../../src/upload/cancel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { LargeFileId } from '../types/ids.ts'\nimport { bestEffort } from '../util/best-effort.ts'\n\n/**\n * Cancels an unfinished large file on a best-effort basis. Used at every\n * error-handling boundary in the multipart upload, write-stream, and\n * server-side copy paths to roll back in-progress uploads without\n * letting a cancellation failure mask the underlying error the caller\n * is about to see.\n *\n * Centralising the call removes a five-line `bestEffort` block that\n * recurred at six sites with identical shape — the only thing that\n * changed was the captured `fileId` and the surrounding error trail.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state for the API URL + token.\n * @param fileId - The in-progress large file ID to cancel.\n *\n * @returns A promise that always resolves, regardless of the cancel\n *   call's outcome.\n */\nexport async function cancelLargeFileBestEffort(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n): Promise<void> {\n  await bestEffort(() =>\n    raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }),\n  )\n}\n"],"names":["bestEffort"],"mappings":";;;AAuBA,eAAsB,0BACpB,KACA,aACA,QACe;AACf,QAAMA,WAAAA;AAAAA,IAAW,MACf,IAAI,gBAAgB,YAAY,UAAA,GAAa,YAAY,gBAAgB,EAAE,OAAA,CAAQ;AAAA,EAAA;AAEvF;;"}
+{"version":3,"file":"cancel.cjs","names":[],"sources":["../../src/upload/cancel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { FinishLargeFileResponseBodyError } from '../errors/index.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport { bestEffort } from '../util/best-effort.ts'\n\n/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */\nexport interface CancelLargeFileCleanupFailureEvent {\n  /** Unfinished large file that may remain orphaned. */\n  readonly fileId: LargeFileId\n  /** Error thrown by `b2_cancel_large_file`. */\n  readonly error: unknown\n  /** Cleanup phase that produced the observable event. */\n  readonly reason: 'cancel-failed'\n}\n\n/** Event emitted when cleanup is skipped because finish may have committed. */\nexport interface AmbiguousFinishCleanupFailureEvent {\n  /** Large file whose final server-side state is ambiguous. */\n  readonly fileId: LargeFileId\n  /** Error thrown to the caller with reconciliation metadata. */\n  readonly error: FinishLargeFileResponseBodyError\n  /** Cleanup phase that produced the observable event. */\n  readonly reason: 'finish-ambiguous'\n}\n\n/** Event emitted when large-file cleanup fails or is deliberately skipped. */\nexport type CleanupFailureEvent =\n  | CancelLargeFileCleanupFailureEvent\n  | AmbiguousFinishCleanupFailureEvent\n\n/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */\nexport type CleanupFailureListener = (event: CleanupFailureEvent) => void\n\n/** Shared option for observing large-file cleanup failures or skipped cleanup. */\nexport interface CleanupFailureOptions {\n  /**\n   * Callback invoked if best-effort cancellation fails, or if cancellation is\n   * skipped because `b2_finish_large_file` may already have committed.\n   */\n  readonly onCleanupFailure?: CleanupFailureListener\n}\n\n/** Default wall-clock bound for best-effort cleanup calls after upload failure. */\nexport const DEFAULT_CLEANUP_TIMEOUT_MS = 30_000\n\nconst fallbackCleanupDisposers = new WeakMap<AbortSignal, () => void>()\n\n/** Context needed to reconcile or cancel an unfinished large file after an error. */\nexport interface LargeFileCleanupContext {\n  readonly fileId: LargeFileId\n  readonly bucketId: BucketId\n  readonly fileName: string\n  readonly signal?: AbortSignal | undefined\n  readonly onCleanupFailure?: CleanupFailureListener | undefined\n}\n\n/** Options for applying the shared large-file cleanup policy. */\nexport interface LargeFileCleanupPolicyOptions {\n  /**\n   * Whether non-ambiguous failures should cancel the unfinished large file.\n   * Defaults to true. Explicit resume callers can disable this so the SDK does\n   * not cancel a large file that it did not create.\n   */\n  readonly cancelOnError?: boolean\n}\n\n/**\n * Cancels an unfinished large file on a best-effort basis. Used at every\n * error-handling boundary in the multipart upload, write-stream, and\n * server-side copy paths to roll back in-progress uploads without\n * letting a cancellation failure mask the underlying error the caller\n * is about to see.\n *\n * Centralising the call removes a five-line `bestEffort` block that\n * recurred at six sites with identical shape — the only thing that\n * changed was the captured `fileId` and the surrounding error trail.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state for the API URL + token.\n * @param fileId - The in-progress large file ID to cancel.\n * @param options - Optional request controls and cleanup-failure observer.\n *\n * @returns A promise that always resolves, regardless of the cancel\n *   call's outcome.\n */\nexport async function cancelLargeFileBestEffort(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n  options?: { readonly signal?: AbortSignal } & CleanupFailureOptions,\n): Promise<void> {\n  await bestEffort(\n    async () => {\n      const requestOptions = cleanupRequestOptions(options?.signal)\n      const request = raw.cancelLargeFile(\n        accountInfo.getApiUrl(),\n        accountInfo.getAuthToken(),\n        { fileId },\n        requestOptions,\n      )\n      await waitForCleanup(request, requestOptions.signal)\n    },\n    (error) => options?.onCleanupFailure?.({ fileId, error, reason: 'cancel-failed' }),\n  )\n}\n\n/**\n * Returns cleanup request controls with a live timeout signal.\n *\n * @param signal - Caller-provided abort signal, if any.\n * @param timeoutMs - Maximum time to spend waiting for cleanup.\n *\n * @returns Request controls with a signal independent of an already-aborted caller signal.\n */\nexport function cleanupRequestOptions(\n  signal: AbortSignal | undefined,\n  timeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS,\n): { readonly signal: AbortSignal } {\n  return { signal: createCleanupSignal(signal, timeoutMs) }\n}\n\nfunction createCleanupSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {\n  if (typeof AbortSignal.timeout === 'function') {\n    if (signal === undefined || signal.aborted) return AbortSignal.timeout(timeoutMs)\n    if (typeof AbortSignal.any === 'function') {\n      return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])\n    }\n  }\n\n  return createFallbackCleanupSignal(signal, timeoutMs)\n}\n\nfunction createFallbackCleanupSignal(\n  signal: AbortSignal | undefined,\n  timeoutMs: number,\n): AbortSignal {\n  const controller = new AbortController()\n  const timeout = setTimeout(() => {\n    abortFallbackCleanup(controller, cleanupTimeoutReason(), cleanup)\n  }, timeoutMs)\n\n  const onAbort = () => {\n    const reason =\n      signal === undefined\n        ? cleanupDomException('Cleanup aborted', 'AbortError')\n        : cleanupAbortReason(signal)\n    abortFallbackCleanup(controller, reason, cleanup)\n  }\n  const cleanup = () => {\n    clearTimeout(timeout)\n    signal?.removeEventListener('abort', onAbort)\n    fallbackCleanupDisposers.delete(controller.signal)\n  }\n  fallbackCleanupDisposers.set(controller.signal, cleanup)\n\n  if (signal === undefined || signal.aborted) {\n    return controller.signal\n  }\n\n  signal.addEventListener('abort', onAbort, { once: true })\n  controller.signal.addEventListener('abort', cleanup, { once: true })\n  return controller.signal\n}\n\nfunction abortFallbackCleanup(\n  controller: AbortController,\n  reason: unknown,\n  cleanup: () => void,\n): void {\n  if (!controller.signal.aborted) controller.abort(reason)\n  cleanup()\n}\n\nasync function waitForCleanup(request: Promise<unknown>, signal: AbortSignal): Promise<void> {\n  if (signal.aborted) throw cleanupAbortReason(signal)\n\n  let removeAbortListener: (() => void) | undefined\n  const aborted = new Promise<never>((_resolve, reject) => {\n    const onAbort = () => reject(cleanupAbortReason(signal))\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n  })\n\n  try {\n    await Promise.race([request, aborted])\n  } finally {\n    removeAbortListener?.()\n    fallbackCleanupDisposers.get(signal)?.()\n    void request.catch(() => {})\n  }\n}\n\nfunction cleanupAbortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? cleanupDomException('Cleanup aborted', 'AbortError')\n}\n\nfunction cleanupTimeoutReason(): unknown {\n  return cleanupDomException('Cleanup timed out', 'TimeoutError')\n}\n\nfunction cleanupDomException(message: string, name: string): Error {\n  if (typeof DOMException === 'function') return new DOMException(message, name)\n  const error = new Error(message)\n  error.name = name\n  return error\n}\n\n/**\n * Emits an observable cleanup event when cancellation is deliberately skipped\n * because `b2_finish_large_file` may already have committed the file.\n * @param fileId - Large file whose final state is ambiguous.\n * @param error - Ambiguous finish error that will be thrown to the caller.\n * @param onCleanupFailure - Optional observer for cleanup-related events.\n */\nexport function notifyAmbiguousLargeFileCleanupSkipped(\n  fileId: LargeFileId,\n  error: FinishLargeFileResponseBodyError,\n  onCleanupFailure?: CleanupFailureListener,\n): void {\n  try {\n    onCleanupFailure?.({ fileId, error, reason: 'finish-ambiguous' })\n  } catch {\n    // Observer failures are secondary and must not hide the finish ambiguity.\n  }\n}\n\n/**\n * Adds high-level reconciliation metadata to an ambiguous finish response-body\n * error and notifies the cleanup observer that cancellation was skipped.\n *\n * @param err - Raw finish response-body error from the low-level client.\n * @param options - Large-file context used for reconciliation.\n *\n * @returns The enriched {@link FinishLargeFileResponseBodyError}.\n */\nexport function handleAmbiguousFinishLargeFileResponseBodyError(\n  err: FinishLargeFileResponseBodyError,\n  options: LargeFileCleanupContext,\n): FinishLargeFileResponseBodyError {\n  const enriched =\n    err.fileId === options.fileId &&\n    err.bucketId === options.bucketId &&\n    err.fileName === options.fileName\n      ? err\n      : new FinishLargeFileResponseBodyError(err.message, {\n          cause: err.cause ?? err,\n          fileId: options.fileId,\n          bucketId: options.bucketId,\n          fileName: options.fileName,\n        })\n  notifyAmbiguousLargeFileCleanupSkipped(options.fileId, enriched, options.onCleanupFailure)\n  return enriched\n}\n\n/**\n * Performs the shared large-file failure policy: ambiguous finish-body errors\n * are enriched and left uncancelled, while all pre-finish errors trigger\n * best-effort cancellation.\n *\n * @param err - Error from a multipart upload/copy/write-stream path.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param context - Large file metadata used for cleanup and diagnostics.\n * @param options - Cleanup policy controls.\n *\n * @returns The error that should be surfaced to the caller.\n */\nexport async function resolveLargeFileErrorAfterCleanup(\n  err: unknown,\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  context: LargeFileCleanupContext,\n  options: LargeFileCleanupPolicyOptions = {},\n): Promise<unknown> {\n  if (err instanceof FinishLargeFileResponseBodyError) {\n    return handleAmbiguousFinishLargeFileResponseBodyError(err, context)\n  }\n  if (options.cancelOnError ?? true) {\n    await cancelLargeFileBestEffort(raw, accountInfo, context.fileId, {\n      ...(context.signal !== undefined ? { signal: context.signal } : {}),\n      ...(context.onCleanupFailure !== undefined\n        ? { onCleanupFailure: context.onCleanupFailure }\n        : {}),\n    })\n  }\n  return err\n}\n\n/**\n * Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths\n * that can surface the error directly.\n * @param err - Error from a multipart upload/copy/write-stream path.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param context - Large file metadata used for cleanup and diagnostics.\n * @param options - Cleanup policy controls.\n *\n * @throws The resolved large-file error after cleanup policy is applied.\n */\nexport async function cleanupAfterLargeFileError(\n  err: unknown,\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  context: LargeFileCleanupContext,\n  options?: LargeFileCleanupPolicyOptions,\n): Promise<never> {\n  throw await resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options)\n}\n"],"mappings":"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"}

package/dist/upload/cancel.d.cts

@@ -1,6 +1,56 @@
 import { AccountInfo } from '../auth/account-info.js';
+import { FinishLargeFileResponseBodyError } from '../errors/index.js';
 import { RawClient } from '../raw/index.js';
-import { LargeFileId } from '../types/ids.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */
+export interface CancelLargeFileCleanupFailureEvent {
+    /** Unfinished large file that may remain orphaned. */
+    readonly fileId: LargeFileId;
+    /** Error thrown by `b2_cancel_large_file`. */
+    readonly error: unknown;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'cancel-failed';
+}
+/** Event emitted when cleanup is skipped because finish may have committed. */
+export interface AmbiguousFinishCleanupFailureEvent {
+    /** Large file whose final server-side state is ambiguous. */
+    readonly fileId: LargeFileId;
+    /** Error thrown to the caller with reconciliation metadata. */
+    readonly error: FinishLargeFileResponseBodyError;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'finish-ambiguous';
+}
+/** Event emitted when large-file cleanup fails or is deliberately skipped. */
+export type CleanupFailureEvent = CancelLargeFileCleanupFailureEvent | AmbiguousFinishCleanupFailureEvent;
+/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */
+export type CleanupFailureListener = (event: CleanupFailureEvent) => void;
+/** Shared option for observing large-file cleanup failures or skipped cleanup. */
+export interface CleanupFailureOptions {
+    /**
+     * Callback invoked if best-effort cancellation fails, or if cancellation is
+     * skipped because `b2_finish_large_file` may already have committed.
+     */
+    readonly onCleanupFailure?: CleanupFailureListener;
+}
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+export declare const DEFAULT_CLEANUP_TIMEOUT_MS = 30000;
+/** Context needed to reconcile or cancel an unfinished large file after an error. */
+export interface LargeFileCleanupContext {
+    readonly fileId: LargeFileId;
+    readonly bucketId: BucketId;
+    readonly fileName: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly onCleanupFailure?: CleanupFailureListener | undefined;
+}
+/** Options for applying the shared large-file cleanup policy. */
+export interface LargeFileCleanupPolicyOptions {
+    /**
+     * Whether non-ambiguous failures should cancel the unfinished large file.
+     * Defaults to true. Explicit resume callers can disable this so the SDK does
+     * not cancel a large file that it did not create.
+     */
+    readonly cancelOnError?: boolean;
+}
 /**
  * Cancels an unfinished large file on a best-effort basis. Used at every
  * error-handling boundary in the multipart upload, write-stream, and
@@ -15,9 +65,67 @@ import { LargeFileId } from '../types/ids.js';
  * @param raw - Low-level B2 API client.
  * @param accountInfo - Authorized account state for the API URL + token.
  * @param fileId - The in-progress large file ID to cancel.
+ * @param options - Optional request controls and cleanup-failure observer.
  *
  * @returns A promise that always resolves, regardless of the cancel
  *   call's outcome.
  */
-export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId): Promise<void>;
+export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options?: {
+    readonly signal?: AbortSignal;
+} & CleanupFailureOptions): Promise<void>;
+/**
+ * Returns cleanup request controls with a live timeout signal.
+ *
+ * @param signal - Caller-provided abort signal, if any.
+ * @param timeoutMs - Maximum time to spend waiting for cleanup.
+ *
+ * @returns Request controls with a signal independent of an already-aborted caller signal.
+ */
+export declare function cleanupRequestOptions(signal: AbortSignal | undefined, timeoutMs?: number): {
+    readonly signal: AbortSignal;
+};
+/**
+ * Emits an observable cleanup event when cancellation is deliberately skipped
+ * because `b2_finish_large_file` may already have committed the file.
+ * @param fileId - Large file whose final state is ambiguous.
+ * @param error - Ambiguous finish error that will be thrown to the caller.
+ * @param onCleanupFailure - Optional observer for cleanup-related events.
+ */
+export declare function notifyAmbiguousLargeFileCleanupSkipped(fileId: LargeFileId, error: FinishLargeFileResponseBodyError, onCleanupFailure?: CleanupFailureListener): void;
+/**
+ * Adds high-level reconciliation metadata to an ambiguous finish response-body
+ * error and notifies the cleanup observer that cancellation was skipped.
+ *
+ * @param err - Raw finish response-body error from the low-level client.
+ * @param options - Large-file context used for reconciliation.
+ *
+ * @returns The enriched {@link FinishLargeFileResponseBodyError}.
+ */
+export declare function handleAmbiguousFinishLargeFileResponseBodyError(err: FinishLargeFileResponseBodyError, options: LargeFileCleanupContext): FinishLargeFileResponseBodyError;
+/**
+ * Performs the shared large-file failure policy: ambiguous finish-body errors
+ * are enriched and left uncancelled, while all pre-finish errors trigger
+ * best-effort cancellation.
+ *
+ * @param err - Error from a multipart upload/copy/write-stream path.
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param context - Large file metadata used for cleanup and diagnostics.
+ * @param options - Cleanup policy controls.
+ *
+ * @returns The error that should be surfaced to the caller.
+ */
+export declare function resolveLargeFileErrorAfterCleanup(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<unknown>;
+/**
+ * Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths
+ * that can surface the error directly.
+ * @param err - Error from a multipart upload/copy/write-stream path.
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param context - Large file metadata used for cleanup and diagnostics.
+ * @param options - Cleanup policy controls.
+ *
+ * @throws The resolved large-file error after cleanup policy is applied.
+ */
+export declare function cleanupAfterLargeFileError(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<never>;
 //# sourceMappingURL=cancel.d.ts.map

package/dist/upload/cancel.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/upload/cancel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/upload/cancel.js"],"names":[],"mappings":"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"}

package/dist/upload/cancel.d.ts

@@ -1,6 +1,56 @@
 import { AccountInfo } from '../auth/account-info.js';
+import { FinishLargeFileResponseBodyError } from '../errors/index.js';
 import { RawClient } from '../raw/index.js';
-import { LargeFileId } from '../types/ids.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */
+export interface CancelLargeFileCleanupFailureEvent {
+    /** Unfinished large file that may remain orphaned. */
+    readonly fileId: LargeFileId;
+    /** Error thrown by `b2_cancel_large_file`. */
+    readonly error: unknown;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'cancel-failed';
+}
+/** Event emitted when cleanup is skipped because finish may have committed. */
+export interface AmbiguousFinishCleanupFailureEvent {
+    /** Large file whose final server-side state is ambiguous. */
+    readonly fileId: LargeFileId;
+    /** Error thrown to the caller with reconciliation metadata. */
+    readonly error: FinishLargeFileResponseBodyError;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'finish-ambiguous';
+}
+/** Event emitted when large-file cleanup fails or is deliberately skipped. */
+export type CleanupFailureEvent = CancelLargeFileCleanupFailureEvent | AmbiguousFinishCleanupFailureEvent;
+/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */
+export type CleanupFailureListener = (event: CleanupFailureEvent) => void;
+/** Shared option for observing large-file cleanup failures or skipped cleanup. */
+export interface CleanupFailureOptions {
+    /**
+     * Callback invoked if best-effort cancellation fails, or if cancellation is
+     * skipped because `b2_finish_large_file` may already have committed.
+     */
+    readonly onCleanupFailure?: CleanupFailureListener;
+}
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+export declare const DEFAULT_CLEANUP_TIMEOUT_MS = 30000;
+/** Context needed to reconcile or cancel an unfinished large file after an error. */
+export interface LargeFileCleanupContext {
+    readonly fileId: LargeFileId;
+    readonly bucketId: BucketId;
+    readonly fileName: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly onCleanupFailure?: CleanupFailureListener | undefined;
+}
+/** Options for applying the shared large-file cleanup policy. */
+export interface LargeFileCleanupPolicyOptions {
+    /**
+     * Whether non-ambiguous failures should cancel the unfinished large file.
+     * Defaults to true. Explicit resume callers can disable this so the SDK does
+     * not cancel a large file that it did not create.
+     */
+    readonly cancelOnError?: boolean;
+}
 /**
  * Cancels an unfinished large file on a best-effort basis. Used at every
  * error-handling boundary in the multipart upload, write-stream, and
@@ -15,9 +65,67 @@ import { LargeFileId } from '../types/ids.js';
  * @param raw - Low-level B2 API client.
  * @param accountInfo - Authorized account state for the API URL + token.
  * @param fileId - The in-progress large file ID to cancel.
+ * @param options - Optional request controls and cleanup-failure observer.
  *
  * @returns A promise that always resolves, regardless of the cancel
  *   call's outcome.
  */
-export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId): Promise<void>;
+export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options?: {
+    readonly signal?: AbortSignal;
+} & CleanupFailureOptions): Promise<void>;
+/**
+ * Returns cleanup request controls with a live timeout signal.
+ *
+ * @param signal - Caller-provided abort signal, if any.
+ * @param timeoutMs - Maximum time to spend waiting for cleanup.
+ *
+ * @returns Request controls with a signal independent of an already-aborted caller signal.
+ */
+export declare function cleanupRequestOptions(signal: AbortSignal | undefined, timeoutMs?: number): {
+    readonly signal: AbortSignal;
+};
+/**
+ * Emits an observable cleanup event when cancellation is deliberately skipped
+ * because `b2_finish_large_file` may already have committed the file.
+ * @param fileId - Large file whose final state is ambiguous.
+ * @param error - Ambiguous finish error that will be thrown to the caller.
+ * @param onCleanupFailure - Optional observer for cleanup-related events.
+ */
+export declare function notifyAmbiguousLargeFileCleanupSkipped(fileId: LargeFileId, error: FinishLargeFileResponseBodyError, onCleanupFailure?: CleanupFailureListener): void;
+/**
+ * Adds high-level reconciliation metadata to an ambiguous finish response-body
+ * error and notifies the cleanup observer that cancellation was skipped.
+ *
+ * @param err - Raw finish response-body error from the low-level client.
+ * @param options - Large-file context used for reconciliation.
+ *
+ * @returns The enriched {@link FinishLargeFileResponseBodyError}.
+ */
+export declare function handleAmbiguousFinishLargeFileResponseBodyError(err: FinishLargeFileResponseBodyError, options: LargeFileCleanupContext): FinishLargeFileResponseBodyError;
+/**
+ * Performs the shared large-file failure policy: ambiguous finish-body errors
+ * are enriched and left uncancelled, while all pre-finish errors trigger
+ * best-effort cancellation.
+ *
+ * @param err - Error from a multipart upload/copy/write-stream path.
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param context - Large file metadata used for cleanup and diagnostics.
+ * @param options - Cleanup policy controls.
+ *
+ * @returns The error that should be surfaced to the caller.
+ */
+export declare function resolveLargeFileErrorAfterCleanup(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<unknown>;
+/**
+ * Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths
+ * that can surface the error directly.
+ * @param err - Error from a multipart upload/copy/write-stream path.
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param context - Large file metadata used for cleanup and diagnostics.
+ * @param options - Cleanup policy controls.
+ *
+ * @throws The resolved large-file error after cleanup policy is applied.
+ */
+export declare function cleanupAfterLargeFileError(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<never>;
 //# sourceMappingURL=cancel.d.ts.map