@miguelmorales13/nestkit 0.4.1 → 0.5.1

package/dist/storage/index.js

@@ -0,0 +1,528 @@
+import {
+  __decorateClass
+} from "../chunk-4MGIQFAJ.js";
+
+// src/storage/storage.port.ts
+var STORAGE = /* @__PURE__ */ Symbol("STORAGE");
+
+// src/storage/storage.options.ts
+var STORAGE_OPTIONS = /* @__PURE__ */ Symbol("STORAGE_OPTIONS");
+
+// src/storage/storage.module.ts
+import { Global, Module } from "@nestjs/common";
+
+// src/storage/adapters/local.storage.ts
+import { createReadStream } from "fs";
+import { mkdir, readFile, rm, stat, writeFile, readdir } from "fs/promises";
+import { dirname, join, normalize, resolve, sep, relative } from "path";
+import { pipeline } from "stream/promises";
+import { createWriteStream } from "fs";
+var LocalStorage = class {
+  constructor(options) {
+    this.root = resolve(options.root);
+    this.publicBaseUrl = options.publicBaseUrl?.replace(/\/$/, "");
+  }
+  /** Resolve a key to an absolute path, refusing anything that escapes the root. */
+  pathOf(key) {
+    const target = resolve(join(this.root, normalize(key)));
+    if (target !== this.root && !target.startsWith(this.root + sep)) {
+      throw new Error(`LocalStorage: key escapes the storage root: ${key}`);
+    }
+    return target;
+  }
+  async put(key, data) {
+    const path = this.pathOf(key);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, data);
+    return { key, size: data.byteLength };
+  }
+  async putStream(key, stream) {
+    const path = this.pathOf(key);
+    await mkdir(dirname(path), { recursive: true });
+    await pipeline(stream, createWriteStream(path));
+    const s = await stat(path);
+    return { key, size: s.size, lastModified: s.mtime };
+  }
+  async get(key) {
+    return readFile(this.pathOf(key));
+  }
+  async getStream(key, range) {
+    const path = this.pathOf(key);
+    const s = await stat(path);
+    if (!range) {
+      return { stream: createReadStream(path), contentLength: s.size, totalSize: s.size, lastModified: s.mtime };
+    }
+    const end = range.end ?? s.size - 1;
+    return {
+      stream: createReadStream(path, { start: range.start, end }),
+      contentLength: end - range.start + 1,
+      totalSize: s.size,
+      contentRange: `bytes ${range.start}-${end}/${s.size}`,
+      lastModified: s.mtime
+    };
+  }
+  async stat(key) {
+    try {
+      const s = await stat(this.pathOf(key));
+      return { key, size: s.size, lastModified: s.mtime };
+    } catch {
+      return null;
+    }
+  }
+  async exists(key) {
+    return await this.stat(key) !== null;
+  }
+  async delete(key) {
+    await rm(this.pathOf(key), { force: true });
+  }
+  async list(prefix, options) {
+    const base = this.pathOf(prefix);
+    const objects = [];
+    const walk = async (dir) => {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (options?.limit && objects.length >= options.limit) return;
+        const full = join(dir, String(entry.name));
+        if (entry.isDirectory()) await walk(full);
+        else {
+          const s = await stat(full);
+          objects.push({ key: relative(this.root, full).split(sep).join("/"), size: s.size, lastModified: s.mtime });
+        }
+      }
+    };
+    await walk(base);
+    return { objects };
+  }
+  publicUrl(key) {
+    return this.publicBaseUrl ? `${this.publicBaseUrl}/${key}` : `/${key}`;
+  }
+  async signedReadUrl(key) {
+    return this.publicUrl(key) ?? `/${key}`;
+  }
+  async signedUploadUrl() {
+    throw new Error(
+      "LocalStorage does not support direct signed uploads \u2014 a client cannot PUT to the server disk. Upload through your API in dev, or use the S3/R2 or Bunny adapter."
+    );
+  }
+};
+
+// src/storage/adapters/s3.storage.ts
+var S3Storage = class {
+  constructor(options) {
+    this.bucket = options.bucket;
+    this.publicBaseUrl = options.publicBaseUrl?.replace(/\/$/, "");
+    this.config = {
+      region: options.region ?? "us-east-1",
+      endpoint: options.endpoint,
+      forcePathStyle: options.forcePathStyle,
+      credentials: {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey
+      }
+    };
+  }
+  /** Lazily construct (and memoize) the S3 client, loading the SDK on first use. */
+  async client() {
+    if (!this.clientPromise) {
+      this.clientPromise = import("@aws-sdk/client-s3").then(
+        ({ S3Client }) => new S3Client(this.config)
+      );
+    }
+    return this.clientPromise;
+  }
+  async put(key, data, options) {
+    const [client, { PutObjectCommand }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3")
+    ]);
+    const out = await client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: data,
+        ContentType: options?.contentType,
+        CacheControl: options?.cacheControl,
+        ContentDisposition: options?.contentDisposition,
+        Metadata: options?.metadata
+      })
+    );
+    return { key, size: data.byteLength, contentType: options?.contentType, etag: out.ETag };
+  }
+  async putStream(key, stream, options) {
+    const [client, { Upload }] = await Promise.all([this.client(), import("@aws-sdk/lib-storage")]);
+    const upload = new Upload({
+      client,
+      params: {
+        Bucket: this.bucket,
+        Key: key,
+        Body: stream,
+        ContentType: options?.contentType,
+        CacheControl: options?.cacheControl,
+        ContentDisposition: options?.contentDisposition,
+        Metadata: options?.metadata
+      }
+    });
+    const out = await upload.done();
+    const info = await this.stat(key);
+    return { key, size: info?.size ?? 0, contentType: options?.contentType, etag: out?.ETag };
+  }
+  async get(key) {
+    const { stream } = await this.getStream(key);
+    const chunks = [];
+    for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+  }
+  async getStream(key, range) {
+    const [client, { GetObjectCommand }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3")
+    ]);
+    const out = await client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Range: range ? `bytes=${range.start}-${range.end ?? ""}` : void 0
+      })
+    );
+    return {
+      stream: out.Body,
+      contentType: out.ContentType,
+      contentLength: out.ContentLength,
+      contentRange: out.ContentRange,
+      totalSize: out.ContentRange ? Number(out.ContentRange.split("/")[1]) : out.ContentLength,
+      lastModified: out.LastModified,
+      etag: out.ETag
+    };
+  }
+  async stat(key) {
+    const [client, { HeadObjectCommand }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3")
+    ]);
+    try {
+      const out = await client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+      return {
+        key,
+        size: out.ContentLength ?? 0,
+        contentType: out.ContentType,
+        lastModified: out.LastModified,
+        etag: out.ETag
+      };
+    } catch (err) {
+      if (err?.$metadata?.httpStatusCode === 404 || err?.name === "NotFound") return null;
+      throw err;
+    }
+  }
+  async exists(key) {
+    return await this.stat(key) !== null;
+  }
+  async delete(key) {
+    const [client, { DeleteObjectCommand }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3")
+    ]);
+    await client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+  async list(prefix, options) {
+    const [client, { ListObjectsV2Command }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3")
+    ]);
+    const out = await client.send(
+      new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: prefix,
+        MaxKeys: options?.limit,
+        ContinuationToken: options?.cursor
+      })
+    );
+    return {
+      objects: (out.Contents ?? []).map((o) => ({
+        key: o.Key,
+        size: o.Size ?? 0,
+        lastModified: o.LastModified,
+        etag: o.ETag
+      })),
+      cursor: out.NextContinuationToken
+    };
+  }
+  async signedReadUrl(key, ttlSeconds = 3600) {
+    const [client, { GetObjectCommand }, { getSignedUrl }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3"),
+      import("@aws-sdk/s3-request-presigner")
+    ]);
+    return getSignedUrl(client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
+      expiresIn: ttlSeconds
+    });
+  }
+  async signedUploadUrl(key, options) {
+    const [client, { PutObjectCommand }, { getSignedUrl }] = await Promise.all([
+      this.client(),
+      import("@aws-sdk/client-s3"),
+      import("@aws-sdk/s3-request-presigner")
+    ]);
+    const ttl = options?.ttlSeconds ?? 900;
+    const url = await getSignedUrl(
+      client,
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        ContentType: options?.contentType,
+        CacheControl: options?.cacheControl
+      }),
+      { expiresIn: ttl }
+    );
+    return {
+      url,
+      method: "PUT",
+      headers: options?.contentType ? { "Content-Type": options.contentType } : void 0,
+      key,
+      expiresAt: new Date(Date.now() + ttl * 1e3)
+    };
+  }
+  publicUrl(key) {
+    return this.publicBaseUrl ? `${this.publicBaseUrl}/${key}` : null;
+  }
+};
+
+// src/storage/adapters/bunny.storage.ts
+import { createHash } from "crypto";
+import { Readable } from "stream";
+var BunnyStorage = class {
+  constructor(options) {
+    const host = `${options.region ? `${options.region}.` : ""}storage.bunnycdn.com`;
+    this.base = `https://${host}/${options.storageZone}`;
+    this.apiKey = options.apiKey;
+    this.pullZoneUrl = options.pullZoneUrl?.replace(/\/$/, "");
+    this.tokenSecurityKey = options.tokenSecurityKey;
+  }
+  url(key) {
+    return `${this.base}/${key.split("/").map(encodeURIComponent).join("/")}`;
+  }
+  async put(key, data, options) {
+    const res = await fetch(this.url(key), {
+      method: "PUT",
+      headers: {
+        AccessKey: this.apiKey,
+        "Content-Type": options?.contentType ?? "application/octet-stream"
+      },
+      body: data
+    });
+    if (!res.ok) throw new Error(`Bunny put ${key} failed: ${res.status} ${await res.text()}`);
+    return { key, size: data.byteLength, contentType: options?.contentType };
+  }
+  async putStream(key, stream, options) {
+    const res = await fetch(this.url(key), {
+      method: "PUT",
+      headers: {
+        AccessKey: this.apiKey,
+        "Content-Type": options?.contentType ?? "application/octet-stream"
+      },
+      body: Readable.toWeb(stream),
+      // Required by fetch when the body is a stream.
+      duplex: "half"
+    });
+    if (!res.ok) throw new Error(`Bunny putStream ${key} failed: ${res.status} ${await res.text()}`);
+    const info = await this.stat(key);
+    return { key, size: info?.size ?? options?.contentLength ?? 0, contentType: options?.contentType };
+  }
+  async get(key) {
+    const res = await fetch(this.url(key), { headers: { AccessKey: this.apiKey } });
+    if (!res.ok) throw new Error(`Bunny get ${key} failed: ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+  async getStream(key, range) {
+    const headers = { AccessKey: this.apiKey };
+    if (range) headers.Range = `bytes=${range.start}-${range.end ?? ""}`;
+    const res = await fetch(this.url(key), { headers });
+    if (!res.ok && res.status !== 206) throw new Error(`Bunny getStream ${key} failed: ${res.status}`);
+    if (!res.body) throw new Error(`Bunny getStream ${key}: empty body`);
+    const contentLength = Number(res.headers.get("content-length")) || void 0;
+    const contentRange = res.headers.get("content-range") ?? void 0;
+    return {
+      stream: Readable.fromWeb(res.body),
+      contentType: res.headers.get("content-type") ?? void 0,
+      contentLength,
+      contentRange,
+      totalSize: contentRange ? Number(contentRange.split("/")[1]) : contentLength
+    };
+  }
+  async stat(key) {
+    const slash = key.lastIndexOf("/");
+    const dir = slash >= 0 ? key.slice(0, slash) : "";
+    const name = slash >= 0 ? key.slice(slash + 1) : key;
+    const entries = await this.listRaw(dir);
+    const found = entries.find((e) => !e.IsDirectory && e.ObjectName === name);
+    if (!found) return null;
+    return {
+      key,
+      size: found.Length,
+      contentType: found.ContentType || void 0,
+      lastModified: found.LastChanged ? new Date(found.LastChanged) : void 0
+    };
+  }
+  async exists(key) {
+    return await this.stat(key) !== null;
+  }
+  async delete(key) {
+    const res = await fetch(this.url(key), { method: "DELETE", headers: { AccessKey: this.apiKey } });
+    if (!res.ok && res.status !== 404) {
+      throw new Error(`Bunny delete ${key} failed: ${res.status} ${await res.text()}`);
+    }
+  }
+  async listRaw(prefix) {
+    const path = prefix ? `${prefix.replace(/\/$/, "")}/` : "";
+    const res = await fetch(`${this.base}/${path}`, { headers: { AccessKey: this.apiKey } });
+    if (res.status === 404) return [];
+    if (!res.ok) throw new Error(`Bunny list ${prefix} failed: ${res.status}`);
+    return await res.json();
+  }
+  async list(prefix, options) {
+    const entries = await this.listRaw(prefix);
+    const base = prefix ? `${prefix.replace(/\/$/, "")}/` : "";
+    let objects = entries.filter((e) => !e.IsDirectory).map((e) => ({
+      key: `${base}${e.ObjectName}`,
+      size: e.Length,
+      contentType: e.ContentType || void 0,
+      lastModified: e.LastChanged ? new Date(e.LastChanged) : void 0
+    }));
+    if (options?.limit) objects = objects.slice(0, options.limit);
+    return { objects };
+  }
+  publicUrl(key) {
+    if (!this.pullZoneUrl) return null;
+    return `${this.pullZoneUrl}/${key.split("/").map(encodeURIComponent).join("/")}`;
+  }
+  async signedReadUrl(key, ttlSeconds = 3600) {
+    if (!this.pullZoneUrl) {
+      throw new Error("BunnyStorage.signedReadUrl: set pullZoneUrl (Bunny signs Pull Zone URLs).");
+    }
+    if (!this.tokenSecurityKey) {
+      return this.publicUrl(key);
+    }
+    const path = `/${key.split("/").map(encodeURIComponent).join("/")}`;
+    const expires = Math.floor(Date.now() / 1e3) + ttlSeconds;
+    const token = createHash("sha256").update(this.tokenSecurityKey + path + expires).digest("base64").replace(/\n/g, "").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    return `${this.pullZoneUrl}${path}?token=${token}&expires=${expires}`;
+  }
+  async signedUploadUrl() {
+    throw new Error(
+      "BunnyStorage does not support presigned direct uploads (Storage has no PUT signature that hides the zone password). Upload through your API, or use Bunny Stream/TUS for large video."
+    );
+  }
+};
+
+// src/storage/storage.module.ts
+var env = (k) => process.env[k] || void 0;
+function r2ToS3Options(r2) {
+  return {
+    bucket: r2.bucket,
+    region: "auto",
+    endpoint: `https://${r2.accountId}.r2.cloudflarestorage.com`,
+    accessKeyId: r2.accessKeyId,
+    secretAccessKey: r2.secretAccessKey,
+    publicBaseUrl: r2.publicBaseUrl
+  };
+}
+function resolveStorageOptions(options = {}) {
+  const provider = options.provider ?? env("STORAGE_PROVIDER") ?? "local";
+  return {
+    provider,
+    local: options.local ?? {
+      root: env("STORAGE_LOCAL_ROOT") ?? ".storage",
+      publicBaseUrl: env("STORAGE_PUBLIC_BASE_URL")
+    },
+    s3: options.s3 ?? (env("S3_BUCKET") ? {
+      bucket: env("S3_BUCKET"),
+      region: env("S3_REGION"),
+      endpoint: env("S3_ENDPOINT"),
+      accessKeyId: env("S3_ACCESS_KEY_ID") ?? "",
+      secretAccessKey: env("S3_SECRET_ACCESS_KEY") ?? "",
+      publicBaseUrl: env("S3_PUBLIC_BASE_URL"),
+      forcePathStyle: env("S3_FORCE_PATH_STYLE") === "true"
+    } : void 0),
+    r2: options.r2 ?? (env("R2_ACCOUNT_ID") ? {
+      accountId: env("R2_ACCOUNT_ID"),
+      bucket: env("R2_BUCKET") ?? "",
+      accessKeyId: env("R2_ACCESS_KEY_ID") ?? "",
+      secretAccessKey: env("R2_SECRET_ACCESS_KEY") ?? "",
+      publicBaseUrl: env("R2_PUBLIC_BASE_URL")
+    } : void 0),
+    bunny: options.bunny ?? (env("BUNNY_STORAGE_ZONE") ? {
+      storageZone: env("BUNNY_STORAGE_ZONE"),
+      apiKey: env("BUNNY_API_KEY") ?? "",
+      region: env("BUNNY_REGION"),
+      pullZoneUrl: env("BUNNY_PULL_ZONE_URL"),
+      tokenSecurityKey: env("BUNNY_TOKEN_SECURITY_KEY")
+    } : void 0)
+  };
+}
+function createStorageAdapter(options) {
+  const resolved = resolveStorageOptions(options);
+  switch (resolved.provider) {
+    case "local":
+      return new LocalStorage(resolved.local);
+    case "s3":
+      if (!resolved.s3) throw new Error('StorageModule: provider "s3" selected but no s3 options / S3_* env set.');
+      return new S3Storage(resolved.s3);
+    case "r2":
+      if (!resolved.r2) throw new Error('StorageModule: provider "r2" selected but no r2 options / R2_* env set.');
+      return new S3Storage(r2ToS3Options(resolved.r2));
+    case "bunny":
+      if (!resolved.bunny)
+        throw new Error('StorageModule: provider "bunny" selected but no bunny options / BUNNY_* env set.');
+      return new BunnyStorage(resolved.bunny);
+    default:
+      throw new Error(`StorageModule: unknown provider "${resolved.provider}".`);
+  }
+}
+var StorageModule = class {
+  static forRoot(options = {}) {
+    const providers = [
+      { provide: STORAGE_OPTIONS, useValue: options },
+      { provide: STORAGE, useFactory: () => createStorageAdapter(options) }
+    ];
+    return { module: StorageModule, providers, exports: [STORAGE, STORAGE_OPTIONS] };
+  }
+  static forRootAsync(config) {
+    const providers = [
+      {
+        provide: STORAGE_OPTIONS,
+        useFactory: config.useFactory,
+        inject: config.inject ?? []
+      },
+      {
+        provide: STORAGE,
+        useFactory: (options) => createStorageAdapter(options),
+        inject: [STORAGE_OPTIONS]
+      }
+    ];
+    return {
+      module: StorageModule,
+      imports: config.imports ?? [],
+      providers,
+      exports: [STORAGE, STORAGE_OPTIONS]
+    };
+  }
+};
+StorageModule = __decorateClass([
+  Global(),
+  Module({})
+], StorageModule);
+export {
+  BunnyStorage,
+  LocalStorage,
+  S3Storage,
+  STORAGE,
+  STORAGE_OPTIONS,
+  StorageModule,
+  createStorageAdapter,
+  r2ToS3Options,
+  resolveStorageOptions
+};

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,47 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type StorageOptions, type S3StorageOptions } from './storage.options.js';
+import { type StoragePort } from './storage.port.js';
+/** Cloudflare R2 is S3-compatible: map its options onto an S3 client pointed at R2. */
+export declare function r2ToS3Options(r2: {
+    accountId: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    publicBaseUrl?: string;
+}): S3StorageOptions;
+/**
+ * Merge explicit options with environment variables. Anything not passed in code
+ * falls back to the env, so `StorageModule.forRoot()` with no arguments works when
+ * the environment is configured.
+ *
+ * Recognized vars: `STORAGE_PROVIDER`; local `STORAGE_LOCAL_ROOT`,
+ * `STORAGE_PUBLIC_BASE_URL`; s3 `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`,
+ * `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_PUBLIC_BASE_URL`,
+ * `S3_FORCE_PATH_STYLE`; r2 `R2_ACCOUNT_ID`, `R2_BUCKET`, `R2_ACCESS_KEY_ID`,
+ * `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_BASE_URL`; bunny `BUNNY_STORAGE_ZONE`,
+ * `BUNNY_API_KEY`, `BUNNY_REGION`, `BUNNY_PULL_ZONE_URL`, `BUNNY_TOKEN_SECURITY_KEY`.
+ */
+export declare function resolveStorageOptions(options?: StorageOptions): StorageOptions;
+/** Construct the adapter the options select, failing loudly on missing config. */
+export declare function createStorageAdapter(options: StorageOptions): StoragePort;
+/**
+ * Provider-agnostic file storage for NestJS. Register once in the root module and
+ * inject the port anywhere with `@Inject(STORAGE) storage: StoragePort`.
+ *
+ * ```ts
+ * StorageModule.forRoot({ provider: 'r2' })            // reads R2_* from env
+ * StorageModule.forRoot({ provider: 'bunny', bunny: { storageZone, apiKey, pullZoneUrl } })
+ * StorageModule.forRootAsync({ inject: [Config], useFactory: (c) => ({ provider: c.storageProvider }) })
+ * ```
+ *
+ * Switching providers is this one line — no call site changes, because everything
+ * depends on `StoragePort`, never on a concrete adapter.
+ */
+export declare class StorageModule {
+    static forRoot(options?: StorageOptions): DynamicModule;
+    static forRootAsync(config: {
+        imports?: any[];
+        inject?: any[];
+        useFactory: (...args: any[]) => StorageOptions | Promise<StorageOptions>;
+    }): DynamicModule;
+}

