@visulima/storage 1.0.0-alpha.8 → 1.0.0

package/dist/storage/bunny/index.d.ts

@@ -0,0 +1,119 @@
+import { F as File, L as LocalMetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, d as FileInit, O as OperationOptions, e as FilePart, f as FileQuery, g as FileReturn, B as BaseStorage } from "../../packem_shared/storage.d-CEM1upWM.js";
+import 'node:stream';
+import { L as LocalMetaStorage } from "../../packem_shared/local-meta-storage.d-D9PBfkn6.js";
+import * as BunnyStorageSDK from '@bunny.net/storage-sdk';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class BunnyFile extends File {
+  /**
+  * SHA-256 checksum reported by Bunny Storage (when present on the
+  * stored object).
+  */
+  bunnyChecksum?: string;
+  /**
+  * Server-side path within the Storage Zone (always prefixed with `/`).
+  */
+  bunnyPath?: string;
+}
+declare class BunnyMetaStorage extends LocalMetaStorage<BunnyFile> {
+  constructor(config?: LocalMetaStorageOptions);
+}
+/**
+* Bunny Storage region code. Mirrors the SDK's `StorageRegion` enum values
+* (e.g. `"de"`, `"ny"`, `"syd"`).
+*/
+type BunnyStorageRegion = `${BunnyStorageSDK.regions.StorageRegion}`;
+/**
+* A connected Bunny Storage zone produced by
+* `BunnyStorageSDK.zone.connect_with_accesskey(...)`.
+*/
+type BunnyStorageClient = ReturnType<typeof BunnyStorageSDK.zone.connect_with_accesskey>;
+interface BunnyStorageOptions extends BaseStorageOptions {
+  /**
+  * Bunny Storage zone password / API access key. Falls back to
+  * `BUNNY_STORAGE_ACCESS_KEY`, then `BUNNY_ACCESS_KEY`, then the
+  * SDK-documented `STORAGE_ACCESS_KEY`. Ignored when `client` is supplied.
+  */
+  accessKey?: string;
+  /**
+  * Pre-built `StorageZone` instance. Use this to share an instance across
+  * adapters or inject test stubs. Mutually exclusive with `zone` /
+  * `accessKey` / `region`.
+  */
+  client?: BunnyStorageClient;
+  /**
+  * Configure metafiles storage for resumable-upload bookkeeping.
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+  /**
+  * Origin used to build URLs from `getReadUrl`, typically a Bunny Pull
+  * Zone or custom CDN hostname in front of the Storage Zone. When unset,
+  * `getReadUrl` throws because the Storage API requires an `AccessKey`
+  * header and has no signed-read URL primitive.
+  */
+  publicBaseUrl?: string;
+  /**
+  * Primary Bunny Storage region. Pass one of
+  * `BunnyStorageSDK.regions.StorageRegion.*`, e.g. `"de"`, `"ny"`, `"syd"`.
+  * Falls back to `BUNNY_STORAGE_REGION`, then `STORAGE_REGION`. Ignored
+  * when `client` is supplied.
+  */
+  region?: BunnyStorageRegion;
+  /**
+  * Bunny Storage zone name. Falls back to `BUNNY_STORAGE_ZONE`, then the
+  * SDK-documented `STORAGE_ZONE`. Ignored when `client` is supplied.
+  */
+  zone?: string;
+}
+/**
+* Bunny Storage backend.
+*
+* Uses `@bunny.net/storage-sdk`. Writes go through the Storage API with an `AccessKey` header; reads either go through `data()` (server-side fetch) or, when a public Pull Zone is configured, through `publicBaseUrl`.
+*
+* **Limitations**:
+*
+* - No native server-side `copy` — implemented as download + re-upload.
+* - No `signedUploadUrl` / presigned PUT — Bunny has no such primitive.
+* - `getReadUrl` requires `publicBaseUrl` (Pull Zone / CDN hostname) and returns an unsigned URL — Bunny has no signed-read URL primitive, so `expiresIn` is accepted for parity with other adapters but ignored.
+* - `getReadUrl` rejects `responseContentDisposition` — no override exists on Bunny Storage / Pull Zone URLs.
+* - `list` is non-recursive: `BunnyStorageSDK.file.list(client, "/")` returns only the immediate children of the zone root. Directory entries are filtered out client-side; the adapter does not descend.
+* - ⚠️ Per-operation `signal`/`timeout` are best-effort: the underlying SDK does not support request cancellation, so an in-flight call may complete server-side even after abort. `retries` is honored.
+*/
+declare class BunnyStorage extends BaseStorage<BunnyFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  protected meta: MetaStorage<BunnyFile>;
+  private readonly client;
+  private readonly publicBaseUrl;
+  private readonly zoneName;
+  constructor(config: BunnyStorageOptions);
+  override get raw(): BunnyStorageClient;
+  /** Name of the connected Bunny Storage zone. */
+  get zone(): string;
+  create(config: FileInit, _options?: OperationOptions): Promise<BunnyFile>;
+  write(part: FilePart | FileQuery | BunnyFile, options?: OperationOptions): Promise<BunnyFile>;
+  delete({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<BunnyFile>;
+  get({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FileReturn>;
+  copy(name: string, destination: string, options?: OperationOptions & {
+    storageClass?: string;
+  }): Promise<BunnyFile>;
+  move(name: string, destination: string, options?: OperationOptions): Promise<BunnyFile>;
+  override list(limit?: number, options?: OperationOptions): Promise<BunnyFile[]>;
+  override getReadUrl(key: string, options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  override getUploadUrl(_key: string, _options?: {
+    contentLength?: number;
+    contentType?: string;
+    expiresIn?: number;
+  }): Promise<string>;
+  private internalOnComplete;
+}
+export { BunnyFile, BunnyMetaStorage, BunnyStorage, type BunnyStorageClient, type BunnyStorageOptions, type BunnyStorageRegion };

package/dist/storage/bunny/index.js

@@ -0,0 +1 @@
+import{default as t}from"../../packem_shared/BunnyFile-BgEOlcYI.js";import{default as r}from"../../packem_shared/BunnyMetaStorage-DFwhEI9C.js";import{default as n}from"../../packem_shared/BunnyStorage-CILSK4_Z.js";export{t as BunnyFile,r as BunnyMetaStorage,n as BunnyStorage};

package/dist/storage/cloudinary/index.d.ts

@@ -0,0 +1,121 @@
+import { F as File, L as LocalMetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, d as FileInit, O as OperationOptions, e as FilePart, f as FileQuery, g as FileReturn, B as BaseStorage } from "../../packem_shared/storage.d-CEM1upWM.js";
+import 'node:stream';
+import { L as LocalMetaStorage } from "../../packem_shared/local-meta-storage.d-D9PBfkn6.js";
+import { v2 } from 'cloudinary';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class CloudinaryFile extends File {
+  bucket?: string;
+  path?: string;
+  publicUrl?: string;
+}
+declare class CloudinaryMetaStorage extends LocalMetaStorage<CloudinaryFile> {
+  constructor(config?: LocalMetaStorageOptions);
+}
+interface CloudinaryStorageOptions extends BaseStorageOptions {
+  /**
+  * Cloudinary API key. Ignored when `client` is supplied. Falls back to
+  * `CLOUDINARY_API_KEY`, or the credentials encoded in `CLOUDINARY_URL`.
+  */
+  apiKey?: string;
+  /**
+  * Cloudinary API secret. Ignored when `client` is supplied. Falls back to
+  * `CLOUDINARY_API_SECRET`, or the credentials encoded in `CLOUDINARY_URL`.
+  */
+  apiSecret?: string;
+  /**
+  * Pre-configured `cloudinary` namespace (the `v2` export). Mutually
+  * exclusive with `cloudName` + `apiKey` + `apiSecret`. When supplied the
+  * adapter skips `cloudinary.config()` and uses the instance as-is.
+  */
+  client?: typeof v2;
+  /**
+  * Cloudinary cloud name. Ignored when `client` is supplied. Falls back to
+  * `CLOUDINARY_CLOUD_NAME`, or the host segment of `CLOUDINARY_URL`.
+  */
+  cloudName?: string;
+  /**
+  * Default expiry, in seconds, for `getReadUrl` signed URLs on private or
+  * authenticated assets. Defaults to 3600 (1 hour).
+  */
+  defaultUrlExpiresIn?: number;
+  /**
+  * Configure metafiles storage. Used for TUS-style resumable upload
+  * bookkeeping. Defaults to {@link LocalMetaStorage} under the OS tmp
+  * directory.
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+  /**
+  * Cloudinary resource type. Use `"raw"` for arbitrary files, `"image"` or
+  * `"video"` for media that benefits from transformations. Defaults to
+  * `"raw"`.
+  */
+  resourceType?: "image" | "raw" | "video";
+  /**
+  * Generate `https://` delivery URLs. Defaults to `true`.
+  */
+  secure?: boolean;
+  /**
+  * Cloudinary delivery type. `"private"` and `"authenticated"` require a
+  * signed URL for delivery. Defaults to `"upload"`.
+  */
+  type?: "authenticated" | "private" | "upload";
+}
+/**
+* Cloudinary Storage backend.
+*
+* Single-shot uploads only — the adapter buffers the part stream and uploads
+* it in one request via `upload_stream`. Cloudinary has no simple presigned
+* `PUT` endpoint, so `getUploadUrl` is not implemented (the base default
+* throws `METHOD_NOT_ALLOWED`).
+* @example
+* ```ts
+* import { CloudinaryStorage } from "@visulima/storage/provider/cloudinary";
+*
+* const storage = new CloudinaryStorage({
+*   cloudName: process.env.CLOUDINARY_CLOUD_NAME,
+*   apiKey: process.env.CLOUDINARY_API_KEY,
+*   apiSecret: process.env.CLOUDINARY_API_SECRET,
+* });
+* ```
+* @remarks
+* - ⚠️ Per-operation `signal`/`timeout` are best-effort: the underlying SDK does not support request cancellation, so an in-flight call may complete server-side even after abort. `retries` is honored.
+*/
+declare class CloudinaryStorage extends BaseStorage<CloudinaryFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  protected meta: MetaStorage<CloudinaryFile>;
+  private readonly client;
+  private readonly defaultUrlExpiresIn;
+  private readonly deliveryType;
+  private readonly resourceType;
+  private readonly secure;
+  constructor(config: CloudinaryStorageOptions);
+  override get raw(): typeof v2;
+  create(config: FileInit, _options?: OperationOptions): Promise<CloudinaryFile>;
+  write(part: CloudinaryFile | FilePart | FileQuery, options?: OperationOptions): Promise<CloudinaryFile>;
+  delete({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<CloudinaryFile>;
+  override exists({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<boolean>;
+  get({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FileReturn>;
+  copy(name: string, destination: string, options?: OperationOptions & {
+    storageClass?: string;
+  }): Promise<CloudinaryFile>;
+  move(name: string, destination: string, options?: OperationOptions): Promise<CloudinaryFile>;
+  override list(limit?: number, options?: OperationOptions): Promise<CloudinaryFile[]>;
+  override getReadUrl(key: string, options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  private uploadBuffer;
+  private getMetaSafe;
+  private internalOnComplete;
+}
+export { CloudinaryFile, CloudinaryMetaStorage, CloudinaryStorage, type CloudinaryStorageOptions };

package/dist/storage/cloudinary/index.js

@@ -0,0 +1 @@
+import{default as r}from"../../packem_shared/CloudinaryFile-Bo5B-vM1.js";import{default as t}from"../../packem_shared/CloudinaryMetaStorage-D_vNzewL.js";import{default as d}from"../../packem_shared/CloudinaryStorage-DiCbdAi_.js";export{r as CloudinaryFile,t as CloudinaryMetaStorage,d as CloudinaryStorage};

package/dist/storage/dropbox/index.d.ts

@@ -0,0 +1,132 @@
+import { F as File, L as LocalMetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, d as FileInit, O as OperationOptions, e as FilePart, f as FileQuery, g as FileReturn, B as BaseStorage } from "../../packem_shared/storage.d-CEM1upWM.js";
+import 'node:stream';
+import { L as LocalMetaStorage } from "../../packem_shared/local-meta-storage.d-D9PBfkn6.js";
+import { Dropbox } from 'dropbox';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class DropboxFile extends File {
+  path?: string;
+  publicUrl?: string;
+  rev?: string;
+}
+declare class DropboxMetaStorage extends LocalMetaStorage<DropboxFile> {
+  constructor(config?: LocalMetaStorageOptions);
+}
+interface DropboxStorageOptions extends BaseStorageOptions {
+  /**
+  * Static or dynamic access token. Pass a string for a one-shot token, or
+  * a function returning a fresh token on each call. The adapter does not
+  * cache the result of a callable — your callable is responsible for
+  * caching/refresh.
+  */
+  accessToken?: string | (() => string | Promise<string>);
+  /**
+  * Dropbox app key (client_id). Required when `refreshToken` is set.
+  */
+  appKey?: string;
+  /**
+  * Dropbox app secret (client_secret). Required for confidential clients.
+  */
+  appSecret?: string;
+  /**
+  * Pre-built `Dropbox` client. Escape hatch for callers that already wire
+  * auth themselves (e.g. with team-space `pathRoot`, custom headers, or a
+  * shared `DropboxAuth`).
+  */
+  client?: Dropbox;
+  /**
+  * Default expiry, in seconds, for temporary download links from
+  * `getReadUrl()`. Capped at 14400 (4 hours, the Dropbox maximum).
+  * Defaults to 3600 (1 hour).
+  */
+  defaultUrlExpiresIn?: number;
+  /**
+  * Configure metafiles storage. Defaults to local tmp directory.
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+  /**
+  * When `true`, `getReadUrl` creates a public shared link instead of a
+  * temporary 4-hour link. The link is rewritten to `?dl=1` so it serves
+  * raw bytes directly.
+  */
+  publicByDefault?: boolean;
+  /**
+  * OAuth2 refresh token. When set, the adapter exchanges it for fresh
+  * access tokens at `https://api.dropboxapi.com/oauth2/token` and caches
+  * them until ~60s before expiry. Requires `appKey` (PKCE) or `appKey` +
+  * `appSecret` (confidential client).
+  */
+  refreshToken?: string;
+  /**
+  * Logical "bucket root" — virtual keys live under this folder path. Must
+  * already exist; the adapter does not create folders. Path is normalized:
+  * leading slash is added, trailing slashes stripped. Defaults to account
+  * root.
+  */
+  rootFolderPath?: string;
+}
+/**
+* Dropbox storage backend.
+*
+* Routes virtual keys onto Dropbox paths under `rootFolderPath`. Uploads use
+* the simple `filesUpload` endpoint up to 150 MB and switch to chunked
+* upload sessions above that threshold.
+*
+* **Auth precedence**:
+* 1. `client` (pre-built `Dropbox`)
+* 2. `accessToken` (string or `() => string | Promise&lt;string>`)
+* 3. `refreshToken` + `appKey` (+ optional `appSecret`)
+* 4. Env fallback: `DROPBOX_ACCESS_TOKEN`, or `DROPBOX_REFRESH_TOKEN` +
+*    `DROPBOX_APP_KEY` (+ optional `DROPBOX_APP_SECRET`)
+*
+* **Limitations**:
+* - `metadata` and `cacheControl` are not supported (Dropbox files have no
+*   native arbitrary-metadata field, and no HTTP cache-header overrides).
+* - `getUploadUrl` is not supported — Dropbox's `files/get_temporary_upload_link`
+*   requires a `POST` with raw body, which doesn't fit a presigned-PUT contract.
+* - `responseContentDisposition` is not supported on signed URLs.
+* - ⚠️ Per-operation `signal`/`timeout` are best-effort: the underlying SDK does not support request cancellation, so an in-flight call may complete server-side even after abort. `retries` is honored.
+*/
+declare class DropboxStorage extends BaseStorage<DropboxFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  protected meta: MetaStorage<DropboxFile>;
+  private readonly authHandle;
+  private readonly client;
+  private readonly defaultUrlExpiresIn;
+  private readonly publicByDefault;
+  private readonly rootFolderPath;
+  constructor(config: DropboxStorageOptions);
+  override get raw(): Dropbox;
+  create(config: FileInit, _options?: OperationOptions): Promise<DropboxFile>;
+  write(part: FilePart | FileQuery | DropboxFile, options?: OperationOptions): Promise<DropboxFile>;
+  delete({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<DropboxFile>;
+  get({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FileReturn>;
+  copy(name: string, destination: string, options?: OperationOptions & {
+    storageClass?: string;
+  }): Promise<DropboxFile>;
+  move(name: string, destination: string, options?: OperationOptions): Promise<DropboxFile>;
+  override list(limit?: number, options?: OperationOptions): Promise<DropboxFile[]>;
+  override getReadUrl(key: string, options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  override getUploadUrl(_key: string, _options?: {
+    contentLength?: number;
+    contentType?: string;
+    expiresIn?: number;
+  }): Promise<string>;
+  private keyToPath;
+  private pathToKey;
+  private uploadSimple;
+  private uploadSession;
+  private createPublicSharedLink;
+  private internalOnComplete;
+}
+export { DropboxFile, DropboxMetaStorage, DropboxStorage, type DropboxStorageOptions };

package/dist/storage/dropbox/index.js

@@ -0,0 +1 @@
+import{default as e}from"../../packem_shared/DropboxFile-BFb7eOzy.js";import{default as t}from"../../packem_shared/DropboxMetaStorage-DFwhEI9C.js";import{default as p}from"../../packem_shared/DropboxStorage-H8bd8hEz.js";export{e as DropboxFile,t as DropboxMetaStorage,p as DropboxStorage};

package/dist/storage/firebase/index.d.ts

@@ -0,0 +1,192 @@
+import { F as File, L as LocalMetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, d as FileInit, O as OperationOptions, e as FilePart, f as FileQuery, g as FileReturn, B as BaseStorage } from "../../packem_shared/storage.d-CEM1upWM.js";
+import 'node:stream';
+import { L as LocalMetaStorage } from "../../packem_shared/local-meta-storage.d-D9PBfkn6.js";
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class FirebaseFile extends File {
+  bucket?: string;
+  path?: string;
+  publicUrl?: string;
+}
+declare class FirebaseMetaStorage extends LocalMetaStorage<FirebaseFile> {
+  constructor(config?: LocalMetaStorageOptions);
+}
+/**
+* Minimal structural type for a `@google-cloud/storage` `File` as returned by
+* `firebase-admin`'s `getStorage(app).bucket().file()`. Declared locally so the
+* adapter type-checks without `firebase-admin` / `@google-cloud/storage`
+* installed (optional peer dependency).
+*/
+interface FirebaseGcsFile {
+  copy: (destination: FirebaseGcsFile | string) => Promise<unknown>;
+  delete: (options?: {
+    ignoreNotFound?: boolean;
+  }) => Promise<unknown>;
+  download: () => Promise<[Buffer]>;
+  exists: () => Promise<[boolean]>;
+  getMetadata: () => Promise<[FirebaseGcsFileMetadata]>;
+  getSignedUrl: (options: FirebaseSignedUrlOptions) => Promise<[string]>;
+  move: (destination: FirebaseGcsFile | string) => Promise<unknown>;
+  name: string;
+  save: (data: Buffer, options?: {
+    contentType?: string;
+    resumable?: boolean;
+  }) => Promise<unknown>;
+}
+interface FirebaseGcsFileMetadata {
+  contentType?: string;
+  etag?: string;
+  md5Hash?: string;
+  name?: string;
+  size?: number | string;
+  timeCreated?: string;
+  updated?: string;
+}
+interface FirebaseSignedUrlOptions {
+  action: "delete" | "read" | "resumable" | "write";
+  contentType?: string;
+  expires: Date | number | string;
+  version?: "v2" | "v4";
+}
+/**
+* Minimal structural type for a `@google-cloud/storage` `Bucket` as returned by
+* `firebase-admin`'s `getStorage(app).bucket()`.
+*/
+interface FirebaseBucket {
+  file: (key: string) => FirebaseGcsFile;
+  getFiles: (options?: {
+    maxResults?: number;
+    prefix?: string;
+  }) => Promise<[FirebaseGcsFile[]]>;
+  name?: string;
+}
+/**
+* Structural type for a `firebase-admin` `App`. Only the shape needed by
+* `getStorage()` is declared.
+*/
+interface FirebaseApp {
+  name: string;
+}
+interface FirebaseStorageOptions extends BaseStorageOptions {
+  /**
+  * Pre-built `firebase-admin` {@link FirebaseApp} or an already-built
+  * `@google-cloud/storage` `Bucket`. When a Bucket is supplied (detected by
+  * the presence of `.file()` and `.getFiles()`), it is used directly and no
+  * Firebase app is initialized. Use this to share an instance, run tests, or
+  * customize the underlying GCS client.
+  */
+  app?: FirebaseApp | FirebaseBucket;
+  /**
+  * Named `firebase-admin` app to reuse/create. Defaults to the SDK default
+  * app. Ignored when `app` is supplied.
+  */
+  appName?: string;
+  /**
+  * Storage bucket name (e.g. `my-project.appspot.com`). Falls back to
+  * `FIREBASE_STORAGE_BUCKET`. Required unless a pre-built Bucket is passed
+  * via `app`.
+  */
+  bucket?: string;
+  /**
+  * Service-account credentials. Ignored when `app` is supplied or
+  * `serviceAccountPath` is used. Falls back to `FIREBASE_CLIENT_EMAIL` /
+  * `FIREBASE_PRIVATE_KEY`.
+  */
+  credentials?: {
+    clientEmail: string;
+    privateKey: string;
+  };
+  /**
+  * Default expiry, in seconds, for `getReadUrl` / `getUploadUrl` signed
+  * URLs. Defaults to 3600 (1 hour).
+  */
+  defaultUrlExpiresIn?: number;
+  /**
+  * Configure metafiles storage. Used for TUS-style resumable upload
+  * bookkeeping. Defaults to {@link LocalMetaStorage} under the OS tmp
+  * directory.
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+  /**
+  * Google Cloud project id. Falls back to `FIREBASE_PROJECT_ID`,
+  * `GOOGLE_CLOUD_PROJECT`, or `GCLOUD_PROJECT`.
+  */
+  projectId?: string;
+  /**
+  * When set, `getReadUrl` returns `${publicBaseUrl}/${key}` instead of a
+  * signed URL. Use for objects served through a public bucket or CDN.
+  */
+  publicBaseUrl?: string;
+  /**
+  * Path to a service-account JSON key file. Ignored when `app` or
+  * `credentials` is supplied. Falls back to
+  * `GOOGLE_APPLICATION_CREDENTIALS`.
+  */
+  serviceAccountPath?: string;
+}
+/**
+* Firebase Storage backend.
+*
+* Firebase Storage is a Google Cloud Storage bucket under the hood; this
+* adapter resolves a `firebase-admin` app, obtains its `@google-cloud/storage`
+* `Bucket`, and drives single-shot uploads through it. The part stream is
+* buffered and uploaded in one `file.save()` call. Use `getUploadUrl` for
+* direct-from-client large transfers.
+* @example
+* ```ts
+* import { FirebaseStorage } from "@visulima/storage/provider/firebase";
+*
+* const storage = new FirebaseStorage({
+*   bucket: "my-project.appspot.com",
+*   projectId: process.env.FIREBASE_PROJECT_ID,
+*   credentials: {
+*     clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
+*     privateKey: process.env.FIREBASE_PRIVATE_KEY,
+*   },
+* });
+* ```
+* @remarks
+* - ⚠️ Per-operation `signal`/`timeout` are best-effort: the underlying SDK does not support request cancellation, so an in-flight call may complete server-side even after abort. `retries` is honored.
+*/
+declare class FirebaseStorage extends BaseStorage<FirebaseFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  protected meta: MetaStorage<FirebaseFile>;
+  private readonly bucket;
+  private readonly bucketName;
+  private readonly defaultUrlExpiresIn;
+  private readonly publicBaseUrl?;
+  constructor(config: FirebaseStorageOptions);
+  override get raw(): FirebaseBucket;
+  create(config: FileInit, _options?: OperationOptions): Promise<FirebaseFile>;
+  write(part: FilePart | FileQuery | FirebaseFile, options?: OperationOptions): Promise<FirebaseFile>;
+  delete({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FirebaseFile>;
+  override exists({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<boolean>;
+  get({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FileReturn>;
+  copy(name: string, destination: string, options?: OperationOptions & {
+    storageClass?: string;
+  }): Promise<FirebaseFile>;
+  move(name: string, destination: string, options?: OperationOptions): Promise<FirebaseFile>;
+  override list(limit?: number, options?: OperationOptions): Promise<FirebaseFile[]>;
+  override getReadUrl(key: string, options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  override getUploadUrl(key: string, options?: {
+    contentLength?: number;
+    contentType?: string;
+    expiresIn?: number;
+  }): Promise<string>;
+  private static resolveApp;
+  private getMetaSafe;
+  private internalOnComplete;
+}
+export { FirebaseFile, FirebaseMetaStorage, FirebaseStorage, type FirebaseStorageOptions };

package/dist/storage/firebase/index.js

@@ -0,0 +1 @@
+import{default as r}from"../../packem_shared/FirebaseFile-BLaBxa2A.js";import{default as o}from"../../packem_shared/FirebaseMetaStorage-D_vNzewL.js";import{default as s}from"../../packem_shared/FirebaseStorage-Dgk4XyMr.js";export{r as FirebaseFile,o as FirebaseMetaStorage,s as FirebaseStorage};

package/dist/storage/ftp/index.d.ts

@@ -0,0 +1,91 @@
+import { F as File, L as LocalMetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, d as FileInit, O as OperationOptions, e as FilePart, f as FileQuery, g as FileReturn, B as BaseStorage } from "../../packem_shared/storage.d-CEM1upWM.js";
+import 'node:stream';
+import { L as LocalMetaStorage } from "../../packem_shared/local-meta-storage.d-D9PBfkn6.js";
+import { AccessOptions } from 'basic-ftp';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class FtpFile extends File {
+  path?: string;
+}
+declare class FtpMetaStorage extends LocalMetaStorage<FtpFile> {
+  constructor(config?: LocalMetaStorageOptions);
+}
+interface FtpStorageOptions extends BaseStorageOptions {
+  /**
+  * `basic-ftp` access options (`host`, `port`, `user`, `password`,
+  * `secure` for FTPS, …). A fresh connection is opened and closed around
+  * every storage operation — an FTP control connection is single-session,
+  * so the adapter does not pool connections.
+  */
+  connection: AccessOptions;
+  /**
+  * Configure metafile storage. FTP has no native arbitrary-metadata
+  * field, so upload metadata is stored as sidecar JSON on the local
+  * disk (defaults to the OS temp directory).
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+  /**
+  * Logical "bucket root" — virtual keys live under this remote directory.
+  * The adapter creates intermediate directories on write. Leading/trailing
+  * slashes are normalized. Defaults to the connection's working directory.
+  */
+  rootFolderPath?: string;
+}
+/**
+* FTP / FTPS storage backend (built on `basic-ftp`).
+*
+* Routes virtual keys onto remote paths under `rootFolderPath`. FTP has no
+* native metadata store, so upload metadata is kept as sidecar JSON on the
+* local disk (see `FtpMetaStorage`).
+*
+* A fresh FTP connection is opened and closed around every operation: an FTP
+* control connection is single-session, so the adapter does not pool
+* connections.
+*
+* **Limitations**:
+* - `write()` buffers the full part in memory before uploading (no remote append), so chunked uploads overwrite rather than append.
+* - `getReadUrl` / `getUploadUrl` are not supported — FTP has no signed-URL concept.
+*/
+declare class FtpStorage extends BaseStorage<FtpFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  override readonly supportsRange: boolean;
+  protected meta: MetaStorage<FtpFile>;
+  private readonly connection;
+  private readonly rootFolderPath;
+  constructor(config: FtpStorageOptions);
+  create(config: FileInit, _options?: OperationOptions): Promise<FtpFile>;
+  write(part: FilePart | FileQuery | FtpFile, options?: OperationOptions): Promise<FtpFile>;
+  get({
+    id
+  }: FileQuery, options?: OperationOptions & {
+    range?: {
+      end?: number;
+      start: number;
+    };
+  }): Promise<FileReturn>;
+  delete({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<FtpFile>;
+  copy(name: string, destination: string, options?: OperationOptions & {
+    storageClass?: string;
+  }): Promise<FtpFile>;
+  move(name: string, destination: string, options?: OperationOptions): Promise<FtpFile>;
+  override list(_limit?: number, options?: OperationOptions): Promise<FtpFile[]>;
+  override exists({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<boolean>;
+  private walkList;
+  /**
+  * Opens a fresh single-session FTP connection for one operation. `basic-ftp`
+  * has no `AbortSignal` hook, so cancellation is best-effort: an abort
+  * destroys the control/data connection via `client.close()`, which rejects
+  * any in-flight transfer. The rejection is normalized to an `AbortError`.
+  */
+  private run;
+  private ensureRemoteDirectory;
+  private keyToPath;
+  private pathToKey;
+}
+export { FtpFile, FtpMetaStorage, FtpStorage, type FtpStorageOptions };

package/dist/storage/ftp/index.js

@@ -0,0 +1 @@
+import{default as a}from"../../packem_shared/FtpFile-ClWDYnt2.js";import{default as r}from"../../packem_shared/FtpMetaStorage-DFwhEI9C.js";import{default as p}from"../../packem_shared/FtpStorage-g_DjiR-C.js";export{a as FtpFile,r as FtpMetaStorage,p as FtpStorage};