@mandujs/core 0.53.3 → 0.54.0

package/src/storage/s3/index.ts

@@ -1,412 +1,412 @@
-/**
- * @mandujs/core/storage/s3
- *
- * Thin, S3-compatible object storage helper backed by **native `Bun.S3Client`**
- * (no AWS SDK, no external deps). The same client works against AWS S3,
- * Cloudflare R2, MinIO, DigitalOcean Spaces, and any other S3-compatible
- * service — the only thing that changes is the `endpoint` URL.
- *
- * ## Credentials
- *
- * Bun reads `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optionally
- * `AWS_SESSION_TOKEN`) — plus the `S3_*` variants — from the environment at
- * initialization time. You can also pass them explicitly to the underlying
- * `Bun.S3Client`, but this helper intentionally does **not** surface that
- * option: routing secrets through env vars (or a `.env` file loaded by Bun)
- * keeps credentials out of application code. See
- * https://bun.com/docs/runtime/s3#credentials for the full matrix.
- *
- * ## Endpoint
- *
- * Pass `endpoint` on the client config for R2/MinIO/GCS/Supabase/etc. Omit it
- * for AWS (Bun infers the endpoint from `region` + `bucket`).
- *
- * @example
- * ```ts
- * import { createS3Client } from "@mandujs/core/storage/s3";
- *
- * const storage = createS3Client({
- *   bucket: "uploads",
- *   endpoint: "https://<account>.r2.cloudflarestorage.com",
- *   region: "auto",
- * });
- *
- * const url = await storage.upload(file, { key: `u/${id}.png` });
- * const presigned = await storage.presign({ key: "u/next.png", method: "PUT", contentType: "image/png" });
- * ```
- *
- * @module storage/s3
- */
-
-// ─── Public types ───────────────────────────────────────────────────────────
-
-/**
- * S3 client configuration. Credentials are **not** part of this interface —
- * they come from `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env vars that
- * Bun auto-reads. See module docs.
- */
-export interface S3Config {
-  /** Bucket name. Required. */
-  bucket: string;
-  /**
-   * Custom endpoint URL. Required for R2/MinIO/GCS/etc.; omit for AWS (Bun
-   * infers from `region`).
-   */
-  endpoint?: string;
-  /**
-   * Force path-style URLs (`endpoint/bucket/key`) instead of virtual-hosted
-   * (`bucket.endpoint/key`). MinIO usually needs this set to `true`. AWS and
-   * R2 work with either but default to virtual-hosted. Default: `false`.
-   */
-  forcePathStyle?: boolean;
-  /**
-   * Region. Bun defaults to `us-east-1` for AWS; set `"auto"` for Cloudflare
-   * R2. No default applied here — we pass through as-is so Bun's own
-   * defaulting logic stays authoritative.
-   */
-  region?: string;
-}
-
-/** Options for uploading a single object. */
-export interface S3UploadOptions {
-  /** Target object key (path inside the bucket). Required. */
-  key: string;
-  /**
-   * Content-Type header. Inferred from the key's file extension when omitted
-   * — see `getContentType` below for the covered extensions.
-   */
-  contentType?: string;
-  /**
-   * User metadata. Keys are lowercased and prefixed with `x-amz-meta-` by S3.
-   * Values must be ASCII — non-ASCII characters will be rejected by most
-   * providers; we do not validate here.
-   */
-  metadata?: Record<string, string>;
-  /**
-   * Canned ACL. Applied to this upload only. Omit to inherit the bucket
-   * default (recommended for private buckets).
-   */
-  acl?: "private" | "public-read";
-}
-
-/** Options for generating a presigned URL. */
-export interface S3PresignOptions {
-  /** Object key. Required. */
-  key: string;
-  /** HTTP method. Default: `"PUT"` (client-direct upload is the common case). */
-  method?: "GET" | "PUT";
-  /** URL lifetime in **seconds**. Default: 900 (15 minutes). */
-  expiresIn?: number;
-  /**
-   * `Content-Type` baked into the signature. Only meaningful for `PUT`; the
-   * uploading client MUST send a matching header or the signature will fail.
-   */
-  contentType?: string;
-}
-
-/** Opaque client instance. */
-export interface S3Client {
-  /**
-   * Uploads a blob/buffer and resolves to the canonical object URL
-   * (endpoint + bucket + key).
-   */
-  upload(
-    body: Blob | ArrayBuffer | Uint8Array,
-    options: S3UploadOptions,
-  ): Promise<string>;
-
-  /** Generates a presigned URL for client-direct upload (PUT) or download (GET). */
-  presign(options: S3PresignOptions): Promise<string>;
-
-  /** Deletes an object. Resolves silently if the object does not exist. */
-  delete(key: string): Promise<void>;
-
-  /** Returns a readable stream for the object body. Throws if not found. */
-  getReadable(key: string): Promise<ReadableStream>;
-
-  /**
-   * Head check — `true` if the object exists, `false` on 404. Any other error
-   * (network failure, 403, malformed response) is re-thrown.
-   */
-  exists(key: string): Promise<boolean>;
-}
-
-// ─── Bun runtime surface (structural; no `any`) ─────────────────────────────
-
-/** Options accepted by `S3File.write`. Mirrors Bun's BlobPropertyBag extensions. */
-interface BunS3WriteOptions {
-  type?: string;
-  acl?: "private" | "public-read";
-}
-
-/** Options accepted by `S3File.presign`. */
-interface BunS3PresignOptions {
-  method?: "GET" | "PUT";
-  expiresIn?: number;
-  type?: string;
-}
-
-/** Minimal shape of the `S3File` handle returned by `client.file(key)`. */
-interface BunS3File {
-  write(
-    body: Blob | ArrayBuffer | Uint8Array,
-    options?: BunS3WriteOptions,
-  ): Promise<number>;
-  presign(options?: BunS3PresignOptions): string;
-  delete(): Promise<void>;
-  exists(): Promise<boolean>;
-  stream(): ReadableStream;
-}
-
-/** Options accepted by the `Bun.S3Client` constructor. */
-interface BunS3ClientConfig {
-  bucket: string;
-  endpoint?: string;
-  region?: string;
-  virtualHostedStyle?: boolean;
-}
-
-/** Minimal `Bun.S3Client` instance shape used by this module. */
-export interface BunS3ClientInstance {
-  file(key: string): BunS3File;
-}
-
-/**
- * Constructor surface — `Bun.S3Client` is a class. We only need the `new`
- * signature structurally, so we type it as a callable returning an instance.
- */
-export type BunS3ClientCtor = new (config: BunS3ClientConfig) => BunS3ClientInstance;
-
-// ─── Content-type inference ─────────────────────────────────────────────────
-
-const EXTENSION_MAP: ReadonlyMap<string, string> = new Map([
-  ["jpg", "image/jpeg"],
-  ["jpeg", "image/jpeg"],
-  ["png", "image/png"],
-  ["webp", "image/webp"],
-  ["gif", "image/gif"],
-  ["pdf", "application/pdf"],
-  ["txt", "text/plain"],
-  ["json", "application/json"],
-  ["csv", "text/csv"],
-  ["zip", "application/zip"],
-  ["mp4", "video/mp4"],
-  ["webm", "video/webm"],
-]);
-
-/**
- * Maps a key's trailing file extension to a MIME type. Returns
- * `application/octet-stream` for unknown/missing extensions.
- *
- * Exported for tests and for callers that want to inspect the mapping without
- * uploading (e.g., for building a `Content-Type` header on a presigned PUT).
- */
-export function getContentType(key: string): string {
-  const lastDot = key.lastIndexOf(".");
-  if (lastDot === -1 || lastDot === key.length - 1) {
-    return "application/octet-stream";
-  }
-  const ext = key.slice(lastDot + 1).toLowerCase();
-  return EXTENSION_MAP.get(ext) ?? "application/octet-stream";
-}
-
-// ─── URL construction ───────────────────────────────────────────────────────
-
-/**
- * Builds the canonical object URL that `upload()` returns. Uses the same
- * path-vs-virtual-host logic Bun itself applies, so the URL matches what
- * `fetch()` would resolve.
- *
- * For AWS (no endpoint set), we return an `s3://<bucket>/<key>` URI — the
- * caller may not know the region and we don't want to guess at a public URL.
- */
-function buildObjectUrl(
-  config: S3Config,
-  key: string,
-): string {
-  const encodedKey = encodeKey(key);
-
-  if (!config.endpoint) {
-    // Bun infers the AWS endpoint; returning s3:// keeps this provider-agnostic
-    // without pretending to know if the bucket is public-read.
-    return `s3://${config.bucket}/${encodedKey}`;
-  }
-
-  const base = config.endpoint.replace(/\/+$/, "");
-  if (config.forcePathStyle) {
-    return `${base}/${config.bucket}/${encodedKey}`;
-  }
-
-  // Virtual-hosted style: splice bucket into the hostname.
-  try {
-    const url = new URL(base);
-    url.hostname = `${config.bucket}.${url.hostname}`;
-    return `${url.toString().replace(/\/+$/, "")}/${encodedKey}`;
-  } catch {
-    // Malformed endpoint — fall back to path style so we still return a
-    // deterministic, debuggable URL.
-    return `${base}/${config.bucket}/${encodedKey}`;
-  }
-}
-
-/** URL-encodes every path segment of an S3 key while preserving `/` separators. */
-function encodeKey(key: string): string {
-  return key
-    .split("/")
-    .map((segment) => encodeURIComponent(segment))
-    .join("/");
-}
-
-// ─── Bun runtime probe ──────────────────────────────────────────────────────
-
-function getBunS3ClientCtor(): BunS3ClientCtor {
-  const g = globalThis as unknown as { Bun?: { S3Client?: BunS3ClientCtor } };
-  if (!g.Bun || !g.Bun.S3Client) {
-    throw new Error(
-      "[@mandujs/core/storage/s3] Bun.S3Client is unavailable — this module requires the Bun runtime (>= 1.3).",
-    );
-  }
-  return g.Bun.S3Client;
-}
-
-// ─── Factory ────────────────────────────────────────────────────────────────
-
-/**
- * Internal factory accepting an injectable `S3Client` constructor — used by
- * unit tests to swap in a fake implementation. Production callers use
- * {@link createS3Client}, which binds this to `Bun.S3Client`.
- */
-export function _createS3ClientWith(
-  Ctor: BunS3ClientCtor,
-  config: S3Config,
-): S3Client {
-  if (!config.bucket || typeof config.bucket !== "string") {
-    throw new TypeError(
-      "[@mandujs/core/storage/s3] createS3Client: 'bucket' is required.",
-    );
-  }
-
-  const bunClient = new Ctor({
-    bucket: config.bucket,
-    endpoint: config.endpoint,
-    region: config.region,
-    // forcePathStyle === true  ⇒ virtualHostedStyle: false (the Bun default).
-    // forcePathStyle === false ⇒ leave Bun's default untouched.
-    // Only set virtualHostedStyle explicitly if the user *opts out* of path
-    // style for a service that normally defaults to it. The map here is 1:1.
-    virtualHostedStyle: config.forcePathStyle === true ? false : undefined,
-  });
-
-  async function upload(
-    body: Blob | ArrayBuffer | Uint8Array,
-    options: S3UploadOptions,
-  ): Promise<string> {
-    if (!options.key) {
-      throw new TypeError(
-        "[@mandujs/core/storage/s3] upload: 'key' is required.",
-      );
-    }
-    const file = bunClient.file(options.key);
-    const contentType = options.contentType ?? getContentType(options.key);
-
-    await file.write(body, {
-      type: contentType,
-      ...(options.acl !== undefined ? { acl: options.acl } : {}),
-    });
-
-    // NOTE: metadata is accepted in our public type for forward-compat, but
-    // Bun 1.3's `S3File.write` does not surface a `metadata` option. Dropping
-    // it silently would be a bug waiting to happen, so we throw at call time.
-    if (options.metadata && Object.keys(options.metadata).length > 0) {
-      throw new Error(
-        "[@mandujs/core/storage/s3] upload: 'metadata' is not yet supported by Bun.S3Client.write. Use a presigned URL with custom headers, or file an issue upstream.",
-      );
-    }
-
-    return buildObjectUrl(config, options.key);
-  }
-
-  async function presign(options: S3PresignOptions): Promise<string> {
-    if (!options.key) {
-      throw new TypeError(
-        "[@mandujs/core/storage/s3] presign: 'key' is required.",
-      );
-    }
-    const method = options.method ?? "PUT";
-    const expiresIn = options.expiresIn ?? 900;
-    const file = bunClient.file(options.key);
-
-    // Bun.S3File.presign is synchronous; we wrap in a Promise so the public
-    // API stays consistent with the rest of the helper surface.
-    const url = file.presign({
-      method,
-      expiresIn,
-      ...(options.contentType !== undefined ? { type: options.contentType } : {}),
-    });
-    return url;
-  }
-
-  async function deleteObject(key: string): Promise<void> {
-    const file = bunClient.file(key);
-    try {
-      await file.delete();
-    } catch (err) {
-      // S3 returns success for delete-of-missing-key; but some S3-compatible
-      // providers (and network hiccups) can surface a 404-shaped error. We
-      // swallow "not found" and re-throw everything else.
-      if (isNotFoundError(err)) return;
-      throw err;
-    }
-  }
-
-  async function getReadable(key: string): Promise<ReadableStream> {
-    const file = bunClient.file(key);
-    // `file.stream()` is synchronous and returns a ReadableStream that lazily
-    // issues the GET when you start consuming. We preserve that laziness and
-    // let errors surface on first read rather than proactively HEAD-ing here.
-    return file.stream();
-  }
-
-  async function exists(key: string): Promise<boolean> {
-    const file = bunClient.file(key);
-    try {
-      return await file.exists();
-    } catch (err) {
-      if (isNotFoundError(err)) return false;
-      throw err;
-    }
-  }
-
-  return {
-    upload,
-    presign,
-    delete: deleteObject,
-    getReadable,
-    exists,
-  };
-}
-
-/**
- * Creates an S3-compatible storage client.
- *
- * @throws if `config.bucket` is missing, or if called outside the Bun runtime.
- */
-export function createS3Client(config: S3Config): S3Client {
-  return _createS3ClientWith(getBunS3ClientCtor(), config);
-}
-
-// ─── Error helpers ──────────────────────────────────────────────────────────
-
-/**
- * Structural check for "object not found" errors raised by Bun's S3 layer.
- * Bun emits an `S3Error` instance with `code` set; we also handle the
- * HTTP-status-bearing variants some providers surface.
- */
-function isNotFoundError(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  const e = err as { name?: unknown; code?: unknown; status?: unknown };
-  if (e.code === "NoSuchKey") return true;
-  if (e.code === "NotFound") return true;
-  if (e.status === 404) return true;
-  return false;
-}
+/**
+ * @mandujs/core/storage/s3
+ *
+ * Thin, S3-compatible object storage helper backed by **native `Bun.S3Client`**
+ * (no AWS SDK, no external deps). The same client works against AWS S3,
+ * Cloudflare R2, MinIO, DigitalOcean Spaces, and any other S3-compatible
+ * service — the only thing that changes is the `endpoint` URL.
+ *
+ * ## Credentials
+ *
+ * Bun reads `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optionally
+ * `AWS_SESSION_TOKEN`) — plus the `S3_*` variants — from the environment at
+ * initialization time. You can also pass them explicitly to the underlying
+ * `Bun.S3Client`, but this helper intentionally does **not** surface that
+ * option: routing secrets through env vars (or a `.env` file loaded by Bun)
+ * keeps credentials out of application code. See
+ * https://bun.com/docs/runtime/s3#credentials for the full matrix.
+ *
+ * ## Endpoint
+ *
+ * Pass `endpoint` on the client config for R2/MinIO/GCS/Supabase/etc. Omit it
+ * for AWS (Bun infers the endpoint from `region` + `bucket`).
+ *
+ * @example
+ * ```ts
+ * import { createS3Client } from "@mandujs/core/storage/s3";
+ *
+ * const storage = createS3Client({
+ *   bucket: "uploads",
+ *   endpoint: "https://<account>.r2.cloudflarestorage.com",
+ *   region: "auto",
+ * });
+ *
+ * const url = await storage.upload(file, { key: `u/${id}.png` });
+ * const presigned = await storage.presign({ key: "u/next.png", method: "PUT", contentType: "image/png" });
+ * ```
+ *
+ * @module storage/s3
+ */
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/**
+ * S3 client configuration. Credentials are **not** part of this interface —
+ * they come from `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env vars that
+ * Bun auto-reads. See module docs.
+ */
+export interface S3Config {
+  /** Bucket name. Required. */
+  bucket: string;
+  /**
+   * Custom endpoint URL. Required for R2/MinIO/GCS/etc.; omit for AWS (Bun
+   * infers from `region`).
+   */
+  endpoint?: string;
+  /**
+   * Force path-style URLs (`endpoint/bucket/key`) instead of virtual-hosted
+   * (`bucket.endpoint/key`). MinIO usually needs this set to `true`. AWS and
+   * R2 work with either but default to virtual-hosted. Default: `false`.
+   */
+  forcePathStyle?: boolean;
+  /**
+   * Region. Bun defaults to `us-east-1` for AWS; set `"auto"` for Cloudflare
+   * R2. No default applied here — we pass through as-is so Bun's own
+   * defaulting logic stays authoritative.
+   */
+  region?: string;
+}
+
+/** Options for uploading a single object. */
+export interface S3UploadOptions {
+  /** Target object key (path inside the bucket). Required. */
+  key: string;
+  /**
+   * Content-Type header. Inferred from the key's file extension when omitted
+   * — see `getContentType` below for the covered extensions.
+   */
+  contentType?: string;
+  /**
+   * User metadata. Keys are lowercased and prefixed with `x-amz-meta-` by S3.
+   * Values must be ASCII — non-ASCII characters will be rejected by most
+   * providers; we do not validate here.
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Canned ACL. Applied to this upload only. Omit to inherit the bucket
+   * default (recommended for private buckets).
+   */
+  acl?: "private" | "public-read";
+}
+
+/** Options for generating a presigned URL. */
+export interface S3PresignOptions {
+  /** Object key. Required. */
+  key: string;
+  /** HTTP method. Default: `"PUT"` (client-direct upload is the common case). */
+  method?: "GET" | "PUT";
+  /** URL lifetime in **seconds**. Default: 900 (15 minutes). */
+  expiresIn?: number;
+  /**
+   * `Content-Type` baked into the signature. Only meaningful for `PUT`; the
+   * uploading client MUST send a matching header or the signature will fail.
+   */
+  contentType?: string;
+}
+
+/** Opaque client instance. */
+export interface S3Client {
+  /**
+   * Uploads a blob/buffer and resolves to the canonical object URL
+   * (endpoint + bucket + key).
+   */
+  upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options: S3UploadOptions,
+  ): Promise<string>;
+
+  /** Generates a presigned URL for client-direct upload (PUT) or download (GET). */
+  presign(options: S3PresignOptions): Promise<string>;
+
+  /** Deletes an object. Resolves silently if the object does not exist. */
+  delete(key: string): Promise<void>;
+
+  /** Returns a readable stream for the object body. Throws if not found. */
+  getReadable(key: string): Promise<ReadableStream>;
+
+  /**
+   * Head check — `true` if the object exists, `false` on 404. Any other error
+   * (network failure, 403, malformed response) is re-thrown.
+   */
+  exists(key: string): Promise<boolean>;
+}
+
+// ─── Bun runtime surface (structural; no `any`) ─────────────────────────────
+
+/** Options accepted by `S3File.write`. Mirrors Bun's BlobPropertyBag extensions. */
+interface BunS3WriteOptions {
+  type?: string;
+  acl?: "private" | "public-read";
+}
+
+/** Options accepted by `S3File.presign`. */
+interface BunS3PresignOptions {
+  method?: "GET" | "PUT";
+  expiresIn?: number;
+  type?: string;
+}
+
+/** Minimal shape of the `S3File` handle returned by `client.file(key)`. */
+interface BunS3File {
+  write(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options?: BunS3WriteOptions,
+  ): Promise<number>;
+  presign(options?: BunS3PresignOptions): string;
+  delete(): Promise<void>;
+  exists(): Promise<boolean>;
+  stream(): ReadableStream;
+}
+
+/** Options accepted by the `Bun.S3Client` constructor. */
+interface BunS3ClientConfig {
+  bucket: string;
+  endpoint?: string;
+  region?: string;
+  virtualHostedStyle?: boolean;
+}
+
+/** Minimal `Bun.S3Client` instance shape used by this module. */
+export interface BunS3ClientInstance {
+  file(key: string): BunS3File;
+}
+
+/**
+ * Constructor surface — `Bun.S3Client` is a class. We only need the `new`
+ * signature structurally, so we type it as a callable returning an instance.
+ */
+export type BunS3ClientCtor = new (config: BunS3ClientConfig) => BunS3ClientInstance;
+
+// ─── Content-type inference ─────────────────────────────────────────────────
+
+const EXTENSION_MAP: ReadonlyMap<string, string> = new Map([
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["png", "image/png"],
+  ["webp", "image/webp"],
+  ["gif", "image/gif"],
+  ["pdf", "application/pdf"],
+  ["txt", "text/plain"],
+  ["json", "application/json"],
+  ["csv", "text/csv"],
+  ["zip", "application/zip"],
+  ["mp4", "video/mp4"],
+  ["webm", "video/webm"],
+]);
+
+/**
+ * Maps a key's trailing file extension to a MIME type. Returns
+ * `application/octet-stream` for unknown/missing extensions.
+ *
+ * Exported for tests and for callers that want to inspect the mapping without
+ * uploading (e.g., for building a `Content-Type` header on a presigned PUT).
+ */
+export function getContentType(key: string): string {
+  const lastDot = key.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === key.length - 1) {
+    return "application/octet-stream";
+  }
+  const ext = key.slice(lastDot + 1).toLowerCase();
+  return EXTENSION_MAP.get(ext) ?? "application/octet-stream";
+}
+
+// ─── URL construction ───────────────────────────────────────────────────────
+
+/**
+ * Builds the canonical object URL that `upload()` returns. Uses the same
+ * path-vs-virtual-host logic Bun itself applies, so the URL matches what
+ * `fetch()` would resolve.
+ *
+ * For AWS (no endpoint set), we return an `s3://<bucket>/<key>` URI — the
+ * caller may not know the region and we don't want to guess at a public URL.
+ */
+function buildObjectUrl(
+  config: S3Config,
+  key: string,
+): string {
+  const encodedKey = encodeKey(key);
+
+  if (!config.endpoint) {
+    // Bun infers the AWS endpoint; returning s3:// keeps this provider-agnostic
+    // without pretending to know if the bucket is public-read.
+    return `s3://${config.bucket}/${encodedKey}`;
+  }
+
+  const base = config.endpoint.replace(/\/+$/, "");
+  if (config.forcePathStyle) {
+    return `${base}/${config.bucket}/${encodedKey}`;
+  }
+
+  // Virtual-hosted style: splice bucket into the hostname.
+  try {
+    const url = new URL(base);
+    url.hostname = `${config.bucket}.${url.hostname}`;
+    return `${url.toString().replace(/\/+$/, "")}/${encodedKey}`;
+  } catch {
+    // Malformed endpoint — fall back to path style so we still return a
+    // deterministic, debuggable URL.
+    return `${base}/${config.bucket}/${encodedKey}`;
+  }
+}
+
+/** URL-encodes every path segment of an S3 key while preserving `/` separators. */
+function encodeKey(key: string): string {
+  return key
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+// ─── Bun runtime probe ──────────────────────────────────────────────────────
+
+function getBunS3ClientCtor(): BunS3ClientCtor {
+  const g = globalThis as unknown as { Bun?: { S3Client?: BunS3ClientCtor } };
+  if (!g.Bun || !g.Bun.S3Client) {
+    throw new Error(
+      "[@mandujs/core/storage/s3] Bun.S3Client is unavailable — this module requires the Bun runtime (>= 1.3).",
+    );
+  }
+  return g.Bun.S3Client;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Internal factory accepting an injectable `S3Client` constructor — used by
+ * unit tests to swap in a fake implementation. Production callers use
+ * {@link createS3Client}, which binds this to `Bun.S3Client`.
+ */
+export function _createS3ClientWith(
+  Ctor: BunS3ClientCtor,
+  config: S3Config,
+): S3Client {
+  if (!config.bucket || typeof config.bucket !== "string") {
+    throw new TypeError(
+      "[@mandujs/core/storage/s3] createS3Client: 'bucket' is required.",
+    );
+  }
+
+  const bunClient = new Ctor({
+    bucket: config.bucket,
+    endpoint: config.endpoint,
+    region: config.region,
+    // forcePathStyle === true  ⇒ virtualHostedStyle: false (the Bun default).
+    // forcePathStyle === false ⇒ leave Bun's default untouched.
+    // Only set virtualHostedStyle explicitly if the user *opts out* of path
+    // style for a service that normally defaults to it. The map here is 1:1.
+    virtualHostedStyle: config.forcePathStyle === true ? false : undefined,
+  });
+
+  async function upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options: S3UploadOptions,
+  ): Promise<string> {
+    if (!options.key) {
+      throw new TypeError(
+        "[@mandujs/core/storage/s3] upload: 'key' is required.",
+      );
+    }
+    const file = bunClient.file(options.key);
+    const contentType = options.contentType ?? getContentType(options.key);
+
+    await file.write(body, {
+      type: contentType,
+      ...(options.acl !== undefined ? { acl: options.acl } : {}),
+    });
+
+    // NOTE: metadata is accepted in our public type for forward-compat, but
+    // Bun 1.3's `S3File.write` does not surface a `metadata` option. Dropping
+    // it silently would be a bug waiting to happen, so we throw at call time.
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+      throw new Error(
+        "[@mandujs/core/storage/s3] upload: 'metadata' is not yet supported by Bun.S3Client.write. Use a presigned URL with custom headers, or file an issue upstream.",
+      );
+    }
+
+    return buildObjectUrl(config, options.key);
+  }
+
+  async function presign(options: S3PresignOptions): Promise<string> {
+    if (!options.key) {
+      throw new TypeError(
+        "[@mandujs/core/storage/s3] presign: 'key' is required.",
+      );
+    }
+    const method = options.method ?? "PUT";
+    const expiresIn = options.expiresIn ?? 900;
+    const file = bunClient.file(options.key);
+
+    // Bun.S3File.presign is synchronous; we wrap in a Promise so the public
+    // API stays consistent with the rest of the helper surface.
+    const url = file.presign({
+      method,
+      expiresIn,
+      ...(options.contentType !== undefined ? { type: options.contentType } : {}),
+    });
+    return url;
+  }
+
+  async function deleteObject(key: string): Promise<void> {
+    const file = bunClient.file(key);
+    try {
+      await file.delete();
+    } catch (err) {
+      // S3 returns success for delete-of-missing-key; but some S3-compatible
+      // providers (and network hiccups) can surface a 404-shaped error. We
+      // swallow "not found" and re-throw everything else.
+      if (isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+
+  async function getReadable(key: string): Promise<ReadableStream> {
+    const file = bunClient.file(key);
+    // `file.stream()` is synchronous and returns a ReadableStream that lazily
+    // issues the GET when you start consuming. We preserve that laziness and
+    // let errors surface on first read rather than proactively HEAD-ing here.
+    return file.stream();
+  }
+
+  async function exists(key: string): Promise<boolean> {
+    const file = bunClient.file(key);
+    try {
+      return await file.exists();
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+
+  return {
+    upload,
+    presign,
+    delete: deleteObject,
+    getReadable,
+    exists,
+  };
+}
+
+/**
+ * Creates an S3-compatible storage client.
+ *
+ * @throws if `config.bucket` is missing, or if called outside the Bun runtime.
+ */
+export function createS3Client(config: S3Config): S3Client {
+  return _createS3ClientWith(getBunS3ClientCtor(), config);
+}
+
+// ─── Error helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Structural check for "object not found" errors raised by Bun's S3 layer.
+ * Bun emits an `S3Error` instance with `code` set; we also handle the
+ * HTTP-status-bearing variants some providers surface.
+ */
+function isNotFoundError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { name?: unknown; code?: unknown; status?: unknown };
+  if (e.code === "NoSuchKey") return true;
+  if (e.code === "NotFound") return true;
+  if (e.status === 404) return true;
+  return false;
+}