@agentuity/storage 3.0.0-alpha.7

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared types for `@agentuity/storage`.
+ *
+ * Both the Bun-backed and Node-backed implementations conform to the
+ * `S3ClientLike` interface. Callers should program against this surface
+ * rather than backend-specific shapes, so that swapping the backend (or
+ * letting the package conditionally pick one) is transparent.
+ */
+/** Bucket connection configuration. */
+export interface BucketConfig {
+    /**
+     * Bucket-specific endpoint, e.g. `my-bucket.agentuity.run`. May be
+     * provided with or without a scheme; missing schemes default to
+     * `https://`.
+     */
+    endpoint: string;
+    /** S3 access key ID. */
+    access_key: string;
+    /** S3 secret access key. */
+    secret_key: string;
+    /** Optional region. Defaults to `'auto'` when omitted or null. */
+    region?: string | null;
+}
+/** Options for `list()`. */
+export interface S3ListOptions {
+    /** Only return objects whose key starts with this prefix. */
+    prefix?: string;
+    /** Maximum number of objects to return in this response. */
+    maxKeys?: number;
+}
+/** A single object entry in a list result. */
+export interface S3Object {
+    key: string;
+    size: number;
+    /**
+     * ISO 8601 timestamp string. Both backends normalize to a string so
+     * downstream code does not have to branch on `Date | string`.
+     */
+    lastModified: string;
+    etag?: string;
+}
+/** Result of a `list()` call. */
+export interface S3ListResult {
+    contents: S3Object[];
+    isTruncated: boolean;
+}
+/** Result of a `stat()` (HEAD) call. */
+export interface S3StatResult {
+    size: number;
+    /** Content-Type of the object, when present. */
+    type?: string;
+    lastModified?: Date;
+    etag?: string;
+}
+/** Options for `write()`. */
+export interface S3WriteOptions {
+    /** Content-Type to record on the object. */
+    type?: string;
+}
+/**
+ * Anything we can upload as an object body.
+ *
+ * The Bun backend forwards these directly to `Bun.S3Client.write`, which
+ * accepts the same shapes. The Node backend converts them to formats
+ * accepted by `@aws-sdk/client-s3`'s `PutObjectCommand`.
+ */
+export type S3Body = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+/** A handle to an object on the server. Returned by `client.file(key)`. */
+export interface S3FileLike {
+    /** Read the entire object into memory as an `ArrayBuffer`. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Read the entire object as UTF-8 text. */
+    text(): Promise<string>;
+    /** Get a Web `ReadableStream` for the object body. */
+    stream(): ReadableStream<Uint8Array>;
+}
+/**
+ * Unified S3 client interface.
+ *
+ * Implemented by both `@agentuity/storage/bun` and
+ * `@agentuity/storage/node`. The surface mirrors `Bun.S3Client` so the
+ * Bun backend can be a thin wrapper, and the Node backend translates
+ * to `@aws-sdk/client-s3` commands.
+ */
+export interface S3ClientLike {
+    /**
+     * List objects in the bucket. Pass `null` (or omit) to list from the
+     * root with no prefix; otherwise narrow with `{ prefix, maxKeys }`.
+     */
+    list(opts?: S3ListOptions | null): Promise<S3ListResult>;
+    /** Get object metadata (HEAD). */
+    stat(key: string): Promise<S3StatResult>;
+    /** Get a handle to an object for streaming reads. */
+    file(key: string): S3FileLike;
+    /**
+     * Upload an object. Returns the number of bytes written.
+     *
+     * For streaming bodies, the byte count is measured by a counting
+     * pass-through stream so that the return value is always accurate.
+     */
+    write(key: string, body: S3Body, opts?: S3WriteOptions): Promise<number>;
+    /** Delete an object. No-op (does not throw) if the object is absent. */
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC9B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAE3F,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IAC1B,8DAA8D;IAC9D,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,4CAA4C;IAC5C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,sDAAsD;IACtD,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzD,kCAAkC;IAClC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzC,qDAAqD;IACrD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,wEAAwE;IACxE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types for `@agentuity/storage`.
+ *
+ * Both the Bun-backed and Node-backed implementations conform to the
+ * `S3ClientLike` interface. Callers should program against this surface
+ * rather than backend-specific shapes, so that swapping the backend (or
+ * letting the package conditionally pick one) is transparent.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "@agentuity/storage",
+	"version": "3.0.0-alpha.7",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"description": "Dual-runtime S3 client for Agentuity storage buckets. Bun backend uses Bun.S3Client; Node backend uses @aws-sdk/client-s3.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"src",
+		"dist"
+	],
+	"exports": {
+		".": {
+			"bun": {
+				"types": "./dist/bun.d.ts",
+				"import": "./dist/bun.js"
+			},
+			"node": {
+				"types": "./dist/node.d.ts",
+				"import": "./dist/node.js"
+			},
+			"default": {
+				"types": "./dist/node.d.ts",
+				"import": "./dist/node.js"
+			}
+		},
+		"./bun": {
+			"types": "./dist/bun.d.ts",
+			"import": "./dist/bun.js"
+		},
+		"./node": {
+			"types": "./dist/node.d.ts",
+			"import": "./dist/node.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts",
+			"import": "./dist/types.js"
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build --force",
+		"typecheck": "bunx tsc --noEmit",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {
+		"@aws-sdk/client-s3": "^3.700.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agentuity/sdk.git",
+		"directory": "packages/storage"
+	}
+}

package/src/bun.ts

@@ -0,0 +1,109 @@
+/**
+ * Bun-backed implementation of `S3ClientLike`.
+ *
+ * Thin wrapper around `Bun.S3Client`. Only resolvable when the consumer
+ * is running under Bun — `package.json`'s `"bun"` exports condition
+ * routes here automatically; explicit `@agentuity/storage/bun` imports
+ * also land here.
+ *
+ * Falling through to this module under Node will fail at import time
+ * because `import { S3Client } from 'bun'` is not satisfiable there.
+ * That is intentional and matches the contract of the `bun` exports
+ * condition.
+ */
+
+import { S3Client } from 'bun';
+import type {
+	BucketConfig,
+	S3Body,
+	S3ClientLike,
+	S3FileLike,
+	S3ListOptions,
+	S3ListResult,
+	S3StatResult,
+	S3WriteOptions,
+} from './types.ts';
+
+export type { BucketConfig, S3ClientLike } from './types.ts';
+
+/**
+ * Create an S3 client backed by `Bun.S3Client`.
+ *
+ * Endpoints are bucket-scoped (virtual-hosted-style), so we do not pass
+ * a bucket parameter on the client itself; the hostname routes to the
+ * correct bucket.
+ */
+export function createS3Client(bucket: BucketConfig): S3ClientLike {
+	const endpoint = bucket.endpoint.startsWith('http')
+		? bucket.endpoint
+		: `https://${bucket.endpoint}`;
+
+	const client = new S3Client({
+		endpoint,
+		accessKeyId: bucket.access_key,
+		secretAccessKey: bucket.secret_key,
+		region: bucket.region || 'auto',
+		virtualHostedStyle: true,
+	});
+
+	return {
+		async list(opts?: S3ListOptions | null): Promise<S3ListResult> {
+			// `Bun.S3Client.list` accepts `null` for "no filter".
+			const out = (await client.list(opts ?? (null as any))) as {
+				contents?: Array<{
+					key: string;
+					size?: number;
+					lastModified?: string | Date;
+					etag?: string;
+				}>;
+				isTruncated?: boolean;
+			};
+			return {
+				contents: (out.contents ?? []).map((o) => ({
+					key: o.key,
+					size: o.size ?? 0,
+					lastModified: normalizeTimestamp(o.lastModified),
+					etag: o.etag,
+				})),
+				isTruncated: out.isTruncated ?? false,
+			};
+		},
+
+		async stat(key: string): Promise<S3StatResult> {
+			const out = await client.stat(key);
+			return {
+				size: out.size ?? 0,
+				type: out.type,
+				lastModified: out.lastModified,
+				// Bun's stat returns the etag with mixed casing across versions.
+				etag: (out as any).etag ?? (out as any).ETag,
+			};
+		},
+
+		file(key: string): S3FileLike {
+			const f = client.file(key);
+			return {
+				arrayBuffer: () => f.arrayBuffer(),
+				text: () => f.text(),
+				stream: () => f.stream() as ReadableStream<Uint8Array>,
+			};
+		},
+
+		async write(key: string, body: S3Body, opts?: S3WriteOptions): Promise<number> {
+			// `Bun.S3Client.write` accepts string, Uint8Array, ArrayBuffer,
+			// Blob, ReadableStream, or Response. We accept the same shapes
+			// minus Response (callers should pass the underlying stream).
+			return client.write(key, body as any, opts);
+		},
+
+		async delete(key: string): Promise<void> {
+			await client.delete(key);
+		},
+	};
+}
+
+function normalizeTimestamp(value: string | Date | undefined): string {
+	if (!value) return '';
+	if (typeof value === 'string') return value;
+	return value.toISOString();
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Default entry for `@agentuity/storage`.
+ *
+ * The real backend selection happens in `package.json`'s `exports`
+ * conditions: under Bun the `"bun"` condition routes the bare import
+ * to `./bun.js`; under Node (and other resolvers that respect the
+ * `"node"` condition) it routes to `./node.js`.
+ *
+ * This file exists for resolvers that ignore conditions entirely (some
+ * IDE indexers, certain bundler configurations, or callers using the
+ * legacy `main` field). For those, we re-export the Node backend,
+ * which works under both runtimes.
+ */
+
+export * from './node.ts';

package/src/node.ts

@@ -0,0 +1,380 @@
+/**
+ * Node-backed implementation of `S3ClientLike`.
+ *
+ * Wraps `@aws-sdk/client-s3`. Resolvable on both Node and Bun, so it
+ * can serve as the package's default fallback for resolvers that do
+ * not honor the `"bun"` exports condition.
+ *
+ * Design notes:
+ *
+ * 1. **Lazy SDK loading.** `@aws-sdk/client-s3` is large (~1 MB on
+ *    disk) and imports several hundred files at startup. To keep the
+ *    cost off the cold-start path of callers that import this module
+ *    but never actually upload/download, the SDK is loaded via dynamic
+ *    `import()` on first method call.
+ *
+ * 2. **Streamed uploads track byte counts via a counting passthrough.**
+ *    `PutObjectCommand` does not report bytes uploaded. For
+ *    fixed-size bodies (`Uint8Array`, `ArrayBuffer`, `Buffer`,
+ *    `string`, `Blob`) we use `.byteLength` / `.size`. For
+ *    `ReadableStream` bodies we wrap the source in a counting
+ *    `Transform` so the returned byte count matches what was actually
+ *    sent on the wire.
+ *
+ * 3. **Bucket-in-endpoint addressing.** Agentuity buckets use
+ *    virtual-host-style endpoints (`<bucket>.<host>`), so the bucket
+ *    name is implicit in the URL. The SDK still requires a `Bucket`
+ *    parameter on each command; we extract it from the endpoint's
+ *    leading hostname label and rely on the endpoint override to route
+ *    correctly. `forcePathStyle` is `false`.
+ */
+
+import { Buffer } from 'node:buffer';
+import { Readable, Transform } from 'node:stream';
+import type { ReadableStream as NodeWebReadableStream } from 'node:stream/web';
+import type {
+	BucketConfig,
+	S3Body,
+	S3ClientLike,
+	S3FileLike,
+	S3ListOptions,
+	S3ListResult,
+	S3StatResult,
+	S3WriteOptions,
+} from './types.ts';
+
+export type { BucketConfig, S3ClientLike } from './types.ts';
+
+// Lazy-loaded handle to `@aws-sdk/client-s3`. Populated on first call to
+// `loadSdk()`; subsequent calls reuse the cached module.
+type SdkModule = typeof import('@aws-sdk/client-s3');
+let sdkModule: SdkModule | null = null;
+let sdkPromise: Promise<SdkModule> | null = null;
+
+async function loadSdk(): Promise<SdkModule> {
+	if (sdkModule) return sdkModule;
+	if (!sdkPromise) {
+		sdkPromise = import('@aws-sdk/client-s3').then((mod) => {
+			sdkModule = mod;
+			return mod;
+		});
+	}
+	return sdkPromise;
+}
+
+interface InternalState {
+	endpoint: string;
+	bucketLabel: string;
+	region: string;
+	credentials: { accessKeyId: string; secretAccessKey: string };
+	/** Cached SDK client; created on first use. */
+	clientPromise: Promise<import('@aws-sdk/client-s3').S3Client> | null;
+}
+
+export function createS3Client(bucket: BucketConfig): S3ClientLike {
+	const endpoint = bucket.endpoint.startsWith('http')
+		? bucket.endpoint
+		: `https://${bucket.endpoint}`;
+
+	// Extract the leading hostname label as the bucket name. The endpoint
+	// is virtual-hosted-style (`<bucket>.<host>`), so the SDK's `Bucket`
+	// parameter is essentially a placeholder — what actually routes the
+	// request is the `endpoint` URL.
+	const bucketLabel = extractBucketLabel(endpoint);
+
+	const state: InternalState = {
+		endpoint,
+		bucketLabel,
+		region: bucket.region || 'auto',
+		credentials: {
+			accessKeyId: bucket.access_key,
+			secretAccessKey: bucket.secret_key,
+		},
+		clientPromise: null,
+	};
+
+	const getClient = async () => {
+		if (!state.clientPromise) {
+			const sdk = await loadSdk();
+			state.clientPromise = Promise.resolve(
+				new sdk.S3Client({
+					endpoint: state.endpoint,
+					region: state.region,
+					credentials: state.credentials,
+					forcePathStyle: false,
+				})
+			);
+		}
+		return state.clientPromise;
+	};
+
+	return {
+		async list(opts?: S3ListOptions | null): Promise<S3ListResult> {
+			const sdk = await loadSdk();
+			const client = await getClient();
+			const out = await client.send(
+				new sdk.ListObjectsV2Command({
+					Bucket: state.bucketLabel,
+					Prefix: opts?.prefix,
+					MaxKeys: opts?.maxKeys,
+				})
+			);
+			return {
+				contents: (out.Contents ?? []).map((o) => ({
+					key: o.Key ?? '',
+					size: o.Size ?? 0,
+					lastModified: o.LastModified?.toISOString() ?? '',
+					etag: o.ETag,
+				})),
+				isTruncated: out.IsTruncated ?? false,
+			};
+		},
+
+		async stat(key: string): Promise<S3StatResult> {
+			const sdk = await loadSdk();
+			const client = await getClient();
+			const out = await client.send(
+				new sdk.HeadObjectCommand({ Bucket: state.bucketLabel, Key: key })
+			);
+			return {
+				size: out.ContentLength ?? 0,
+				type: out.ContentType,
+				lastModified: out.LastModified,
+				etag: out.ETag,
+			};
+		},
+
+		file(key: string): S3FileLike {
+			return {
+				async arrayBuffer(): Promise<ArrayBuffer> {
+					const sdk = await loadSdk();
+					const client = await getClient();
+					const out = await client.send(
+						new sdk.GetObjectCommand({ Bucket: state.bucketLabel, Key: key })
+					);
+					return readBodyAsArrayBuffer(out.Body);
+				},
+				async text(): Promise<string> {
+					const buf = await this.arrayBuffer();
+					return new TextDecoder().decode(buf);
+				},
+				stream(): ReadableStream<Uint8Array> {
+					// Lazily fetch on first pull so callers can hold a handle
+					// without triggering a network call upfront.
+					let inner: ReadableStream<Uint8Array> | null = null;
+					let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+					return new ReadableStream<Uint8Array>({
+						async pull(controller) {
+							if (!inner) {
+								const sdk = await loadSdk();
+								const client = await getClient();
+								const out = await client.send(
+									new sdk.GetObjectCommand({
+										Bucket: state.bucketLabel,
+										Key: key,
+									})
+								);
+								inner = bodyToWebStream(out.Body);
+								reader = inner.getReader() as ReadableStreamDefaultReader<Uint8Array>;
+							}
+							const { value, done } = await reader!.read();
+							if (done) controller.close();
+							else controller.enqueue(value);
+						},
+						async cancel() {
+							await reader?.cancel();
+						},
+					});
+				},
+			};
+		},
+
+		async write(key: string, body: S3Body, opts?: S3WriteOptions): Promise<number> {
+			const sdk = await loadSdk();
+			const client = await getClient();
+			const { Body, getBytesUploaded } = prepareBody(body);
+			await client.send(
+				new sdk.PutObjectCommand({
+					Bucket: state.bucketLabel,
+					Key: key,
+					Body,
+					ContentType: opts?.type,
+				})
+			);
+			return getBytesUploaded();
+		},
+
+		async delete(key: string): Promise<void> {
+			const sdk = await loadSdk();
+			const client = await getClient();
+			await client.send(new sdk.DeleteObjectCommand({ Bucket: state.bucketLabel, Key: key }));
+		},
+	};
+}
+
+/**
+ * Convert one of our accepted `S3Body` shapes into something the AWS
+ * SDK can consume, while also preparing a way to report the number of
+ * bytes that flowed to S3.
+ *
+ * For fixed-size bodies the count is known up front. For streaming
+ * bodies we attach a counting `Transform` and read the tally back after
+ * the upload completes.
+ */
+function prepareBody(body: S3Body): {
+	Body: Uint8Array | Buffer | Readable | string;
+	getBytesUploaded(): number;
+} {
+	if (typeof body === 'string') {
+		const bytes = Buffer.byteLength(body, 'utf-8');
+		return { Body: body, getBytesUploaded: () => bytes };
+	}
+	if (body instanceof Uint8Array) {
+		return { Body: body, getBytesUploaded: () => body.byteLength };
+	}
+	if (body instanceof ArrayBuffer) {
+		const buf = Buffer.from(body);
+		return { Body: buf, getBytesUploaded: () => buf.byteLength };
+	}
+	if (typeof Blob !== 'undefined' && body instanceof Blob) {
+		// Convert the Blob to a Node stream, counting bytes as it flows.
+		const webStream = body.stream() as unknown as NodeWebReadableStream<Uint8Array>;
+		const nodeStream = Readable.fromWeb(webStream);
+		const { stream, getBytes } = countingPassthrough(nodeStream);
+		return { Body: stream, getBytesUploaded: getBytes };
+	}
+	if (isWebReadableStream(body)) {
+		const nodeStream = Readable.fromWeb(body as unknown as NodeWebReadableStream<Uint8Array>);
+		const { stream, getBytes } = countingPassthrough(nodeStream);
+		return { Body: stream, getBytesUploaded: getBytes };
+	}
+	// Fallthrough: pass through whatever it is. Should be unreachable
+	// given the `S3Body` union, but keeps the function total.
+	return {
+		Body: body as unknown as Uint8Array,
+		getBytesUploaded: () => 0,
+	};
+}
+
+function isWebReadableStream(value: unknown): value is ReadableStream<Uint8Array> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as { getReader?: unknown }).getReader === 'function'
+	);
+}
+
+/**
+ * Wrap a Node `Readable` in a passthrough that counts bytes flowing
+ * through it. The returned `getBytes()` callback returns the running
+ * tally; call it after the consumer has finished reading.
+ */
+function countingPassthrough(source: Readable): {
+	stream: Readable;
+	getBytes(): number;
+} {
+	let count = 0;
+	const counter = new Transform({
+		transform(chunk, _enc, cb) {
+			count += chunk.length;
+			cb(null, chunk);
+		},
+	});
+	source.pipe(counter);
+	source.on('error', (err) => counter.destroy(err));
+	return { stream: counter, getBytes: () => count };
+}
+
+/**
+ * Read an SDK `GetObjectCommand` response body fully into an
+ * `ArrayBuffer`. The SDK returns `unknown` for the body shape because
+ * it varies by runtime; in Node it's an `IncomingMessage`-style
+ * `Readable`.
+ */
+async function readBodyAsArrayBuffer(body: unknown): Promise<ArrayBuffer> {
+	if (!body) return new ArrayBuffer(0);
+	if (body instanceof Uint8Array) {
+		// Some shapes return a Uint8Array directly. Copy into a fresh
+		// ArrayBuffer so the return type is the strict ArrayBuffer rather
+		// than ArrayBuffer | SharedArrayBuffer (which `.buffer` may be).
+		const out = new Uint8Array(body.byteLength);
+		out.set(body);
+		return out.buffer;
+	}
+	if (isWebReadableStream(body)) {
+		const reader = body.getReader();
+		const chunks: Uint8Array[] = [];
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			if (value) chunks.push(value);
+		}
+		return concatUint8Arrays(chunks).buffer;
+	}
+	// Otherwise treat as a Node Readable.
+	const chunks: Buffer[] = [];
+	for await (const chunk of body as Readable) {
+		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	}
+	const merged = Buffer.concat(chunks);
+	// Copy into a tightly-sized ArrayBuffer to avoid sharing the underlying
+	// pool buffer with other Buffer instances.
+	const out = new Uint8Array(merged.byteLength);
+	out.set(merged);
+	return out.buffer;
+}
+
+/**
+ * Convert an SDK response body into a Web `ReadableStream<Uint8Array>`.
+ * Returns an empty stream when the body is missing.
+ */
+function bodyToWebStream(body: unknown): ReadableStream<Uint8Array> {
+	if (!body) {
+		return new ReadableStream<Uint8Array>({
+			start(controller) {
+				controller.close();
+			},
+		});
+	}
+	if (isWebReadableStream(body)) return body;
+	if (body instanceof Uint8Array) {
+		return new ReadableStream<Uint8Array>({
+			start(controller) {
+				controller.enqueue(body);
+				controller.close();
+			},
+		});
+	}
+	// Assume Node Readable.
+	return Readable.toWeb(body as Readable) as unknown as ReadableStream<Uint8Array>;
+}
+
+function concatUint8Arrays(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
+	let total = 0;
+	for (const p of parts) total += p.byteLength;
+	// Allocate against a concrete ArrayBuffer (not SharedArrayBuffer) so
+	// the resulting `.buffer` is typed as ArrayBuffer.
+	const out = new Uint8Array(new ArrayBuffer(total));
+	let offset = 0;
+	for (const p of parts) {
+		out.set(p, offset);
+		offset += p.byteLength;
+	}
+	return out;
+}
+
+/**
+ * Pull the leading hostname label off a virtual-hosted-style endpoint
+ * URL. Falls back to `'bucket'` if parsing fails — which is fine
+ * because the endpoint override controls actual routing; the SDK only
+ * uses `Bucket` to construct path-style URLs (which we never do).
+ */
+function extractBucketLabel(endpoint: string): string {
+	try {
+		const url = new URL(endpoint);
+		const firstLabel = url.hostname.split('.')[0];
+		return firstLabel || 'bucket';
+	} catch {
+		return 'bucket';
+	}
+}