package/dist/storage/storage.options.d.ts

@@ -0,0 +1,79 @@
+/** DI token carrying the resolved {@link StorageOptions}. */
+export declare const STORAGE_OPTIONS: unique symbol;
+/** Which adapter backs the {@link StoragePort}. */
+export type StorageProvider = 'local' | 's3' | 'r2' | 'bunny';
+/** Local filesystem adapter — for development. Not for production. */
+export interface LocalStorageOptions {
+    /** Directory objects are written under. Created on demand. */
+    root: string;
+    /**
+     * Base URL that serves the files (including any global prefix), for `publicUrl`
+     * and `signedReadUrl`. Your app must actually serve `root` under this URL. If
+     * omitted, both return a `key`-relative path and the app resolves it.
+     */
+    publicBaseUrl?: string;
+}
+/** S3-compatible adapter. Covers AWS S3 and anything speaking the S3 API. */
+export interface S3StorageOptions {
+    bucket: string;
+    region?: string;
+    /** Custom endpoint for non-AWS S3 (MinIO, R2, …). Omit for AWS S3. */
+    endpoint?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Path-style addressing (`endpoint/bucket/key`) instead of virtual-host. MinIO needs this. */
+    forcePathStyle?: boolean;
+    /** Public base URL (a CDN or the bucket's website endpoint) for `publicUrl`. Omit for a private bucket. */
+    publicBaseUrl?: string;
+}
+/**
+ * Cloudflare R2. R2 speaks the S3 API, so under the hood this becomes an S3
+ * adapter pointed at `https://<accountId>.r2.cloudflarestorage.com` with region
+ * `auto`. Give it your R2 access key pair (not a Cloudflare API token).
+ */
+export interface R2StorageOptions {
+    accountId: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Your public R2.dev URL or a custom domain bound to the bucket, for `publicUrl`. */
+    publicBaseUrl?: string;
+}
+/**
+ * Bunny.net Storage. Objects live in a Storage Zone; they are served publicly
+ * through the Pull Zone bound to it.
+ */
+export interface BunnyStorageOptions {
+    /** Storage Zone name. */
+    storageZone: string;
+    /** Storage Zone password (the "password" / access key of the zone). */
+    apiKey: string;
+    /**
+     * Storage region hostname prefix: `''` (Falkenstein/default), `'ny'`, `'la'`,
+     * `'sg'`, `'syd'`, `'br'`, `'jh'`, `'uk'`, `'se'`, … Matches where you created
+     * the zone. Wrong region → 401.
+     */
+    region?: string;
+    /**
+     * Pull Zone URL that serves the files publicly, e.g.
+     * `https://my-zone.b-cdn.net`. Required for `publicUrl` and for `signedReadUrl`
+     * (Bunny signs Pull Zone URLs, not Storage URLs).
+     */
+    pullZoneUrl?: string;
+    /** Pull Zone "URL Token Authentication" key, to sign `signedReadUrl`. */
+    tokenSecurityKey?: string;
+}
+/**
+ * Storage configuration. `provider` chooses the adapter; only the matching
+ * option block is required. Any field can come from the environment instead —
+ * see `resolveStorageOptions` in `storage.module.ts` for the variable names —
+ * so `StorageModule.forRoot()` with no arguments works when the env is set.
+ */
+export interface StorageOptions {
+    /** Adapter to use. Falls back to the `STORAGE_PROVIDER` env var, then `'local'`. */
+    provider?: StorageProvider;
+    local?: LocalStorageOptions;
+    s3?: S3StorageOptions;
+    r2?: R2StorageOptions;
+    bunny?: BunnyStorageOptions;
+}