@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/r2/r2Manager.d.ts

@@ -0,0 +1,228 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+import { R2Credentials } from "./r2Credentials";
+/**
+ * Config for the R2 manager: the shared client config plus the S3-compatible credential pair and
+ * the bucket it targets. R2 signs presigned URLs with the S3 keys, not the CF API token — both
+ * come from config (no environment coupling).
+ */
+export interface R2ManagerConfig extends CloudflareManagerConfig, R2Credentials {
+    /** The R2 bucket all object operations target. */
+    bucketName: string;
+}
+/** How long a presigned URL stays valid. Shared by every presign method so the option reads the same. */
+export interface PresignOptions {
+    /** Lifetime in seconds. Defaults to one hour — long enough for a large upload, short enough to leak little. */
+    expiresIn?: number;
+}
+/** Presign options for one multipart part, which may additionally pin the part's exact byte count. */
+export interface PresignPartOptions extends PresignOptions {
+    /**
+     * Exact byte count the client must send. Omitted by default — see {@link CloudflareR2Manager.presignUploadPart}
+     * for why signing a part length is opt-in where signing a whole-object length is not.
+     */
+    contentLength?: number;
+}
+/** What emptying a bucket reclaimed — the counts a teardown reports and an audit event records. */
+export interface R2BucketDrain {
+    /** How many stored objects were deleted. */
+    objectsDeleted: number;
+    /** How many abandoned multipart uploads were aborted before the objects were drained. */
+    uploadsAborted: number;
+}
+/** Which slice of a bucket's keys to list, and how many to return. */
+export interface ListObjectsOptions {
+    /** Only return keys starting with this prefix. Omitted lists the whole bucket. */
+    prefix?: string;
+    /** Continuation cursor from a previous page's `cursor`. Omitted starts at the beginning. */
+    cursor?: string;
+    /** Page size. R2 caps this at 1000 and returns a `cursor` when more remain. */
+    maxKeys?: number;
+}
+/** One completed part, as the client reports it back after a presigned `PUT` to a part URL. */
+export interface CompletedPart {
+    /** The part's 1-based index, matching the `partNumber` the part URL was presigned for. */
+    partNumber: number;
+    /** The `ETag` response header R2 returned for that part, verbatim — quotes included. */
+    etag: string;
+}
+/** An object's metadata as R2 reports it, without fetching the body. */
+export declare const R2ObjectHead: z.ZodObject<{
+    size: z.ZodNumber;
+    etag: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    uploaded: z.ZodOptional<z.ZodDate>;
+}, z.core.$strip>;
+export type R2ObjectHead = z.output<typeof R2ObjectHead>;
+/** One part already uploaded against an in-flight multipart upload. */
+export declare const R2UploadedPart: z.ZodObject<{
+    partNumber: z.ZodNumber;
+    etag: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+export type R2UploadedPart = z.output<typeof R2UploadedPart>;
+/** One page of object keys from a bucket listing. */
+export declare const R2ObjectListing: z.ZodObject<{
+    keys: z.ZodArray<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type R2ObjectListing = z.output<typeof R2ObjectListing>;
+/**
+ * A multipart upload that was started and never completed or aborted.
+ *
+ * Abandoned uploads are invisible and not free — R2 stores and bills their parts, and a bucket holding
+ * one cannot be deleted at all.
+ */
+export declare const R2PendingUpload: z.ZodObject<{
+    key: z.ZodString;
+    uploadId: z.ZodString;
+    initiated: z.ZodOptional<z.ZodDate>;
+}, z.core.$strip>;
+export type R2PendingUpload = z.output<typeof R2PendingUpload>;
+/**
+ * Out-of-Worker Cloudflare R2 access over the S3 protocol: presigned URLs the client uses to move
+ * bytes directly, plus the server-side object and multipart operations that surround them. Inside a
+ * Worker you use the R2 binding for object reads and writes; this manager is the REST/S3 counterpart,
+ * addressed by bucket name, and the only path to *presigned* multipart — the binding's multipart API
+ * streams bytes through the Worker, which defeats the point.
+ *
+ * Only `uploadPart` is presigned. Create, complete, abort, list, head, copy and delete are server-side
+ * calls the holder of the credentials makes directly — presigning them would hand a client authority
+ * it has no reason to hold.
+ */
+export declare class CloudflareR2Manager extends CloudflareManager {
+    private readonly bucketName;
+    private readonly accessKeyId;
+    private readonly secretAccessKey;
+    private s3Client;
+    constructor(config: R2ManagerConfig);
+    /** The S3-compatible client for R2, lazily created and cached for the manager's lifetime. */
+    private getS3Client;
+    /**
+     * Presign a PUT URL for uploading one whole object. Valid for one hour unless `expiresIn` says otherwise.
+     *
+     * **`ContentLength` is signed; `ContentType` is not.** The length lands in `X-Amz-SignedHeaders`, so
+     * the client must send exactly that byte count — the signature is the enforcement, and that is
+     * deliberate for a whole-object upload: the caller already knows the size (it is what a quota check
+     * was run against), so signing it stops a client from spending more storage than it was granted.
+     *
+     * The type cannot be enforced this way at all. `@aws-sdk/s3-request-presigner` marks `content-type`
+     * unsignable before signing (`prepareRequest` → `unsignableHeaders.add("content-type")`), because a
+     * browser rewrites the header on a form or an XHR upload and a signature over it would break every
+     * such client. It therefore never reaches `X-Amz-SignedHeaders`, and R2 stores whatever type the
+     * client's PUT actually carries. `contentType` here is documentation of intent, not a constraint —
+     * unlike {@link createMultipartUpload}, which is a server-side call and does pin the type it sends.
+     * Anything keyed on an object's type must read it back with {@link headObject} after the upload,
+     * never from what the caller declared.
+     */
+    createUploadUrl(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
+    /** Presign a GET URL for downloading one object. Valid for one hour unless `expiresIn` says otherwise. */
+    createDownloadUrl(key: string, options?: PresignOptions): Promise<string>;
+    /**
+     * Open a multipart upload and return its `uploadId`. Server-side — no presigning. The id is the
+     * handle every later part, completion, abort and resume is addressed by, so a caller that means to
+     * support resuming must persist it.
+     *
+     * R2's multipart shape: at most 10,000 parts, every part but the last at least 5 MiB, each at most
+     * 5 GiB. Nothing here enforces that — R2 rejects a violating `complete`, and the part-size policy
+     * belongs to the layer that chose the part size.
+     */
+    createMultipartUpload(key: string, contentType: string): Promise<string>;
+    /**
+     * Presign a PUT URL for one part of a multipart upload. This is the only multipart step a client
+     * ever touches, and therefore the only one presigned.
+     *
+     * **`ContentLength` is omitted by default**, unlike `createUploadUrl`. A signed length forces the
+     * client to send exactly that many bytes, and for a multipart upload the last part's length is
+     * `total - partSize * (n - 1)` — a different number from every other part. Signing it would mean
+     * either knowing the total size at mint time (a resumable or streaming upload does not) or minting
+     * the final part's URL through a separate code path. Neither earns its complexity: R2 already
+     * enforces the 5 MiB floor and 5 GiB ceiling per part, and the whole-object size is enforced where
+     * it matters — at `completeMultipartUpload`, against the parts R2 actually stored. A caller that
+     * does know the exact part size may still pin it by passing `contentLength`.
+     */
+    presignUploadPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
+    /**
+     * Assemble the uploaded parts into one object. Server-side — the client only ever reports the
+     * `{ partNumber, etag }` pairs its part PUTs returned.
+     *
+     * Parts are sorted ascending before the call: S3 rejects an out-of-order part list, and the order a
+     * client finishes concurrent part uploads in is not the order they belong in. ETags pass through
+     * verbatim — they are opaque to us, and R2 compares them byte for byte.
+     */
+    completeMultipartUpload(key: string, uploadId: string, parts: readonly CompletedPart[]): Promise<void>;
+    /**
+     * Discard an in-flight multipart upload and the parts already stored under it. Idempotent — an
+     * upload id R2 has already forgotten is not an error, so a sweep or a retried teardown can re-run.
+     */
+    abortMultipartUpload(key: string, uploadId: string): Promise<void>;
+    /**
+     * List the parts already stored against an in-flight upload, ascending. This is what makes an upload
+     * resumable: a client that lost its progress asks which parts landed and re-sends only the rest.
+     *
+     * Pagination is drained here rather than surfaced. An upload holds at most 10,000 parts and a page
+     * holds 1000, so the loop is bounded at ten calls — a cursor would be API surface for no gain.
+     */
+    listParts(key: string, uploadId: string): Promise<R2UploadedPart[]>;
+    /**
+     * Read one object's metadata without transferring its body. Returns `null` when the object is
+     * absent — a missing object is an answer, not a failure, and the caller decides what it means.
+     */
+    headObject(key: string): Promise<R2ObjectHead | null>;
+    /**
+     * Every multipart upload started in this bucket and never completed or aborted.
+     *
+     * Abandoned uploads are invisible and not free: R2 stores and bills the parts, and a bucket holding one
+     * cannot be deleted at all. Nothing else can find them — `listObjects` does not show an upload that never
+     * assembled, and `listParts` needs the `uploadId` you are trying to discover. So this is the only route to
+     * reclaiming a bucket, and the only way an orphan sweep can see the cost it is meant to reclaim.
+     *
+     * Fully drained rather than cursor-paged: a caller wants all of them, and the count is bounded by how many
+     * uploads were abandoned rather than by how much data the bucket holds.
+     */
+    listMultipartUploads(prefix?: string): Promise<R2PendingUpload[]>;
+    /**
+     * List one page of object keys. Pagination is caller-driven: pass the returned `cursor` back to get
+     * the next page, and stop when it is absent. Unlike `listParts` a bucket has no bounded size, so
+     * draining it here would be an unbounded loop with no way for the caller to stop early.
+     */
+    listObjects(options?: ListObjectsOptions): Promise<R2ObjectListing>;
+    /**
+     * Copy an object within this bucket, server-side — the bytes never leave R2.
+     *
+     * `CopySource` is `/<bucket>/<key>` with the key percent-encoded per path segment. The SDK does not
+     * encode it, and a key containing a space or `?` produces a malformed source header otherwise;
+     * encoding whole would destroy the `/` separators a nested key depends on.
+     */
+    copyObject(sourceKey: string, destKey: string): Promise<void>;
+    /**
+     * Delete one object. Idempotent by protocol — S3 answers a delete of an absent key with a success,
+     * so teardown and orphan sweeps can re-run safely.
+     */
+    deleteObject(key: string): Promise<void>;
+    /**
+     * Delete every object in this bucket and abort every multipart upload still in flight.
+     *
+     * **R2 refuses to delete a bucket that is not empty**, so this is the step that has to run before
+     * `CloudflareR2Provisioner.deleteBucket` — and it is the reason a teardown needs the S3 key pair at
+     * all: the CF API has no object plane, so nothing but this protocol can empty a bucket.
+     *
+     * Two different things hold a bucket, and only one of them is visible. Stored objects show up in a
+     * listing; the parts of an upload that was started and never completed or aborted do not, and they
+     * block the delete just the same. So the aborts go first: draining the keys of a bucket that still
+     * carries a dangling upload leaves it empty-looking and undeletable, which is the confusing failure.
+     *
+     * **Destructive and unrecoverable**, and it does not ask — the caller owns the confirmation. Idempotent:
+     * an already-empty bucket is a no-op reporting zeroes, so a retried teardown is safe.
+     */
+    emptyBucket(): Promise<R2BucketDrain>;
+    getServiceType(): string;
+    /**
+     * Prove access by reading the bucket record over the CF API (token + account + bucket existence),
+     * not merely that an S3 client could be built. Never throws.
+     */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=r2Manager.d.ts.map

package/dist/r2/r2Manager.d.ts.map

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

package/dist/r2/r2Manager.js

@@ -0,0 +1,407 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { R2Credentials } from "./r2Credentials.js";
+import { z } from "zod";
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CopyObjectCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListMultipartUploadsCommand, ListObjectsV2Command, ListPartsCommand, PutObjectCommand, S3Client, UploadPartCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+//#region src/r2/r2Manager.ts
+/** How long a presigned R2 URL stays valid, in seconds (1 hour), when the caller names no lifetime. */
+const PRESIGN_EXPIRY_SECONDS = 3600;
+/** How many parts one `ListParts` page returns. S3's own cap; the drain loop below relies on it. */
+const LIST_PARTS_PAGE_SIZE = 1e3;
+/** An object's metadata as R2 reports it, without fetching the body. */
+const R2ObjectHead = z.object({
+	size: z.number().int().nonnegative().describe("The object's size in bytes."),
+	etag: z.string().min(1).describe("R2's entity tag for this object version, verbatim — quotes included."),
+	contentType: z.string().min(1).optional().describe("The stored `Content-Type`. Absent when the object was written without one."),
+	uploaded: z.date().optional().describe("When R2 last wrote the object. Absent when R2 reports no timestamp.")
+}).describe("Metadata for one R2 object, read with a HEAD — no body transfer.");
+/** One part already uploaded against an in-flight multipart upload. */
+const R2UploadedPart = z.object({
+	partNumber: z.number().int().min(1).describe("The part's 1-based index within the upload."),
+	etag: z.string().min(1).describe("The part's entity tag, verbatim. Pass it back unchanged to complete the upload."),
+	size: z.number().int().nonnegative().describe("The part's size in bytes, as R2 stored it.")
+}).describe("One uploaded part of a multipart upload — the unit a resumed upload skips re-sending.");
+/** One page of object keys from a bucket listing. */
+const R2ObjectListing = z.object({
+	keys: z.array(z.string().min(1)).describe("The object keys in this page, in R2's lexicographic order."),
+	cursor: z.string().min(1).optional().describe("Continuation cursor for the next page. Absent means this page was the last.")
+}).describe("One page of an R2 bucket listing. Pagination is caller-driven — pass `cursor` back to advance.");
+/**
+* A multipart upload that was started and never completed or aborted.
+*
+* Abandoned uploads are invisible and not free — R2 stores and bills their parts, and a bucket holding
+* one cannot be deleted at all.
+*/
+const R2PendingUpload = z.object({
+	key: z.string().min(1).describe("The object key this upload would have assembled into."),
+	uploadId: z.string().min(1).describe("The id `abortMultipartUpload` needs in order to reclaim it."),
+	initiated: z.date().optional().describe("When the upload was started, for age-based reclamation.")
+}).describe("A multipart upload started and never completed or aborted — billed, invisible, and blocking.");
+/**
+* Whether a thrown S3 error is a 404.
+*
+* `isNotFoundError` from `client/errors` reads `error.status`, which the `cloudflare` SDK sets and the
+* AWS SDK does not — the AWS SDK reports the code on `$metadata.httpStatusCode` and names the shape
+* `NotFound` (HEAD) or `NoSuchKey` (GET). So the S3 protocol needs its own check; sharing one would
+* silently classify every missing object as a request failure.
+*/
+function isS3NotFound(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const name = error.name;
+	if (name === "NotFound" || name === "NoSuchKey") return true;
+	return error.$metadata?.httpStatusCode === 404;
+}
+/**
+* Out-of-Worker Cloudflare R2 access over the S3 protocol: presigned URLs the client uses to move
+* bytes directly, plus the server-side object and multipart operations that surround them. Inside a
+* Worker you use the R2 binding for object reads and writes; this manager is the REST/S3 counterpart,
+* addressed by bucket name, and the only path to *presigned* multipart — the binding's multipart API
+* streams bytes through the Worker, which defeats the point.
+*
+* Only `uploadPart` is presigned. Create, complete, abort, list, head, copy and delete are server-side
+* calls the holder of the credentials makes directly — presigning them would hand a client authority
+* it has no reason to hold.
+*/
+var CloudflareR2Manager = class extends CloudflareManager {
+	bucketName;
+	accessKeyId;
+	secretAccessKey;
+	s3Client = null;
+	constructor(config) {
+		super(config);
+		if (!config.bucketName) throw new CloudflareNotConfiguredError({ detail: "Missing bucketName for R2 access." });
+		const credentials = R2Credentials.safeParse(config);
+		if (!credentials.success) throw new CloudflareNotConfiguredError({ detail: `Invalid R2 credentials: ${credentials.error.message}` });
+		this.bucketName = config.bucketName;
+		this.accessKeyId = config.accessKeyId;
+		this.secretAccessKey = config.secretAccessKey;
+	}
+	/** The S3-compatible client for R2, lazily created and cached for the manager's lifetime. */
+	getS3Client() {
+		if (!this.s3Client) this.s3Client = new S3Client({
+			region: "auto",
+			endpoint: `https://${this.accountId}.r2.cloudflarestorage.com`,
+			credentials: {
+				accessKeyId: this.accessKeyId,
+				secretAccessKey: this.secretAccessKey
+			}
+		});
+		return this.s3Client;
+	}
+	/**
+	* Presign a PUT URL for uploading one whole object. Valid for one hour unless `expiresIn` says otherwise.
+	*
+	* **`ContentLength` is signed; `ContentType` is not.** The length lands in `X-Amz-SignedHeaders`, so
+	* the client must send exactly that byte count — the signature is the enforcement, and that is
+	* deliberate for a whole-object upload: the caller already knows the size (it is what a quota check
+	* was run against), so signing it stops a client from spending more storage than it was granted.
+	*
+	* The type cannot be enforced this way at all. `@aws-sdk/s3-request-presigner` marks `content-type`
+	* unsignable before signing (`prepareRequest` → `unsignableHeaders.add("content-type")`), because a
+	* browser rewrites the header on a form or an XHR upload and a signature over it would break every
+	* such client. It therefore never reaches `X-Amz-SignedHeaders`, and R2 stores whatever type the
+	* client's PUT actually carries. `contentType` here is documentation of intent, not a constraint —
+	* unlike {@link createMultipartUpload}, which is a server-side call and does pin the type it sends.
+	* Anything keyed on an object's type must read it back with {@link headObject} after the upload,
+	* never from what the caller declared.
+	*/
+	async createUploadUrl(key, contentType, contentLength, options = {}) {
+		return cloudflareRequest(`R2 presign upload for '${key}'`, () => {
+			const command = new PutObjectCommand({
+				Bucket: this.bucketName,
+				Key: key,
+				ContentType: contentType,
+				ContentLength: contentLength
+			});
+			return getSignedUrl(this.getS3Client(), command, { expiresIn: options.expiresIn ?? PRESIGN_EXPIRY_SECONDS });
+		});
+	}
+	/** Presign a GET URL for downloading one object. Valid for one hour unless `expiresIn` says otherwise. */
+	async createDownloadUrl(key, options = {}) {
+		return cloudflareRequest(`R2 presign download for '${key}'`, () => {
+			const command = new GetObjectCommand({
+				Bucket: this.bucketName,
+				Key: key
+			});
+			return getSignedUrl(this.getS3Client(), command, { expiresIn: options.expiresIn ?? PRESIGN_EXPIRY_SECONDS });
+		});
+	}
+	/**
+	* Open a multipart upload and return its `uploadId`. Server-side — no presigning. The id is the
+	* handle every later part, completion, abort and resume is addressed by, so a caller that means to
+	* support resuming must persist it.
+	*
+	* R2's multipart shape: at most 10,000 parts, every part but the last at least 5 MiB, each at most
+	* 5 GiB. Nothing here enforces that — R2 rejects a violating `complete`, and the part-size policy
+	* belongs to the layer that chose the part size.
+	*/
+	async createMultipartUpload(key, contentType) {
+		return cloudflareRequest(`R2 create multipart upload for '${key}'`, async () => {
+			const response = await this.getS3Client().send(new CreateMultipartUploadCommand({
+				Bucket: this.bucketName,
+				Key: key,
+				ContentType: contentType
+			}));
+			return decodeResponse(z.string().min(1).describe("The multipart upload id."), response.UploadId, `R2 create multipart upload for '${key}'`);
+		});
+	}
+	/**
+	* Presign a PUT URL for one part of a multipart upload. This is the only multipart step a client
+	* ever touches, and therefore the only one presigned.
+	*
+	* **`ContentLength` is omitted by default**, unlike `createUploadUrl`. A signed length forces the
+	* client to send exactly that many bytes, and for a multipart upload the last part's length is
+	* `total - partSize * (n - 1)` — a different number from every other part. Signing it would mean
+	* either knowing the total size at mint time (a resumable or streaming upload does not) or minting
+	* the final part's URL through a separate code path. Neither earns its complexity: R2 already
+	* enforces the 5 MiB floor and 5 GiB ceiling per part, and the whole-object size is enforced where
+	* it matters — at `completeMultipartUpload`, against the parts R2 actually stored. A caller that
+	* does know the exact part size may still pin it by passing `contentLength`.
+	*/
+	async presignUploadPart(key, uploadId, partNumber, options = {}) {
+		return cloudflareRequest(`R2 presign part ${partNumber} for '${key}'`, () => {
+			const command = new UploadPartCommand({
+				Bucket: this.bucketName,
+				Key: key,
+				UploadId: uploadId,
+				PartNumber: partNumber,
+				...options.contentLength === void 0 ? {} : { ContentLength: options.contentLength }
+			});
+			return getSignedUrl(this.getS3Client(), command, { expiresIn: options.expiresIn ?? PRESIGN_EXPIRY_SECONDS });
+		});
+	}
+	/**
+	* Assemble the uploaded parts into one object. Server-side — the client only ever reports the
+	* `{ partNumber, etag }` pairs its part PUTs returned.
+	*
+	* Parts are sorted ascending before the call: S3 rejects an out-of-order part list, and the order a
+	* client finishes concurrent part uploads in is not the order they belong in. ETags pass through
+	* verbatim — they are opaque to us, and R2 compares them byte for byte.
+	*/
+	async completeMultipartUpload(key, uploadId, parts) {
+		await cloudflareRequest(`R2 complete multipart upload for '${key}'`, async () => {
+			const ordered = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+			await this.getS3Client().send(new CompleteMultipartUploadCommand({
+				Bucket: this.bucketName,
+				Key: key,
+				UploadId: uploadId,
+				MultipartUpload: { Parts: ordered.map((p) => ({
+					PartNumber: p.partNumber,
+					ETag: p.etag
+				})) }
+			}));
+		});
+	}
+	/**
+	* Discard an in-flight multipart upload and the parts already stored under it. Idempotent — an
+	* upload id R2 has already forgotten is not an error, so a sweep or a retried teardown can re-run.
+	*/
+	async abortMultipartUpload(key, uploadId) {
+		await cloudflareRequest(`R2 abort multipart upload for '${key}'`, async () => {
+			try {
+				await this.getS3Client().send(new AbortMultipartUploadCommand({
+					Bucket: this.bucketName,
+					Key: key,
+					UploadId: uploadId
+				}));
+			} catch (error) {
+				if (isS3NotFound(error)) return;
+				throw error;
+			}
+		});
+	}
+	/**
+	* List the parts already stored against an in-flight upload, ascending. This is what makes an upload
+	* resumable: a client that lost its progress asks which parts landed and re-sends only the rest.
+	*
+	* Pagination is drained here rather than surfaced. An upload holds at most 10,000 parts and a page
+	* holds 1000, so the loop is bounded at ten calls — a cursor would be API surface for no gain.
+	*/
+	async listParts(key, uploadId) {
+		return cloudflareRequest(`R2 list parts for '${key}'`, async () => {
+			const parts = [];
+			let marker;
+			do {
+				const response = await this.getS3Client().send(new ListPartsCommand({
+					Bucket: this.bucketName,
+					Key: key,
+					UploadId: uploadId,
+					MaxParts: LIST_PARTS_PAGE_SIZE,
+					PartNumberMarker: marker
+				}));
+				for (const part of response.Parts ?? []) parts.push(decodeResponse(R2UploadedPart, {
+					partNumber: part.PartNumber,
+					etag: part.ETag,
+					size: part.Size
+				}, `R2 list parts for '${key}'`));
+				marker = response.IsTruncated ? response.NextPartNumberMarker : void 0;
+			} while (marker);
+			return parts.sort((a, b) => a.partNumber - b.partNumber);
+		});
+	}
+	/**
+	* Read one object's metadata without transferring its body. Returns `null` when the object is
+	* absent — a missing object is an answer, not a failure, and the caller decides what it means.
+	*/
+	async headObject(key) {
+		return cloudflareRequest(`R2 head object '${key}'`, async () => {
+			try {
+				const response = await this.getS3Client().send(new HeadObjectCommand({
+					Bucket: this.bucketName,
+					Key: key
+				}));
+				return decodeResponse(R2ObjectHead, {
+					size: response.ContentLength,
+					etag: response.ETag,
+					contentType: response.ContentType,
+					uploaded: response.LastModified
+				}, `R2 head object '${key}'`);
+			} catch (error) {
+				if (isS3NotFound(error)) return null;
+				throw error;
+			}
+		});
+	}
+	/**
+	* Every multipart upload started in this bucket and never completed or aborted.
+	*
+	* Abandoned uploads are invisible and not free: R2 stores and bills the parts, and a bucket holding one
+	* cannot be deleted at all. Nothing else can find them — `listObjects` does not show an upload that never
+	* assembled, and `listParts` needs the `uploadId` you are trying to discover. So this is the only route to
+	* reclaiming a bucket, and the only way an orphan sweep can see the cost it is meant to reclaim.
+	*
+	* Fully drained rather than cursor-paged: a caller wants all of them, and the count is bounded by how many
+	* uploads were abandoned rather than by how much data the bucket holds.
+	*/
+	async listMultipartUploads(prefix) {
+		return cloudflareRequest("R2 list multipart uploads", async () => {
+			const found = [];
+			let keyMarker;
+			let uploadIdMarker;
+			do {
+				const response = await this.getS3Client().send(new ListMultipartUploadsCommand({
+					Bucket: this.bucketName,
+					Prefix: prefix,
+					KeyMarker: keyMarker,
+					UploadIdMarker: uploadIdMarker
+				}));
+				for (const upload of response.Uploads ?? []) {
+					if (!upload.Key || !upload.UploadId) continue;
+					found.push(decodeResponse(R2PendingUpload, {
+						key: upload.Key,
+						uploadId: upload.UploadId,
+						initiated: upload.Initiated
+					}, "R2 pending multipart upload"));
+				}
+				keyMarker = response.IsTruncated ? response.NextKeyMarker : void 0;
+				uploadIdMarker = response.IsTruncated ? response.NextUploadIdMarker : void 0;
+			} while (keyMarker || uploadIdMarker);
+			return found;
+		});
+	}
+	/**
+	* List one page of object keys. Pagination is caller-driven: pass the returned `cursor` back to get
+	* the next page, and stop when it is absent. Unlike `listParts` a bucket has no bounded size, so
+	* draining it here would be an unbounded loop with no way for the caller to stop early.
+	*/
+	async listObjects(options = {}) {
+		return cloudflareRequest("R2 list objects", async () => {
+			const response = await this.getS3Client().send(new ListObjectsV2Command({
+				Bucket: this.bucketName,
+				Prefix: options.prefix,
+				ContinuationToken: options.cursor,
+				MaxKeys: options.maxKeys
+			}));
+			const keys = (response.Contents ?? []).map((entry) => entry.Key).filter((key) => Boolean(key));
+			return decodeResponse(R2ObjectListing, {
+				keys,
+				cursor: response.IsTruncated ? response.NextContinuationToken : void 0
+			}, "R2 list objects");
+		});
+	}
+	/**
+	* Copy an object within this bucket, server-side — the bytes never leave R2.
+	*
+	* `CopySource` is `/<bucket>/<key>` with the key percent-encoded per path segment. The SDK does not
+	* encode it, and a key containing a space or `?` produces a malformed source header otherwise;
+	* encoding whole would destroy the `/` separators a nested key depends on.
+	*/
+	async copyObject(sourceKey, destKey) {
+		await cloudflareRequest(`R2 copy '${sourceKey}' to '${destKey}'`, async () => {
+			const source = `/${this.bucketName}/${sourceKey.split("/").map(encodeURIComponent).join("/")}`;
+			await this.getS3Client().send(new CopyObjectCommand({
+				Bucket: this.bucketName,
+				Key: destKey,
+				CopySource: source
+			}));
+		});
+	}
+	/**
+	* Delete one object. Idempotent by protocol — S3 answers a delete of an absent key with a success,
+	* so teardown and orphan sweeps can re-run safely.
+	*/
+	async deleteObject(key) {
+		await cloudflareRequest(`R2 delete object '${key}'`, async () => {
+			await this.getS3Client().send(new DeleteObjectCommand({
+				Bucket: this.bucketName,
+				Key: key
+			}));
+		});
+	}
+	/**
+	* Delete every object in this bucket and abort every multipart upload still in flight.
+	*
+	* **R2 refuses to delete a bucket that is not empty**, so this is the step that has to run before
+	* `CloudflareR2Provisioner.deleteBucket` — and it is the reason a teardown needs the S3 key pair at
+	* all: the CF API has no object plane, so nothing but this protocol can empty a bucket.
+	*
+	* Two different things hold a bucket, and only one of them is visible. Stored objects show up in a
+	* listing; the parts of an upload that was started and never completed or aborted do not, and they
+	* block the delete just the same. So the aborts go first: draining the keys of a bucket that still
+	* carries a dangling upload leaves it empty-looking and undeletable, which is the confusing failure.
+	*
+	* **Destructive and unrecoverable**, and it does not ask — the caller owns the confirmation. Idempotent:
+	* an already-empty bucket is a no-op reporting zeroes, so a retried teardown is safe.
+	*/
+	async emptyBucket() {
+		let uploadsAborted = 0;
+		for (const pending of await this.listMultipartUploads()) {
+			await this.abortMultipartUpload(pending.key, pending.uploadId);
+			uploadsAborted += 1;
+		}
+		let objectsDeleted = 0;
+		let cursor;
+		do {
+			const page = await this.listObjects({ cursor });
+			for (const key of page.keys) {
+				await this.deleteObject(key);
+				objectsDeleted += 1;
+			}
+			cursor = page.cursor;
+		} while (cursor);
+		return {
+			objectsDeleted,
+			uploadsAborted
+		};
+	}
+	getServiceType() {
+		return "Cloudflare R2";
+	}
+	/**
+	* Prove access by reading the bucket record over the CF API (token + account + bucket existence),
+	* not merely that an S3 client could be built. Never throws.
+	*/
+	async validateServiceAccess() {
+		try {
+			await this.getClient().r2.buckets.get(this.bucketName, { account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareR2Manager, R2ObjectHead, R2ObjectListing, R2PendingUpload, R2UploadedPart };