@cubis/vfsclient 0.0.1

package/dist/index.cjs

@@ -0,0 +1,1577 @@
+'use strict';
+
+// src/types/errors.ts
+var VFSError = class _VFSError extends Error {
+  status;
+  code;
+  problem;
+  headers;
+  constructor(message, options) {
+    super(message);
+    this.name = "VFSError";
+    this.status = options?.status ?? 500;
+    this.code = options?.code;
+    this.problem = options?.problem;
+    this.headers = options?.headers;
+    if (options?.cause) {
+      this.cause = options.cause;
+    }
+    Object.setPrototypeOf(this, _VFSError.prototype);
+  }
+  /**
+   * Helper to check if error is a specific HTTP status code.
+   */
+  is(status) {
+    return this.status === status;
+  }
+};
+
+// src/http/error.ts
+async function parseHttpError(res) {
+  const status = res.status;
+  const contentType = res.headers.get("content-type") || "";
+  let errorMessage = res.statusText || `Request failed with status ${status}`;
+  let problemDetails;
+  let code;
+  try {
+    if (contentType.includes("application/json") || contentType.includes("application/problem+json")) {
+      const json = await res.json();
+      if (json && typeof json === "object") {
+        problemDetails = json;
+        if (problemDetails.detail) {
+          errorMessage = problemDetails.detail;
+        } else if (problemDetails.title) {
+          errorMessage = problemDetails.title;
+        } else if (json.error) {
+          errorMessage = json.error;
+        } else if (json.message) {
+          errorMessage = json.message;
+        }
+        if (problemDetails.extensions?.code && typeof problemDetails.extensions.code === "string") {
+          code = problemDetails.extensions.code;
+        }
+      }
+    } else {
+      const text = await res.text();
+      if (text) {
+        errorMessage = text;
+      }
+    }
+  } catch {
+  }
+  return new VFSError(errorMessage, {
+    status,
+    code,
+    problem: problemDetails,
+    headers: res.headers
+  });
+}
+
+// src/http/client.ts
+var HttpClient = class {
+  endpoint;
+  apiKey;
+  apiHash;
+  defaultTimeout;
+  fetchImpl;
+  debug;
+  maxRetries;
+  retryDelay;
+  retryOnStatus;
+  constructor(options) {
+    if (!options.endpoint) {
+      throw new VFSError("Endpoint URL is required", { status: 400 });
+    }
+    this.endpoint = options.endpoint.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.apiHash = options.apiHash;
+    this.defaultTimeout = options.timeout ?? 3e4;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof options.debug === "function") {
+      this.debug = options.debug;
+    } else if (options.debug === true) {
+      this.debug = (msg, ...args) => console.debug(`[VFSClient] ${msg}`, ...args);
+    }
+    this.maxRetries = options.retry?.maxRetries ?? 2;
+    this.retryDelay = options.retry?.retryDelay ?? 500;
+    this.retryOnStatus = options.retry?.retryOnStatus ?? [502, 503, 504];
+  }
+  getEndpoint() {
+    return this.endpoint;
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  getApiHash() {
+    return this.apiHash;
+  }
+  buildUrl(path, params) {
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${this.endpoint}${cleanPath}`);
+    if (params) {
+      for (const [key, val] of Object.entries(params)) {
+        if (val !== void 0 && val !== null) {
+          url.searchParams.append(key, String(val));
+        }
+      }
+    }
+    return url.toString();
+  }
+  buildHeaders(customHeaders, skipAuth) {
+    const headers = new Headers();
+    if (!skipAuth) {
+      if (this.apiKey) {
+        headers.set("x-api-key", this.apiKey);
+      }
+      if (this.apiHash) {
+        headers.set("x-api-hash", this.apiHash);
+      }
+    }
+    if (customHeaders) {
+      for (const [key, value] of Object.entries(customHeaders)) {
+        headers.set(key, value);
+      }
+    }
+    return headers;
+  }
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.params);
+    const headers = this.buildHeaders(options.headers, options.skipAuth);
+    const timeoutMs = options.timeout ?? this.defaultTimeout;
+    let attempt = 0;
+    let lastError;
+    while (attempt <= this.maxRetries) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error("Request timed out")), timeoutMs);
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => controller.abort(options.signal?.reason), { once: true });
+      }
+      this.debug?.(`${method} ${url} (Attempt ${attempt + 1}/${this.maxRetries + 1})`);
+      try {
+        const res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: options.body,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+          if (attempt < this.maxRetries && this.retryOnStatus.includes(res.status)) {
+            attempt++;
+            const backoff = this.retryDelay * Math.pow(2, attempt - 1);
+            this.debug?.(`HTTP ${res.status} on ${method} ${url}. Retrying in ${backoff}ms...`);
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+            continue;
+          }
+          throw await parseHttpError(res);
+        }
+        let data;
+        const contentType = res.headers.get("content-type") || "";
+        if (contentType.includes("application/json")) {
+          data = await res.json();
+        } else if (contentType.includes("text/")) {
+          data = await res.text();
+        } else {
+          data = res;
+        }
+        let totalCount;
+        const totalCountHeader = res.headers.get("x-total-count");
+        if (totalCountHeader) {
+          const parsed = parseInt(totalCountHeader, 10);
+          if (!isNaN(parsed)) {
+            totalCount = parsed;
+          }
+        }
+        return {
+          data,
+          status: res.status,
+          statusText: res.statusText,
+          headers: res.headers,
+          totalCount
+        };
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof VFSError) {
+          throw err;
+        }
+        lastError = err;
+        const isAbort = options.signal?.aborted;
+        if (isAbort) {
+          throw new VFSError("Request was aborted by caller", { status: 499, cause: err });
+        }
+        if (attempt < this.maxRetries) {
+          attempt++;
+          const backoff = this.retryDelay * Math.pow(2, attempt - 1);
+          this.debug?.(`Network error on ${method} ${url}. Retrying in ${backoff}ms...`, err);
+          await new Promise((resolve) => setTimeout(resolve, backoff));
+          continue;
+        }
+        throw new VFSError(err instanceof Error ? err.message : "Network request failed", {
+          status: 0,
+          cause: err
+        });
+      }
+    }
+    throw lastError instanceof VFSError ? lastError : new VFSError("Request failed after retries", { status: 500, cause: lastError });
+  }
+  get(path, options) {
+    return this.request("GET", path, options);
+  }
+  post(path, body, options) {
+    return this.request("POST", path, { ...options, body });
+  }
+  put(path, body, options) {
+    return this.request("PUT", path, { ...options, body });
+  }
+  delete(path, options) {
+    return this.request("DELETE", path, options);
+  }
+  /**
+   * Fetches raw Response object directly (useful for streaming file downloads).
+   */
+  async fetchRaw(path, options = {}) {
+    const url = this.buildUrl(path, options.params);
+    const headers = this.buildHeaders(options.headers, options.skipAuth);
+    const timeoutMs = options.timeout ?? this.defaultTimeout;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("Request timed out")), timeoutMs);
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => controller.abort(options.signal?.reason), { once: true });
+    }
+    try {
+      const res = await this.fetchImpl(url, {
+        method: "GET",
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+      if (!res.ok) {
+        throw await parseHttpError(res);
+      }
+      return res;
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof VFSError) {
+        throw err;
+      }
+      throw new VFSError(err instanceof Error ? err.message : "Download failed", {
+        status: 0,
+        cause: err
+      });
+    }
+  }
+};
+
+// src/cache/memory.ts
+var MemoryCacheAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  maxItems;
+  defaultTTL;
+  constructor(options = {}) {
+    this.maxItems = options.maxItems ?? 200;
+    this.defaultTTL = options.defaultTTL ?? 3600;
+  }
+  isExpired(entry) {
+    if (!entry.expiresAt) return false;
+    return Date.now() > entry.expiresAt;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (this.isExpired(entry)) {
+      this.store.delete(key);
+      return null;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry;
+  }
+  set(key, entry, ttlSeconds) {
+    const ttl = ttlSeconds ?? this.defaultTTL;
+    const expiresAt = ttl > 0 ? Date.now() + ttl * 1e3 : void 0;
+    const clonedEntry = {
+      ...entry,
+      expiresAt
+    };
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    } else if (this.store.size >= this.maxItems) {
+      const oldestKey = this.store.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.store.delete(oldestKey);
+      }
+    }
+    this.store.set(key, clonedEntry);
+  }
+  delete(key) {
+    return this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+  has(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    if (this.isExpired(entry)) {
+      this.store.delete(key);
+      return false;
+    }
+    return true;
+  }
+  size() {
+    return this.store.size;
+  }
+};
+
+// src/cache/browser.ts
+var BrowserCacheAdapter = class {
+  cacheName;
+  defaultTTL;
+  fallback;
+  constructor(options = {}) {
+    this.cacheName = options.cacheName ?? "vfs-client-cache-v1";
+    this.defaultTTL = options.defaultTTL ?? 3600;
+    this.fallback = new MemoryCacheAdapter({ defaultTTL: this.defaultTTL });
+  }
+  isAvailable() {
+    return typeof window !== "undefined" && typeof window.caches !== "undefined";
+  }
+  urlForKey(key) {
+    return `https://vfs-cache.internal/${encodeURIComponent(key)}`;
+  }
+  async get(key) {
+    if (!this.isAvailable()) {
+      return this.fallback.get(key);
+    }
+    try {
+      const cache = await window.caches.open(this.cacheName);
+      const res = await cache.match(this.urlForKey(key));
+      if (!res) return null;
+      const expiresHeader = res.headers.get("x-vfs-expires-at");
+      if (expiresHeader) {
+        const expiresAt2 = parseInt(expiresHeader, 10);
+        if (!isNaN(expiresAt2) && Date.now() > expiresAt2) {
+          await cache.delete(this.urlForKey(key));
+          return null;
+        }
+      }
+      const buffer = await res.arrayBuffer();
+      const contentType = res.headers.get("content-type") || void 0;
+      const name = res.headers.get("x-vfs-name") || void 0;
+      const hash = res.headers.get("x-vfs-hash") || void 0;
+      const createdAtHeader = res.headers.get("x-vfs-created-at");
+      const createdAt = createdAtHeader ? parseInt(createdAtHeader, 10) : Date.now();
+      const expiresAt = expiresHeader ? parseInt(expiresHeader, 10) : void 0;
+      return {
+        data: new Uint8Array(buffer),
+        contentType,
+        name,
+        size: buffer.byteLength,
+        hash,
+        createdAt,
+        expiresAt
+      };
+    } catch {
+      return this.fallback.get(key);
+    }
+  }
+  async set(key, entry, ttlSeconds) {
+    if (!this.isAvailable()) {
+      this.fallback.set(key, entry, ttlSeconds);
+      return;
+    }
+    try {
+      const ttl = ttlSeconds ?? this.defaultTTL;
+      const expiresAt = ttl > 0 ? Date.now() + ttl * 1e3 : void 0;
+      const headers = new Headers();
+      if (entry.contentType) headers.set("content-type", entry.contentType);
+      if (entry.name) headers.set("x-vfs-name", entry.name);
+      if (entry.hash) headers.set("x-vfs-hash", entry.hash);
+      headers.set("x-vfs-created-at", String(entry.createdAt));
+      if (expiresAt) headers.set("x-vfs-expires-at", String(expiresAt));
+      const response = new Response(entry.data, { headers });
+      const cache = await window.caches.open(this.cacheName);
+      await cache.put(this.urlForKey(key), response);
+    } catch {
+      this.fallback.set(key, entry, ttlSeconds);
+    }
+  }
+  async delete(key) {
+    if (!this.isAvailable()) {
+      return this.fallback.delete(key);
+    }
+    try {
+      const cache = await window.caches.open(this.cacheName);
+      return await cache.delete(this.urlForKey(key));
+    } catch {
+      return this.fallback.delete(key);
+    }
+  }
+  async clear() {
+    if (!this.isAvailable()) {
+      this.fallback.clear();
+      return;
+    }
+    try {
+      await window.caches.delete(this.cacheName);
+    } catch {
+      this.fallback.clear();
+    }
+  }
+  async has(key) {
+    const entry = await this.get(key);
+    return entry !== null;
+  }
+};
+
+// src/cache/filesystem.ts
+var FileSystemCacheAdapter = class {
+  cacheDir;
+  defaultTTL;
+  fallback;
+  isNodeEnv;
+  constructor(options = {}) {
+    this.cacheDir = options.cacheDir ?? "./.vfs-cache";
+    this.defaultTTL = options.defaultTTL ?? 3600;
+    this.fallback = new MemoryCacheAdapter({ defaultTTL: this.defaultTTL });
+    this.isNodeEnv = typeof process !== "undefined" && Boolean(process.versions?.node || process.versions?.bun);
+  }
+  sanitizeKey(key) {
+    return encodeURIComponent(key).replace(/[*?:<>|"/\\%]/g, "_");
+  }
+  async getFs() {
+    if (!this.isNodeEnv) return null;
+    try {
+      const fs = await import('fs/promises');
+      const path = await import('path');
+      return { fs, path };
+    } catch {
+      return null;
+    }
+  }
+  async ensureDir() {
+    const mods = await this.getFs();
+    if (!mods) return false;
+    try {
+      await mods.fs.mkdir(this.cacheDir, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async get(key) {
+    const mods = await this.getFs();
+    if (!mods) return this.fallback.get(key);
+    const safeKey = this.sanitizeKey(key);
+    const dataPath = mods.path.join(this.cacheDir, `${safeKey}.bin`);
+    const metaPath = mods.path.join(this.cacheDir, `${safeKey}.json`);
+    try {
+      const metaRaw = await mods.fs.readFile(metaPath, "utf8");
+      const meta = JSON.parse(metaRaw);
+      if (meta.expiresAt && Date.now() > meta.expiresAt) {
+        await Promise.allSettled([mods.fs.unlink(dataPath), mods.fs.unlink(metaPath)]);
+        return null;
+      }
+      const buffer = await mods.fs.readFile(dataPath);
+      return {
+        data: new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength),
+        contentType: meta.contentType,
+        name: meta.name,
+        size: meta.size,
+        hash: meta.hash,
+        createdAt: meta.createdAt,
+        expiresAt: meta.expiresAt
+      };
+    } catch {
+      return null;
+    }
+  }
+  async set(key, entry, ttlSeconds) {
+    const mods = await this.getFs();
+    if (!mods) {
+      this.fallback.set(key, entry, ttlSeconds);
+      return;
+    }
+    if (!await this.ensureDir()) {
+      this.fallback.set(key, entry, ttlSeconds);
+      return;
+    }
+    const ttl = ttlSeconds ?? this.defaultTTL;
+    const expiresAt = ttl > 0 ? Date.now() + ttl * 1e3 : void 0;
+    const safeKey = this.sanitizeKey(key);
+    const dataPath = mods.path.join(this.cacheDir, `${safeKey}.bin`);
+    const metaPath = mods.path.join(this.cacheDir, `${safeKey}.json`);
+    const meta = {
+      contentType: entry.contentType,
+      name: entry.name,
+      size: entry.size,
+      hash: entry.hash,
+      createdAt: entry.createdAt,
+      expiresAt
+    };
+    try {
+      await Promise.all([
+        mods.fs.writeFile(dataPath, entry.data),
+        mods.fs.writeFile(metaPath, JSON.stringify(meta), "utf8")
+      ]);
+    } catch {
+      this.fallback.set(key, entry, ttlSeconds);
+    }
+  }
+  async delete(key) {
+    const mods = await this.getFs();
+    if (!mods) return this.fallback.delete(key);
+    const safeKey = this.sanitizeKey(key);
+    const dataPath = mods.path.join(this.cacheDir, `${safeKey}.bin`);
+    const metaPath = mods.path.join(this.cacheDir, `${safeKey}.json`);
+    try {
+      await Promise.allSettled([mods.fs.unlink(dataPath), mods.fs.unlink(metaPath)]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async clear() {
+    const mods = await this.getFs();
+    if (!mods) {
+      this.fallback.clear();
+      return;
+    }
+    try {
+      const files = await mods.fs.readdir(this.cacheDir);
+      await Promise.allSettled(files.map((file) => mods.fs.unlink(mods.path.join(this.cacheDir, file))));
+    } catch {
+      this.fallback.clear();
+    }
+  }
+  async has(key) {
+    const entry = await this.get(key);
+    return entry !== null;
+  }
+};
+
+// src/cache/factory.ts
+function createDefaultCache() {
+  if (typeof window !== "undefined" && typeof window.caches !== "undefined") {
+    return new BrowserCacheAdapter();
+  }
+  if (typeof process !== "undefined" && (process.versions?.node || process.versions?.bun)) {
+    return new FileSystemCacheAdapter();
+  }
+  return new MemoryCacheAdapter();
+}
+
+// src/crypto/hash.ts
+function bufferToHex(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+async function calculateSHA256(data) {
+  let bytes;
+  if (typeof data === "string") {
+    bytes = new TextEncoder().encode(data);
+  } else if (data instanceof Uint8Array) {
+    bytes = data;
+  } else {
+    bytes = new Uint8Array(data);
+  }
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle?.digest) {
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return bufferToHex(hashBuffer);
+  }
+  try {
+    const nodeCrypto = await import('crypto');
+    return nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+  } catch {
+    throw new Error("No crypto implementation found in current environment for SHA-256");
+  }
+}
+async function calculateBlobSHA256(blob) {
+  const arrayBuffer = await blob.arrayBuffer();
+  return calculateSHA256(arrayBuffer);
+}
+
+// src/upload/normalizer.ts
+function guessContentType(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "png":
+      return "image/png";
+    case "gif":
+      return "image/gif";
+    case "webp":
+      return "image/webp";
+    case "svg":
+      return "image/svg+xml";
+    case "pdf":
+      return "application/pdf";
+    case "json":
+      return "application/json";
+    case "txt":
+      return "text/plain";
+    case "html":
+      return "text/html";
+    case "csv":
+      return "text/csv";
+    case "zip":
+      return "application/zip";
+    case "tar":
+      return "application/x-tar";
+    case "gz":
+      return "application/gzip";
+    case "mp4":
+      return "video/mp4";
+    case "mp3":
+      return "audio/mpeg";
+    default:
+      return "application/octet-stream";
+  }
+}
+async function normalizeUploadInput(input) {
+  const file = input.file;
+  let bytes = new Uint8Array(0);
+  let name = input.name || "unnamed_file";
+  let contentType = input.contentType;
+  if (typeof File !== "undefined" && file instanceof File) {
+    name = input.name || file.name;
+    contentType = contentType || file.type || guessContentType(name);
+    const arrayBuffer = await file.arrayBuffer();
+    bytes = new Uint8Array(arrayBuffer);
+  } else if (typeof Blob !== "undefined" && file instanceof Blob) {
+    contentType = contentType || file.type || guessContentType(name);
+    const arrayBuffer = await file.arrayBuffer();
+    bytes = new Uint8Array(arrayBuffer);
+  } else if (file instanceof Uint8Array) {
+    bytes = file;
+    contentType = contentType || guessContentType(name);
+  } else if (file instanceof ArrayBuffer) {
+    bytes = new Uint8Array(file);
+    contentType = contentType || guessContentType(name);
+  } else if (typeof ReadableStream !== "undefined" && file instanceof ReadableStream) {
+    const reader = file.getReader();
+    const chunks = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) chunks.push(value);
+    }
+    const totalLength = chunks.reduce((acc, c) => acc + c.length, 0);
+    bytes = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    contentType = contentType || guessContentType(name);
+  } else if (typeof file === "object" && file !== null && "on" in file && typeof file.pipe === "function") {
+    const chunks = [];
+    await new Promise((resolve, reject) => {
+      file.on("data", (chunk) => {
+        if (typeof chunk === "string") {
+          chunks.push(new TextEncoder().encode(chunk));
+        } else if (chunk instanceof Uint8Array) {
+          chunks.push(chunk);
+        }
+      });
+      file.on("end", () => resolve());
+      file.on("error", (err) => reject(err));
+    });
+    const totalLength = chunks.reduce((acc, c) => acc + c.length, 0);
+    bytes = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    contentType = contentType || guessContentType(name);
+  } else if (typeof file === "string") {
+    const isNode = typeof process !== "undefined" && Boolean(process.versions?.node || process.versions?.bun);
+    let readFromFile = false;
+    if (isNode) {
+      try {
+        const fs = await import('fs/promises');
+        const path = await import('path');
+        const stat = await fs.stat(file);
+        if (stat.isFile()) {
+          const buf = await fs.readFile(file);
+          bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+          name = input.name || path.basename(file);
+          contentType = contentType || guessContentType(name);
+          readFromFile = true;
+        }
+      } catch {
+      }
+    }
+    if (!readFromFile) {
+      if (file.startsWith("data:")) {
+        const commaIdx = file.indexOf(",");
+        if (commaIdx !== -1) {
+          const mimeMatch = file.slice(0, commaIdx).match(/data:(.*?);/);
+          if (mimeMatch && !contentType) {
+            contentType = mimeMatch[1];
+          }
+          const base64Data = file.slice(commaIdx + 1);
+          const binaryStr = atob(base64Data);
+          bytes = new Uint8Array(binaryStr.length);
+          for (let i = 0; i < binaryStr.length; i++) {
+            bytes[i] = binaryStr.charCodeAt(i);
+          }
+        } else {
+          bytes = new TextEncoder().encode(file);
+        }
+      } else {
+        bytes = new TextEncoder().encode(file);
+      }
+      contentType = contentType || guessContentType(name);
+    }
+  } else {
+    throw new VFSError("Unsupported file input type for upload", { status: 400 });
+  }
+  const hash = input.fileHash || await calculateSHA256(bytes);
+  return {
+    bytes,
+    name,
+    size: bytes.byteLength,
+    contentType: contentType || "application/octet-stream",
+    hash
+  };
+}
+
+// src/upload/preflight.ts
+async function executePreflight(http, req, signal) {
+  try {
+    const res = await http.post("/api/upload/preflight", JSON.stringify(req), {
+      headers: { "Content-Type": "application/json" },
+      signal
+    });
+    return res.data;
+  } catch (err) {
+    if (err instanceof VFSError && err.status === 404) {
+      return {
+        allowed: true,
+        bucket_id: req.bucket_id,
+        size: req.size ?? 0,
+        max_upload_bytes: 0
+      };
+    }
+    throw err;
+  }
+}
+
+// src/upload/single.ts
+async function uploadSingleFile(http, input, defaultBucket = "default") {
+  const bucketId = input.bucketId || defaultBucket;
+  input.onProgress?.({
+    loaded: 0,
+    total: 100,
+    percent: 5,
+    phase: "hashing"
+  });
+  const normalized = await normalizeUploadInput(input);
+  let uploadToken;
+  if (input.preflight !== false) {
+    input.onProgress?.({
+      loaded: 0,
+      total: normalized.size,
+      percent: 15,
+      phase: "preflight"
+    });
+    const preflight = await executePreflight(
+      http,
+      {
+        bucket_id: bucketId,
+        name: normalized.name,
+        size: normalized.size,
+        content_type: normalized.contentType,
+        file_hash: normalized.hash
+      },
+      input.signal
+    );
+    if (preflight.duplicate) {
+      input.onProgress?.({
+        loaded: normalized.size,
+        total: normalized.size,
+        percent: 100,
+        phase: "complete"
+      });
+      return preflight.duplicate;
+    }
+    if (!preflight.allowed) {
+      throw new VFSError(preflight.reason || "Upload rejected by server preflight check", {
+        status: 400
+      });
+    }
+    uploadToken = preflight.upload_token;
+  }
+  input.onProgress?.({
+    loaded: 0,
+    total: normalized.size,
+    percent: 30,
+    phase: "uploading"
+  });
+  const formData = new FormData();
+  const blob = new Blob([normalized.bytes], { type: normalized.contentType });
+  formData.append("file", blob, normalized.name);
+  formData.append("bucket_id", bucketId);
+  if (normalized.hash) {
+    formData.append("file_hash", normalized.hash);
+  }
+  if (uploadToken) {
+    formData.append("upload_token", uploadToken);
+  }
+  if (input.metadata && Object.keys(input.metadata).length > 0) {
+    formData.append("metadata", JSON.stringify(input.metadata));
+  }
+  const res = await http.post("/api/upload", formData, {
+    signal: input.signal
+  });
+  input.onProgress?.({
+    loaded: normalized.size,
+    total: normalized.size,
+    percent: 100,
+    phase: "complete"
+  });
+  return res.data;
+}
+
+// src/upload/session.ts
+var DEFAULT_CHUNK_SIZE = 1048576;
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function generateSessionId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID().replace(/-/g, "");
+  }
+  return Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+}
+async function uploadSessionFile(http, input, defaultBucket = "default") {
+  const bucketId = input.bucketId || defaultBucket;
+  input.onProgress?.({
+    loaded: 0,
+    total: 100,
+    percent: 5,
+    phase: "hashing"
+  });
+  const normalized = await normalizeUploadInput(input);
+  const sessionId = input.resumeId || generateSessionId();
+  const chunkSize = input.chunkSize || DEFAULT_CHUNK_SIZE;
+  input.onProgress?.({
+    loaded: 0,
+    total: normalized.size,
+    percent: 10,
+    phase: "preflight"
+  });
+  let session;
+  let failures = 0;
+  while (!session) {
+    if (input.signal?.aborted) {
+      throw new VFSError("Upload aborted", { status: 499 });
+    }
+    try {
+      const res = await http.post(
+        "/api/upload/sessions",
+        JSON.stringify({
+          id: sessionId,
+          bucket_id: bucketId,
+          name: normalized.name,
+          size: normalized.size,
+          file_hash: normalized.hash,
+          content_type: normalized.contentType
+        }),
+        {
+          headers: { "Content-Type": "application/json" },
+          signal: input.signal,
+          timeout: 15e3
+        }
+      );
+      session = res.data;
+    } catch (err) {
+      if (err instanceof VFSError) {
+        if (err.status === 410) {
+          throw new VFSError("The upload session has expired. Start a new session.", { status: 410, cause: err });
+        }
+        if ([400, 401, 403, 409, 413, 422].includes(err.status)) {
+          throw err;
+        }
+      }
+      failures++;
+      if (failures >= 5) {
+        throw new VFSError("Failed to initialize upload session after retries", { cause: err });
+      }
+      await delay(500 * Math.pow(2, failures - 1));
+    }
+  }
+  if (!session) {
+    throw new VFSError("Failed to initialize upload session");
+  }
+  let currentSession = session;
+  failures = 0;
+  let offset = currentSession.offset;
+  while (["receiving", "paused"].includes(currentSession.state) && offset < normalized.size) {
+    if (input.signal?.aborted) {
+      throw new VFSError("Upload aborted", { status: 499 });
+    }
+    const currentChunkSize = Math.min(currentSession.chunk_size || chunkSize, normalized.size - offset);
+    const chunkBytes = normalized.bytes.subarray(offset, offset + currentChunkSize);
+    const chunkHash = await calculateSHA256(chunkBytes);
+    const percent = Math.min(95, 15 + Math.floor(offset / normalized.size * 80));
+    input.onProgress?.({
+      loaded: offset,
+      total: normalized.size,
+      percent,
+      phase: "chunks"
+    });
+    try {
+      const chunkRes = await http.put(
+        `/api/upload/sessions/${currentSession.id}/chunks/${offset}`,
+        // Pass Uint8Array slice directly as binary body
+        chunkBytes,
+        {
+          headers: {
+            "Content-Type": "application/octet-stream",
+            "X-Upload-SHA256": chunkHash
+          },
+          signal: input.signal,
+          timeout: 3e4
+        }
+      );
+      currentSession = chunkRes.data;
+      offset = currentSession.offset;
+      failures = 0;
+    } catch (err) {
+      failures++;
+      if (err instanceof VFSError && [400, 401, 403, 410, 413, 422].includes(err.status)) {
+        throw err;
+      }
+      if (failures >= 6) {
+        throw new VFSError(`Chunk upload failed at offset ${offset}: ${err instanceof Error ? err.message : "Unknown error"}`, {
+          cause: err
+        });
+      }
+      await delay(Math.min(500 * Math.pow(2, failures - 1), 8e3));
+      try {
+        const statusRes = await http.get(`/api/upload/sessions/${currentSession.id}`, {
+          timeout: 1e4,
+          signal: input.signal
+        });
+        currentSession = statusRes.data;
+        offset = currentSession.offset;
+      } catch {
+      }
+    }
+  }
+  input.onProgress?.({
+    loaded: normalized.size,
+    total: normalized.size,
+    percent: 96,
+    phase: "finalizing"
+  });
+  if (currentSession.state !== "complete") {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      if (input.signal?.aborted) {
+        throw new VFSError("Upload aborted", { status: 499 });
+      }
+      try {
+        const finalRes = await http.post(
+          `/api/upload/sessions/${currentSession.id}/finalize`,
+          "{}",
+          {
+            headers: { "Content-Type": "application/json" },
+            timeout: 15e3,
+            signal: input.signal
+          }
+        );
+        currentSession = finalRes.data;
+        break;
+      } catch (err) {
+        if (attempt >= 4) {
+          throw new VFSError("Failed to finalize session upload", { cause: err });
+        }
+        await delay(1e3);
+      }
+    }
+  }
+  let pollAttempts = 0;
+  while (currentSession.state !== "complete" && pollAttempts < 10) {
+    await delay(1e3);
+    try {
+      const statusRes = await http.get(`/api/upload/sessions/${currentSession.id}`, {
+        timeout: 5e3,
+        signal: input.signal
+      });
+      currentSession = statusRes.data;
+      if (currentSession.state === "complete") break;
+    } catch {
+    }
+    pollAttempts++;
+  }
+  input.onProgress?.({
+    loaded: normalized.size,
+    total: normalized.size,
+    percent: 100,
+    phase: "complete"
+  });
+  const ext = normalized.name.split(".").pop() || "";
+  const fileUrl = `${http.getEndpoint()}/v/${bucketId}/${currentSession.id}${ext ? `.${ext}` : ""}`;
+  return {
+    id: currentSession.id,
+    bucket_id: bucketId,
+    file_id: currentSession.id,
+    file_hash: normalized.hash,
+    extension: ext,
+    name: normalized.name,
+    size: normalized.size,
+    type: normalized.contentType,
+    metadata: input.metadata,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    url: fileUrl,
+    key: `edge:${currentSession.id}`,
+    store: "edge",
+    is_stat_synced: true
+  };
+}
+
+// src/upload/queue.ts
+var BackgroundUploadQueue = class {
+  http;
+  defaultBucket;
+  concurrency;
+  items = [];
+  activeCount = 0;
+  isPaused = false;
+  abortController = new AbortController();
+  listeners = /* @__PURE__ */ new Set();
+  onFileSuccessCb;
+  onFileErrorCb;
+  onCompletePromiseResolve;
+  onCompletePromiseReject;
+  constructor(http, options = {}) {
+    this.http = http;
+    this.defaultBucket = options.defaultBucket || "default";
+    this.concurrency = Math.max(1, options.concurrency || 3);
+  }
+  onProgress(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  onFileSuccess(cb) {
+    this.onFileSuccessCb = cb;
+    return this;
+  }
+  onFileError(cb) {
+    this.onFileErrorCb = cb;
+    return this;
+  }
+  add(input) {
+    const id = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).slice(2);
+    const item = {
+      id,
+      input,
+      status: "pending",
+      progress: 0
+    };
+    this.items.push(item);
+    this.processQueue();
+    return id;
+  }
+  addAll(inputs) {
+    return inputs.map((input) => this.add(input));
+  }
+  pause() {
+    this.isPaused = true;
+  }
+  resume() {
+    if (this.isPaused) {
+      this.isPaused = false;
+      this.processQueue();
+    }
+  }
+  cancel() {
+    this.abortController.abort();
+    this.abortController = new AbortController();
+    for (const item of this.items) {
+      if (item.status === "pending" || item.status === "uploading") {
+        item.status = "cancelled";
+      }
+    }
+    this.activeCount = 0;
+    this.notifyProgress();
+    this.onCompletePromiseReject?.(new Error("Upload queue cancelled"));
+  }
+  clear() {
+    this.cancel();
+    this.items = [];
+  }
+  getItems() {
+    return [...this.items];
+  }
+  getProgress() {
+    const totalFiles = this.items.length;
+    if (totalFiles === 0) {
+      return { totalFiles: 0, completedFiles: 0, failedFiles: 0, overallPercent: 100 };
+    }
+    let completedFiles = 0;
+    let failedFiles = 0;
+    let totalPercentSum = 0;
+    let currentFile;
+    for (const item of this.items) {
+      if (item.status === "completed") {
+        completedFiles++;
+        totalPercentSum += 100;
+      } else if (item.status === "failed") {
+        failedFiles++;
+        totalPercentSum += 100;
+      } else if (item.status === "uploading") {
+        currentFile = item.input.name;
+        totalPercentSum += item.progress;
+      }
+    }
+    const overallPercent = Math.round(totalPercentSum / totalFiles);
+    return {
+      totalFiles,
+      completedFiles,
+      failedFiles,
+      overallPercent,
+      currentFile
+    };
+  }
+  notifyProgress(item) {
+    const progress = this.getProgress();
+    for (const listener of this.listeners) {
+      try {
+        listener(progress, item);
+      } catch {
+      }
+    }
+  }
+  async processQueue() {
+    if (this.isPaused) return;
+    while (this.activeCount < this.concurrency) {
+      const nextItem = this.items.find((i) => i.status === "pending");
+      if (!nextItem) break;
+      this.activeCount++;
+      nextItem.status = "uploading";
+      this.notifyProgress(nextItem);
+      this.uploadItem(nextItem).catch(() => {
+      }).finally(() => {
+        this.activeCount--;
+        this.notifyProgress(nextItem);
+        this.processQueue();
+        this.checkCompletion();
+      });
+    }
+  }
+  async uploadItem(item) {
+    const inputWithProgress = {
+      ...item.input,
+      signal: item.input.signal || this.abortController.signal,
+      onProgress: (p) => {
+        item.progress = p.percent;
+        item.input.onProgress?.(p);
+        this.notifyProgress(item);
+      }
+    };
+    try {
+      let result;
+      if (item.input.resumable) {
+        result = await uploadSessionFile(this.http, inputWithProgress, this.defaultBucket);
+      } else if (item.input.preflight !== false) {
+        const normalized = await normalizeUploadInput(item.input);
+        const bucketId = item.input.bucketId || this.defaultBucket;
+        const preflight = await executePreflight(
+          this.http,
+          {
+            bucket_id: bucketId,
+            name: normalized.name,
+            size: normalized.size,
+            content_type: normalized.contentType,
+            file_hash: normalized.hash
+          },
+          inputWithProgress.signal
+        );
+        if (preflight.duplicate) {
+          result = preflight.duplicate;
+        } else if (preflight.upload_protocol === "edge-chunks-v1") {
+          result = await uploadSessionFile(this.http, inputWithProgress, this.defaultBucket);
+        } else {
+          result = await uploadSingleFile(this.http, inputWithProgress, this.defaultBucket);
+        }
+      } else {
+        result = await uploadSingleFile(this.http, inputWithProgress, this.defaultBucket);
+      }
+      item.status = "completed";
+      item.progress = 100;
+      item.response = result;
+      this.onFileSuccessCb?.(item.input, result);
+    } catch (err) {
+      item.status = "failed";
+      item.error = err instanceof Error ? err : new Error(String(err));
+      this.onFileErrorCb?.(item.input, item.error);
+    }
+  }
+  checkCompletion() {
+    const hasPending = this.items.some((i) => i.status === "pending" || i.status === "uploading");
+    if (!hasPending && this.activeCount === 0) {
+      const successful = this.items.filter((i) => i.status === "completed" && i.response).map((i) => i.response);
+      this.onCompletePromiseResolve?.(successful);
+    }
+  }
+  /**
+   * Returns a promise that resolves when all items currently in the queue have completed.
+   */
+  async wait() {
+    const hasPending = this.items.some((i) => i.status === "pending" || i.status === "uploading");
+    if (!hasPending && this.activeCount === 0) {
+      return this.items.filter((i) => i.status === "completed" && i.response).map((i) => i.response);
+    }
+    return new Promise((resolve, reject) => {
+      this.onCompletePromiseResolve = resolve;
+      this.onCompletePromiseReject = reject;
+    });
+  }
+};
+async function uploadMultipleFiles(http, input, defaultBucket = "default") {
+  const queue = new BackgroundUploadQueue(http, {
+    defaultBucket: input.bucketId || defaultBucket,
+    concurrency: input.concurrency || 3
+  });
+  if (input.onProgress) {
+    queue.onProgress((p) => input.onProgress?.(p));
+  }
+  if (input.onFileSuccess) {
+    queue.onFileSuccess(input.onFileSuccess);
+  }
+  if (input.onFileError) {
+    queue.onFileError(input.onFileError);
+  }
+  if (input.signal) {
+    input.signal.addEventListener("abort", () => queue.cancel(), { once: true });
+  }
+  queue.addAll(input.files);
+  return queue.wait();
+}
+
+// src/client.ts
+var VFSClient = class {
+  http;
+  defaultBucket;
+  cache;
+  constructor(options) {
+    this.http = new HttpClient(options);
+    this.defaultBucket = options.defaultBucket || "default";
+    if (options.cache === true) {
+      this.cache = createDefaultCache();
+    } else if (options.cache && typeof options.cache === "object") {
+      this.cache = options.cache;
+    }
+  }
+  /**
+   * Upload a single file to VFS.
+   * Proactively checks preflight quota and deduplication: if identical file content exists,
+   * skips transfer and returns the existing file immediately.
+   */
+  async upload(input) {
+    if (input.resumable) {
+      return uploadSessionFile(this.http, input, this.defaultBucket);
+    }
+    return uploadSingleFile(this.http, input, this.defaultBucket);
+  }
+  /**
+   * Upload multiple files with concurrency control, progress reporting, and stream/chunk support.
+   */
+  async uploadMultiple(input) {
+    return uploadMultipleFiles(this.http, input, this.defaultBucket);
+  }
+  /**
+   * Creates a background upload queue manager for continuous uploads with pause/resume and events.
+   */
+  createBackgroundQueue(options) {
+    return new BackgroundUploadQueue(this.http, {
+      defaultBucket: options?.bucketId || this.defaultBucket,
+      concurrency: options?.concurrency || 3
+    });
+  }
+  /**
+   * Retrieves a file from VFS with multi-tier caching (Browser CacheStorage / Server Filesystem).
+   */
+  async getFile(bucketId, fileId, options = {}) {
+    const cacheKey = `vfs:${bucketId}:${fileId}`;
+    const shouldUseCache = options.useCache !== false && Boolean(this.cache);
+    if (shouldUseCache && this.cache) {
+      const cached = await this.cache.get(cacheKey);
+      if (cached) {
+        if (options.responseType === "arrayBuffer") {
+          return cached.data.buffer.slice(cached.data.byteOffset, cached.data.byteOffset + cached.data.byteLength);
+        }
+        if (options.responseType === "text") {
+          return new TextDecoder().decode(cached.data);
+        }
+        if (options.responseType === "json") {
+          return JSON.parse(new TextDecoder().decode(cached.data));
+        }
+        if (options.responseType === "stream") {
+          return new ReadableStream({
+            start(controller) {
+              controller.enqueue(cached.data);
+              controller.close();
+            }
+          });
+        }
+        return new Blob([cached.data], { type: cached.contentType });
+      }
+    }
+    const params = {};
+    if (options.download) {
+      params.download = true;
+    }
+    if (options.imgproxy) {
+      if (options.imgproxy.width) params.w = options.imgproxy.width;
+      if (options.imgproxy.height) params.h = options.imgproxy.height;
+      if (options.imgproxy.resizingType) params.rs = options.imgproxy.resizingType;
+      if (options.imgproxy.format) params.fmt = options.imgproxy.format;
+      if (options.imgproxy.quality) params.q = options.imgproxy.quality;
+    }
+    const response = await this.http.fetchRaw(`/v/${encodeURIComponent(bucketId)}/${encodeURIComponent(fileId)}`, {
+      params,
+      signal: options.signal
+    });
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    const contentDisposition = response.headers.get("content-disposition") || "";
+    let filename;
+    const match = contentDisposition.match(/filename="?([^";]+)"?/);
+    if (match) filename = match[1];
+    const arrayBuffer = await response.arrayBuffer();
+    const bytes = new Uint8Array(arrayBuffer);
+    if (shouldUseCache && this.cache) {
+      await this.cache.set(cacheKey, {
+        data: bytes,
+        contentType,
+        name: filename,
+        size: bytes.byteLength,
+        createdAt: Date.now()
+      });
+    }
+    if (options.responseType === "arrayBuffer") {
+      return arrayBuffer;
+    }
+    if (options.responseType === "text") {
+      return new TextDecoder().decode(bytes);
+    }
+    if (options.responseType === "json") {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    if (options.responseType === "stream") {
+      return new ReadableStream({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        }
+      });
+    }
+    return new Blob([bytes], { type: contentType });
+  }
+  /**
+   * Retrieves a file directly by its SHA-256 hash (/h/:hash).
+   * Hash-addressed content is immutable and cached indefinitely.
+   */
+  async getFileByHash(hash, options = {}) {
+    const cacheKey = `vfs:hash:${hash}`;
+    const shouldUseCache = options.useCache !== false && Boolean(this.cache);
+    if (shouldUseCache && this.cache) {
+      const cached = await this.cache.get(cacheKey);
+      if (cached) {
+        if (options.responseType === "arrayBuffer") {
+          return cached.data.buffer.slice(cached.data.byteOffset, cached.data.byteOffset + cached.data.byteLength);
+        }
+        if (options.responseType === "text") {
+          return new TextDecoder().decode(cached.data);
+        }
+        if (options.responseType === "json") {
+          return JSON.parse(new TextDecoder().decode(cached.data));
+        }
+        return new Blob([cached.data], { type: cached.contentType });
+      }
+    }
+    const response = await this.http.fetchRaw(`/h/${encodeURIComponent(hash)}`, {
+      signal: options.signal
+    });
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    const arrayBuffer = await response.arrayBuffer();
+    const bytes = new Uint8Array(arrayBuffer);
+    if (shouldUseCache && this.cache) {
+      await this.cache.set(
+        cacheKey,
+        {
+          data: bytes,
+          contentType,
+          size: bytes.byteLength,
+          hash,
+          createdAt: Date.now()
+        },
+        31536e3
+      );
+    }
+    if (options.responseType === "arrayBuffer") {
+      return arrayBuffer;
+    }
+    if (options.responseType === "text") {
+      return new TextDecoder().decode(bytes);
+    }
+    if (options.responseType === "json") {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    return new Blob([bytes], { type: contentType });
+  }
+  /**
+   * Gets metadata manifest of an uploaded file as a JSON object without downloading the file data.
+   */
+  async getFileMetadata(bucketId, fileId, signal) {
+    const res = await this.http.get(
+      `/v/${encodeURIComponent(bucketId)}/${encodeURIComponent(fileId)}`,
+      {
+        params: { output: "json" },
+        headers: { Accept: "application/json" },
+        signal
+      }
+    );
+    return res.data;
+  }
+  /**
+   * Gets metadata manifest of a file by its SHA-256 hash.
+   */
+  async getFileMetadataByHash(hash, signal) {
+    const res = await this.http.get(`/h/${encodeURIComponent(hash)}`, {
+      params: { output: "json" },
+      headers: { Accept: "application/json" },
+      signal
+    });
+    return res.data;
+  }
+  /**
+   * Generates public/access URL for a file, supporting imgproxy transformations and download triggers.
+   */
+  getFileUrl(bucketId, fileId, options = {}) {
+    const url = new URL(`${this.http.getEndpoint()}/v/${encodeURIComponent(bucketId)}/${encodeURIComponent(fileId)}`);
+    if (options.download) {
+      url.searchParams.set("download", "true");
+    }
+    if (options.imgproxy) {
+      if (options.imgproxy.width) url.searchParams.set("w", String(options.imgproxy.width));
+      if (options.imgproxy.height) url.searchParams.set("h", String(options.imgproxy.height));
+      if (options.imgproxy.resizingType) url.searchParams.set("rs", options.imgproxy.resizingType);
+      if (options.imgproxy.format) url.searchParams.set("fmt", options.imgproxy.format);
+      if (options.imgproxy.quality) url.searchParams.set("q", String(options.imgproxy.quality));
+    }
+    return url.toString();
+  }
+  /**
+   * Generates public URL for a file addressed by its SHA-256 hash.
+   */
+  getFileUrlByHash(hash) {
+    return `${this.http.getEndpoint()}/h/${encodeURIComponent(hash)}`;
+  }
+  /**
+   * Deletes a file by bucket ID and file ID, invalidating any cached copies.
+   */
+  async deleteFile(bucketId, fileId, signal) {
+    try {
+      await this.http.delete(`/api/upload/unlink/${encodeURIComponent(bucketId)}/${encodeURIComponent(fileId)}`, {
+        signal
+      });
+    } catch (err) {
+      if (err instanceof VFSError && err.status === 404) ; else {
+        throw err;
+      }
+    }
+    if (this.cache) {
+      await this.cache.delete(`vfs:${bucketId}:${fileId}`);
+    }
+  }
+  /**
+   * Deletes a file record by catalog ID.
+   */
+  async deleteFileById(id, signal) {
+    await this.http.delete(`/api/upload/${encodeURIComponent(id)}`, { signal });
+  }
+  /**
+   * Deletes all files within a specified bucket.
+   */
+  async deleteAllInBucket(bucketId, signal) {
+    await this.http.delete(`/api/upload/bucket/${encodeURIComponent(bucketId)}`, { signal });
+  }
+  /**
+   * Lists stored objects in a bucket.
+   */
+  async listFiles(options = {}) {
+    const bucketId = options.bucketId || this.defaultBucket;
+    const res = await this.http.get("/api/upload", {
+      params: { bucket_id: bucketId },
+      signal: options.signal
+    });
+    return res.data;
+  }
+  /**
+   * Gets real-time statistics for a bucket (total files, storage usage, read/write counts, quota limits).
+   */
+  async getBucketStats(bucketId, signal) {
+    const targetBucket = bucketId || this.defaultBucket;
+    const res = await this.http.get(`/api/bucket/stats/${encodeURIComponent(targetBucket)}`, { signal });
+    return res.data;
+  }
+  /**
+   * Gets a list of all bucket statistics.
+   */
+  async getAllBucketStats(params, signal) {
+    const res = await this.http.get("/api/bucket/stats", {
+      params,
+      signal
+    });
+    return {
+      items: res.data,
+      total: res.totalCount
+    };
+  }
+  /**
+   * Gets overall system summary of bucket statistics (total buckets, total files, total storage size).
+   */
+  async getBucketSummary(signal) {
+    const res = await this.http.get("/api/bucket/stats/summary", { signal });
+    return res.data;
+  }
+  /**
+   * Gets date-based usage growth metrics for a bucket.
+   */
+  async getBucketMetrics(bucketId, signal) {
+    const targetBucket = bucketId || this.defaultBucket;
+    const res = await this.http.get(
+      `/api/bucket/stats/${encodeURIComponent(targetBucket)}/metrics`,
+      { signal }
+    );
+    return res.data;
+  }
+};
+
+exports.BackgroundUploadQueue = BackgroundUploadQueue;
+exports.BrowserCacheAdapter = BrowserCacheAdapter;
+exports.FileSystemCacheAdapter = FileSystemCacheAdapter;
+exports.HttpClient = HttpClient;
+exports.MemoryCacheAdapter = MemoryCacheAdapter;
+exports.VFSClient = VFSClient;
+exports.VFSError = VFSError;
+exports.calculateBlobSHA256 = calculateBlobSHA256;
+exports.calculateSHA256 = calculateSHA256;
+exports.createDefaultCache = createDefaultCache;
+exports.executePreflight = executePreflight;
+exports.guessContentType = guessContentType;
+exports.normalizeUploadInput = normalizeUploadInput;
+exports.uploadMultipleFiles = uploadMultipleFiles;
+exports.uploadSessionFile = uploadSessionFile;
+exports.uploadSingleFile = uploadSingleFile;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map