@lacrous/omnicloud 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,175 +1,520 @@
 // src/client.ts
 var OmniCloudError = class extends Error {
-  constructor(status, code, message) {
+  constructor(status, code, message, requestId = void 0, details = void 0) {
     super(message);
     this.status = status;
     this.code = code;
+    this.requestId = requestId;
+    this.details = details;
     this.name = "OmniCloudError";
   }
   status;
   code;
+  requestId;
+  details;
 };
+var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 300 };
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new OmniCloudError(0, "ABORTED", "Request aborted"));
+      },
+      { once: true }
+    );
+  });
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function buildQuery(query) {
+  const params = new URLSearchParams();
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0 || value === null || value === "") continue;
+      params.set(key, String(value));
+    }
+  }
+  const encoded = params.toString();
+  return encoded ? `?${encoded}` : "";
+}
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
 var OmniCloudClient = class {
+  files;
+  folders;
+  trash;
+  storage;
+  search;
+  recent;
+  activity;
+  auth;
+  /** @internal */
   baseUrl;
+  /** @internal */
   fetchImpl;
+  /** @internal */
+  retry;
+  /** @internal */
+  defaultHeaders;
   constructor(options = {}) {
     this.baseUrl = (options.baseUrl ?? "").replace(/\/$/, "");
     this.fetchImpl = options.fetchImpl ?? fetch.bind(globalThis);
+    this.retry = { ...DEFAULT_RETRY, ...options.retry };
+    this.defaultHeaders = {
+      ...options.token ? { Authorization: `Bearer ${options.token}` } : {},
+      ...options.headers
+    };
+    this.files = new FilesApi(this);
+    this.folders = new FoldersApi(this);
+    this.trash = new TrashApi(this);
+    this.storage = new StorageApi(this);
+    this.search = new SearchApi(this);
+    this.recent = new RecentApi(this);
+    this.activity = new ActivityApi(this);
+    this.auth = new AuthApi(this);
+  }
+  /** Low-level request helper (retries transient failures). */
+  async request(method, path, body) {
+    return this.withRetry(async () => this.rawRequest(method, path, body));
   }
-  // ── Authentication ───────────────────────────────────────────────────────
-  async me() {
-    return this.request("GET", "/api/auth/me");
-  }
-  async startTelegramLogin(phone) {
-    await this.request("POST", "/api/auth/telegram/start", { phone });
-  }
-  async verifyTelegramCode(phone, code) {
-    return this.request("POST", "/api/auth/telegram/verify", { phone, code });
-  }
-  async submitTelegramPassword(phone, password) {
-    return this.request("POST", "/api/auth/telegram/password", { phone, password });
-  }
-  async ensureStorage() {
-    const { storage } = await this.request("POST", "/api/storage/ensure");
-    return storage;
-  }
-  async logout() {
-    await this.request("POST", "/api/auth/logout");
-  }
-  // ── Folders ──────────────────────────────────────────────────────────────
-  async listFolders(parentId) {
-    const { folders } = await this.request(
-      "GET",
-      `/api/folders${parentId ? `?parentId=${encodeURIComponent(parentId)}` : ""}`
-    );
-    return folders;
-  }
-  async folderTree() {
-    const { folders } = await this.request("GET", "/api/folders/tree");
-    return folders;
-  }
-  async createFolder(name, parentId = null) {
-    const { folder } = await this.request("POST", "/api/folders", {
-      name,
-      parentId
+  /** @internal */
+  async rawRequest(method, path, body) {
+    const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        ...this.defaultHeaders,
+        ...body !== void 0 && !isForm ? { "Content-Type": "application/json" } : {}
+      },
+      body: body === void 0 ? void 0 : isForm ? body : JSON.stringify(body),
+      credentials: "include"
     });
-    return folder;
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    const data = text ? safeJsonParse(text) : null;
+    if (!response.ok) {
+      const error = data?.error;
+      throw new OmniCloudError(
+        response.status,
+        error?.code ?? "INTERNAL_ERROR",
+        error?.message ?? `Request failed (${response.status})`,
+        error?.requestId,
+        error?.details
+      );
+    }
+    return data;
   }
-  async renameFolder(id, name) {
-    const { folder } = await this.request("PATCH", `/api/folders/${id}`, {
-      name
-    });
-    return folder;
+  /** @internal */
+  async withRetry(operation) {
+    const { attempts, baseDelayMs } = this.retry;
+    let lastError;
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt += 1) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+        const retryable = error instanceof OmniCloudError && isRetryableStatus(error.status);
+        if (!retryable || attempt >= attempts) break;
+        await sleep(baseDelayMs * 2 ** (attempt - 1));
+      }
+    }
+    throw lastError;
   }
-  async moveFolder(id, parentId) {
-    const { folder } = await this.request(
-      "POST",
-      `/api/folders/${id}/move`,
-      { parentId }
-    );
-    return folder;
+  /** @internal */
+  async requestBinary(path, onProgress) {
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      headers: this.defaultHeaders,
+      credentials: "include"
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      const error = safeJsonParse(text)?.error;
+      throw new OmniCloudError(
+        response.status,
+        error?.code ?? "DOWNLOAD_FAILED",
+        error?.message ?? `Download failed (${response.status})`
+      );
+    }
+    const total = Number(response.headers.get("content-length") ?? 0) || null;
+    const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+    const sha256 = response.headers.get("x-content-sha256");
+    const integrityHeader = response.headers.get("x-integrity-verified");
+    const integrityVerified = integrityHeader === null ? null : integrityHeader === "true";
+    const data = await readBody(response, total, onProgress);
+    return { data, contentType, size: data.byteLength, sha256, integrityVerified };
   }
-  async deleteFolder(id) {
-    return this.request("DELETE", `/api/folders/${id}`);
+};
+async function readBody(response, total, onProgress) {
+  const body = response.body;
+  if (!body) {
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    onProgress?.({ loaded: buffer.byteLength, total: buffer.byteLength, percent: 100 });
+    return buffer;
+  }
+  const chunks = [];
+  let loaded = 0;
+  const reader = body.getReader();
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      loaded += value.byteLength;
+      onProgress?.({
+        loaded,
+        total,
+        percent: total ? Math.round(loaded / total * 100) : null
+      });
+    }
   }
-  // ── Files ────────────────────────────────────────────────────────────────
-  async listFiles(folderId) {
-    const { files } = await this.request(
-      "GET",
-      `/api/files${folderId ? `?folderId=${encodeURIComponent(folderId)}` : ""}`
-    );
-    return files;
+  const merged = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
   }
-  async getFile(id) {
-    const { file } = await this.request("GET", `/api/files/${id}`);
-    return file;
+  const BufferCtor = globalThis.Buffer;
+  return BufferCtor ? BufferCtor.from(merged) : merged;
+}
+var FilesApi = class {
+  constructor(client) {
+    this.client = client;
   }
-  async renameFile(id, name) {
-    const { file } = await this.request("PATCH", `/api/files/${id}`, { name });
-    return file;
+  client;
+  /** `folderId: null` = root; omit it to list every active file. */
+  async list(query = {}) {
+    return this.client.request("GET", `/api/files${buildQuery(query)}`);
   }
-  async moveFile(id, folderId) {
-    const { file } = await this.request("POST", `/api/files/${id}/move`, {
-      folderId
-    });
+  async get(id) {
+    const { file } = await this.client.request("GET", `/api/files/${id}`);
     return file;
   }
-  async deleteFile(id) {
-    await this.request("DELETE", `/api/files/${id}`);
-  }
-  /** URL of the download endpoint (usable as href for direct downloads). */
-  fileDownloadUrl(id) {
-    return `${this.baseUrl}/api/files/${id}/download`;
+  async versions(id) {
+    const { versions } = await this.client.request(
+      "GET",
+      `/api/files/${id}/versions`
+    );
+    return versions;
   }
   /**
-   * Uploads a file. Uses XMLHttpRequest when available so `onProgress`
-   * works (browsers); falls back to fetch without progress in Node.
+   * Uploads a file with progress and retry support. Uses XMLHttpRequest when
+   * available (browsers) so progress and cancellation work; falls back to
+   * fetch elsewhere.
    */
-  async uploadFile(input, options = {}) {
+  async upload(input, options = {}) {
+    const attempts = Math.max(1, (options.retry ?? 2) + 1);
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        return await this.uploadOnce(input, options);
+      } catch (error) {
+        lastError = error;
+        if (options.signal?.aborted) throw error;
+        if (error instanceof OmniCloudError && !isRetryableStatus(error.status)) throw error;
+        if (attempt < attempts) await sleep(300 * 2 ** (attempt - 1), options.signal);
+      }
+    }
+    throw lastError;
+  }
+  uploadOnce(input, options) {
     const form = new FormData();
-    const blob = input.data instanceof Blob ? input.data : new Blob([new Uint8Array(input.data)]);
+    const blob = typeof Blob !== "undefined" && input.data instanceof Blob ? input.data : new Blob([new Uint8Array(input.data)]);
     form.append("file", blob, input.name);
     if (options.folderId) form.append("folderId", options.folderId);
     if (typeof XMLHttpRequest === "function") {
-      return this.uploadViaXhr(form, options.onProgress);
+      return this.uploadViaXhr(form, options);
     }
-    return this.request("POST", "/api/files", form);
-  }
-  async search(query) {
-    return this.request("GET", `/api/search?q=${encodeURIComponent(query)}`);
+    return this.client.request("POST", "/api/files", form).then((response) => response.file);
   }
-  // ── internals ────────────────────────────────────────────────────────────
-  uploadViaXhr(form, onProgress) {
+  uploadViaXhr(form, options) {
     return new Promise((resolve, reject) => {
       const xhr = new XMLHttpRequest();
-      xhr.open("POST", `${this.baseUrl}/api/files`);
+      xhr.open("POST", `${this.client.baseUrl}/api/files`);
       xhr.responseType = "json";
       xhr.withCredentials = true;
+      const onAbort = () => xhr.abort();
+      options.signal?.addEventListener("abort", onAbort, { once: true });
       xhr.upload.onprogress = (event) => {
-        if (!onProgress) return;
-        onProgress({
+        options.onProgress?.({
           loaded: event.loaded,
           total: event.total,
           percent: event.total > 0 ? Math.round(event.loaded / event.total * 100) : 0
         });
       };
       xhr.onload = () => {
+        options.signal?.removeEventListener("abort", onAbort);
         const body = xhr.response;
         if (xhr.status >= 200 && xhr.status < 300 && body?.file) {
+          options.onProgress?.({ loaded: 1, total: 1, percent: 100 });
           resolve(body.file);
           return;
         }
         reject(
           new OmniCloudError(
             xhr.status,
-            body?.error?.code ?? "INTERNAL_ERROR",
-            body?.error?.message ?? `Upload failed (${xhr.status})`
+            body?.error?.code ?? "UPLOAD_FAILED",
+            body?.error?.message ?? `Upload failed (${xhr.status})`,
+            body?.error?.requestId
           )
         );
       };
       xhr.onerror = () => reject(new OmniCloudError(0, "NETWORK_ERROR", "Network error during upload"));
+      xhr.onabort = () => reject(new OmniCloudError(0, "ABORTED", "Upload aborted"));
       xhr.send(form);
     });
   }
-  async request(method, path, body) {
-    const isJsonBody = body !== void 0 && !(body instanceof FormData);
-    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-      method,
-      headers: isJsonBody ? { "Content-Type": "application/json" } : void 0,
-      body: body === void 0 ? void 0 : isJsonBody ? JSON.stringify(body) : body,
-      credentials: "include"
+  /** Uploads a new version of an existing file. */
+  async replace(id, input) {
+    const form = new FormData();
+    const blob = typeof Blob !== "undefined" && input.data instanceof Blob ? input.data : new Blob([new Uint8Array(input.data)]);
+    form.append("file", blob, input.name);
+    const { file } = await this.client.request(
+      "POST",
+      `/api/files/${id}/replace`,
+      form
+    );
+    return file;
+  }
+  async download(id, onProgress) {
+    return this.client.requestBinary(`/api/files/${id}/download`, onProgress);
+  }
+  /** URL suitable for direct download (anchor href). */
+  downloadUrl(id) {
+    return `${this.client.baseUrl}/api/files/${id}/download`;
+  }
+  async rename(id, name) {
+    const { file } = await this.client.request("PATCH", `/api/files/${id}`, {
+      name
+    });
+    return file;
+  }
+  async star(id, starred = true) {
+    const { file } = await this.client.request("PATCH", `/api/files/${id}`, {
+      starred
+    });
+    return file;
+  }
+  async move(id, folderId) {
+    const { file } = await this.client.request("POST", `/api/files/${id}/move`, {
+      folderId
+    });
+    return file;
+  }
+  async trash(id) {
+    const { file } = await this.client.request("POST", `/api/files/${id}/trash`);
+    return file;
+  }
+  async restore(id) {
+    const { file } = await this.client.request(
+      "POST",
+      `/api/files/${id}/restore`
+    );
+    return file;
+  }
+  /** Permanently deletes a file and its Telegram objects. */
+  async delete(id) {
+    await this.client.request("DELETE", `/api/files/${id}`);
+  }
+  /** Batch operation: trash | restore | delete | star | unstar | move. */
+  async batch(operation, ids, options = {}) {
+    return this.client.request("POST", "/api/files/batch", {
+      operation,
+      ids,
+      ...operation === "move" ? { folderId: options.folderId ?? null } : {}
+    });
+  }
+};
+var FoldersApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list(query = {}) {
+    const { parentId, ...rest } = query;
+    const path = parentId !== void 0 ? `/api/folders?parentId=${encodeURIComponent(parentId ?? "")}` : `/api/folders${buildQuery(rest)}`;
+    return this.client.request("GET", path);
+  }
+  /** The full active folder tree (for move dialogs). */
+  async tree() {
+    const { folders } = await this.client.request(
+      "GET",
+      "/api/folders/tree"
+    );
+    return folders;
+  }
+  async create(name, parentId = null) {
+    const { folder } = await this.client.request("POST", "/api/folders", {
+      name,
+      parentId
+    });
+    return folder;
+  }
+  async rename(id, name) {
+    const { folder } = await this.client.request(
+      "PATCH",
+      `/api/folders/${id}`,
+      { name }
+    );
+    return folder;
+  }
+  async star(id, starred = true) {
+    const { folder } = await this.client.request(
+      "PATCH",
+      `/api/folders/${id}`,
+      { starred }
+    );
+    return folder;
+  }
+  async move(id, parentId) {
+    const { folder } = await this.client.request(
+      "POST",
+      `/api/folders/${id}/move`,
+      { parentId }
+    );
+    return folder;
+  }
+  async trash(id) {
+    return this.client.request("POST", `/api/folders/${id}/trash`);
+  }
+  async restore(id) {
+    return this.client.request("POST", `/api/folders/${id}/restore`);
+  }
+  /** Permanently deletes the folder subtree and its Telegram objects. */
+  async delete(id) {
+    return this.client.request("DELETE", `/api/folders/${id}`);
+  }
+  async batch(operation, ids, options = {}) {
+    return this.client.request("POST", "/api/folders/batch", {
+      operation,
+      ids,
+      ...operation === "move" ? { parentId: options.parentId ?? null } : {}
     });
-    if (response.status === 204) return void 0;
-    const data = await response.json().catch(() => null);
-    if (!response.ok) {
-      const error = data?.error;
-      throw new OmniCloudError(
-        response.status,
-        error?.code ?? "INTERNAL_ERROR",
-        error?.message ?? `Request failed (${response.status})`
-      );
-    }
-    return data;
+  }
+};
+var TrashApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list(query = {}) {
+    return this.client.request("GET", `/api/trash${buildQuery(query)}`);
+  }
+  /** Permanently removes everything in the Trash. */
+  async empty() {
+    return this.client.request("POST", "/api/trash/empty");
+  }
+};
+var StorageApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Creates the private storage channel if it does not exist yet. */
+  async ensure() {
+    const { storage } = await this.client.request(
+      "POST",
+      "/api/storage/ensure"
+    );
+    return storage;
+  }
+  async stats() {
+    const { stats } = await this.client.request(
+      "GET",
+      "/api/storage/stats"
+    );
+    return stats;
+  }
+  async health() {
+    return this.client.request("GET", "/api/storage/health");
+  }
+  /** Probes the storage backend; `deep` performs a real Telegram round-trip. */
+  async check(deep = false) {
+    const { health } = await this.client.request(
+      "POST",
+      "/api/storage/health/check",
+      { deep }
+    );
+    return health;
+  }
+  /** Read-only integrity scan; nothing is repaired or deleted. */
+  async integrityCheck(options = {}) {
+    const { report } = await this.client.request(
+      "POST",
+      "/api/storage/integrity/check",
+      { deep: options.deep ?? false }
+    );
+    return report;
+  }
+  /** Public server health (no authentication required). */
+  async serverHealth() {
+    return this.client.request("GET", "/api/health");
+  }
+};
+var SearchApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Searches with the v0.2 query language:
+   *   `type:pdf`, `size:>100MB`, `folder:Projects`, `starred:true`, `after:2026-01-01`
+   */
+  async query(q, page = {}) {
+    return this.client.request(
+      "GET",
+      `/api/search${buildQuery({ q, ...page })}`
+    );
+  }
+};
+var RecentApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list(page = {}) {
+    return this.client.request("GET", `/api/recent${buildQuery(page)}`);
+  }
+};
+var ActivityApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list(page = {}) {
+    return this.client.request("GET", `/api/activity${buildQuery(page)}`);
+  }
+};
+var AuthApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async me() {
+    return this.client.request("GET", "/api/auth/me");
+  }
+  async startTelegramLogin(phone) {
+    await this.client.request("POST", "/api/auth/telegram/start", { phone });
+  }
+  async verifyTelegramCode(phone, code) {
+    return this.client.request("POST", "/api/auth/telegram/verify", {
+      phone,
+      code
+    });
+  }
+  async submitTelegramPassword(phone, password) {
+    return this.client.request("POST", "/api/auth/telegram/password", { phone, password });
+  }
+  async logout() {
+    await this.client.request("POST", "/api/auth/logout");
   }
 };
 
@@ -289,18 +634,205 @@ function fileCategory(mimeType) {
   if (OFFICE_MIMES.has(mimeType)) return "document";
   return "other";
 }
+var FILE_CATEGORIES = [
+  "image",
+  "video",
+  "audio",
+  "pdf",
+  "archive",
+  "document",
+  "text",
+  "other"
+];
+var CATEGORY_PREFIXES = {
+  image: ["image/"],
+  video: ["video/"],
+  audio: ["audio/"],
+  pdf: ["application/pdf"],
+  archive: [
+    "application/zip",
+    "application/x-tar",
+    "application/gzip",
+    "application/x-7z-compressed",
+    "application/vnd.rar",
+    "application/x-bzip2",
+    "application/x-xz"
+  ],
+  text: [
+    "text/",
+    "application/json",
+    "application/xml",
+    "application/yaml",
+    "application/javascript"
+  ],
+  document: [...OFFICE_MIMES],
+  other: []
+};
+function isFileCategory(value) {
+  return FILE_CATEGORIES.includes(value);
+}
+function mimeMatchersForType(value) {
+  const normalized = value.toLowerCase().trim();
+  if (!normalized) return null;
+  if (isFileCategory(normalized)) {
+    const prefixes = CATEGORY_PREFIXES[normalized];
+    return prefixes.length > 0 ? prefixes : null;
+  }
+  return [normalized];
+}
+
+// ../shared/src/query.ts
+var SIZE_UNITS = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 ** 2,
+  gb: 1024 ** 3,
+  tb: 1024 ** 4
+};
+function parseSize(value) {
+  const match = /^\s*([0-9]+(?:\.[0-9]+)?)\s*([a-zA-Z]*)\s*$/.exec(value);
+  if (!match) return null;
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount < 0) return null;
+  const unit = (match[2] ?? "").toLowerCase() || "b";
+  const factor = SIZE_UNITS[unit];
+  if (factor === void 0) return null;
+  return Math.round(amount * factor);
+}
+function parseSizeComparison(value) {
+  const match = /^\s*(>=|<=|>|<|=)?\s*(.+)$/.exec(value);
+  if (!match) return null;
+  const operator = match[1] ?? "=";
+  const bytes = parseSize(match[2]);
+  if (bytes === null) return null;
+  switch (operator) {
+    case ">":
+      return { min: bytes + 1 };
+    case ">=":
+      return { min: bytes };
+    case "<":
+      return { max: bytes - 1 };
+    case "<=":
+      return { max: bytes };
+    default:
+      return { min: bytes, max: bytes };
+  }
+}
+function parseBoolean(value) {
+  const normalized = value.toLowerCase();
+  if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "n", "off"].includes(normalized)) return false;
+  return null;
+}
+function parseDate(value, endOfDay) {
+  const trimmed = value.trim();
+  if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+    const date2 = /* @__PURE__ */ new Date(`${trimmed}T${endOfDay ? "23:59:59.999" : "00:00:00.000"}Z`);
+    return Number.isNaN(date2.getTime()) ? null : date2;
+  }
+  const date = new Date(trimmed);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+function parseSearchQuery(input, base = {}) {
+  const query = { ...base };
+  const terms = [];
+  for (const rawToken of input.trim().split(/\s+/)) {
+    if (!rawToken) continue;
+    const separator = rawToken.indexOf(":");
+    if (separator <= 0) {
+      terms.push(rawToken);
+      continue;
+    }
+    const field = rawToken.slice(0, separator).toLowerCase();
+    const value = rawToken.slice(separator + 1);
+    if (!value) {
+      terms.push(rawToken);
+      continue;
+    }
+    switch (field) {
+      case "name":
+      case "filename":
+        terms.push(value);
+        break;
+      case "type":
+        query.type = value.toLowerCase();
+        break;
+      case "ext":
+      case "extension":
+        query.ext = value.replace(/^\./, "").toLowerCase();
+        break;
+      case "size": {
+        const comparison = parseSizeComparison(value);
+        if (!comparison) {
+          terms.push(rawToken);
+          break;
+        }
+        if (comparison.min !== void 0) query.minSize = comparison.min;
+        if (comparison.max !== void 0) query.maxSize = comparison.max;
+        break;
+      }
+      case "folder":
+        query.folderName = value;
+        break;
+      case "starred": {
+        const parsed = parseBoolean(value);
+        if (parsed === null) terms.push(rawToken);
+        else query.starred = parsed;
+        break;
+      }
+      case "trashed":
+      case "deleted": {
+        const parsed = parseBoolean(value);
+        if (parsed === null) terms.push(rawToken);
+        else query.status = parsed ? "trashed" : "active";
+        break;
+      }
+      case "after":
+      case "since": {
+        const date = parseDate(value, false);
+        if (!date) terms.push(rawToken);
+        else query.from = date.toISOString();
+        break;
+      }
+      case "before": {
+        const date = parseDate(value, true);
+        if (!date) terms.push(rawToken);
+        else query.to = date.toISOString();
+        break;
+      }
+      default:
+        terms.push(rawToken);
+        break;
+    }
+  }
+  const freeText = terms.join(" ").trim();
+  if (freeText) query.q = freeText;
+  return { query, freeText };
+}
+function paginationMeta(page, limit, total) {
+  return { page, limit, total, hasMore: page * limit < total };
+}
 
 // ../shared/src/index.ts
 var ERROR_CODES = {
-  VALIDATION: "VALIDATION_ERROR",
-  UNAUTHENTICATED: "UNAUTHENTICATED",
-  FORBIDDEN: "FORBIDDEN",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_INVALID: "AUTH_INVALID",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  INVALID_REQUEST: "INVALID_REQUEST",
   NOT_FOUND: "NOT_FOUND",
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  FOLDER_NOT_FOUND: "FOLDER_NOT_FOUND",
   CONFLICT: "CONFLICT",
   PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
   RATE_LIMITED: "RATE_LIMITED",
   STORAGE_NOT_INITIALIZED: "STORAGE_NOT_INITIALIZED",
-  TELEGRAM_ERROR: "TELEGRAM_ERROR",
+  STORAGE_UNAVAILABLE: "STORAGE_UNAVAILABLE",
+  TELEGRAM_AUTH_REQUIRED: "TELEGRAM_AUTH_REQUIRED",
+  TELEGRAM_CONNECTION_FAILED: "TELEGRAM_CONNECTION_FAILED",
+  TELEGRAM_FILE_NOT_FOUND: "TELEGRAM_FILE_NOT_FOUND",
+  UPLOAD_FAILED: "UPLOAD_FAILED",
+  DOWNLOAD_FAILED: "DOWNLOAD_FAILED",
+  INTEGRITY_CHECK_FAILED: "INTEGRITY_CHECK_FAILED",
   INTERNAL: "INTERNAL_ERROR"
 };
 
@@ -319,22 +851,31 @@ var DomainError = class extends Error {
 };
 var ValidationError = class extends DomainError {
   constructor(message, details) {
-    super(ERROR_CODES.VALIDATION, 400, message, details);
+    super(ERROR_CODES.INVALID_REQUEST, 400, message, details);
   }
 };
 var UnauthorizedError = class extends DomainError {
   constructor(message = "Authentication required") {
-    super(ERROR_CODES.UNAUTHENTICATED, 401, message);
+    super(ERROR_CODES.AUTH_REQUIRED, 401, message);
   }
 };
 var ForbiddenError = class extends DomainError {
   constructor(message = "You do not have access to this resource") {
-    super(ERROR_CODES.FORBIDDEN, 403, message);
+    super(ERROR_CODES.PERMISSION_DENIED, 403, message);
   }
 };
 var NotFoundError = class extends DomainError {
-  constructor(message = "Resource not found") {
-    super(ERROR_CODES.NOT_FOUND, 404, message);
+  constructor(message = "Resource not found", resource) {
+    super(
+      resource === "file" ? ERROR_CODES.FILE_NOT_FOUND : resource === "folder" ? ERROR_CODES.FOLDER_NOT_FOUND : ERROR_CODES.NOT_FOUND,
+      404,
+      message
+    );
+  }
+};
+var ConflictError = class extends DomainError {
+  constructor(message) {
+    super(ERROR_CODES.CONFLICT, 409, message);
   }
 };
 var RateLimitedError = class extends DomainError {
@@ -347,11 +888,39 @@ var StorageNotInitializedError = class extends DomainError {
     super(ERROR_CODES.STORAGE_NOT_INITIALIZED, 409, "Storage is not initialized for this account");
   }
 };
-var StorageProviderError = class extends DomainError {
-  constructor(message, details) {
-    super(ERROR_CODES.TELEGRAM_ERROR, 502, message, details);
+var TelegramAuthRequiredError = class extends DomainError {
+  constructor(message = "Your Telegram session has expired \u2014 please reconnect") {
+    super(ERROR_CODES.TELEGRAM_AUTH_REQUIRED, 401, message);
+  }
+};
+var TelegramConnectionError = class extends DomainError {
+  constructor(message = "Could not reach Telegram", details) {
+    super(ERROR_CODES.TELEGRAM_CONNECTION_FAILED, 502, message, details);
   }
 };
+var TelegramFileNotFoundError = class extends DomainError {
+  constructor(message = "The stored file is missing from Telegram") {
+    super(ERROR_CODES.TELEGRAM_FILE_NOT_FOUND, 404, message);
+  }
+};
+var UploadFailedError = class extends DomainError {
+  constructor(message = "Upload failed", details) {
+    super(ERROR_CODES.UPLOAD_FAILED, 502, message, details);
+  }
+};
+var OperationCancelledError = class extends DomainError {
+  constructor(message = "Operation cancelled") {
+    super(ERROR_CODES.INVALID_REQUEST, 499, message);
+  }
+};
+function mapProviderError(message, error) {
+  if (error instanceof DomainError) return error;
+  const detail = error instanceof Error ? error.message : String(error);
+  return new UploadFailedError(detail ? `${message}: ${detail}` : message, error);
+}
+
+// ../core/src/storage/engine.ts
+import { Readable } from "stream";
 
 // ../core/src/utils/hash.ts
 import { createHash } from "crypto";
@@ -360,49 +929,237 @@ function sha256Hex(data) {
 }
 
 // ../core/src/storage/engine.ts
+var DEFAULT_RETRY_POLICY = { attempts: 3, baseDelayMs: 400 };
+function isRetryable(error) {
+  if (error instanceof OperationCancelledError) return false;
+  const name = error instanceof Error ? error.name : "";
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error.code;
+  if (name === "AbortError" || code === "ABORT_ERR") return false;
+  if (/AUTH|PASSWORD|PHONE|FLOOD_WAIT|not found|invalid/i.test(message)) return false;
+  return true;
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new OperationCancelledError());
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new OperationCancelledError());
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw new OperationCancelledError();
+}
 var StorageEngine = class {
-  constructor(provider) {
+  constructor(provider, retryPolicy = DEFAULT_RETRY_POLICY) {
     this.provider = provider;
+    this.retryPolicy = retryPolicy;
   }
   provider;
+  retryPolicy;
   get providerName() {
     return this.provider.name;
   }
-  /** Uploads an object and computes its checksum in one step. */
-  async upload(input) {
-    const sha256 = sha256Hex(input.data);
-    let stored;
+  /**
+   * Uploads an object, computing its SHA-256 as it goes and reporting
+   * progress. Retries transient failures with exponential backoff.
+   */
+  async upload(input, control = {}) {
+    const data = await this.readInput(input);
+    const sha256 = sha256Hex(data);
+    control.onProgress?.({ transferred: 0, total: data.byteLength, percent: 0 });
+    const stored = await this.withRetry(
+      () => this.provider.put({ ...input, data }, control),
+      control,
+      (error) => new UploadFailedError("Upload failed", error)
+    );
+    control.onProgress?.({ transferred: data.byteLength, total: data.byteLength, percent: 100 });
+    return { stored, sha256, size: data.byteLength };
+  }
+  async download(ref, control = {}) {
+    return this.withRetry(
+      () => this.provider.get(ref, control),
+      control,
+      (error) => mapProviderError("Download failed", error)
+    );
+  }
+  /** Streams the object, computing the checksum on the fly when requested. */
+  async downloadStream(ref, control = {}) {
+    const stream = await this.withRetry(
+      () => this.provider.getStream(ref, control),
+      control,
+      (error) => mapProviderError("Download failed", error)
+    );
+    return { stream, hash: () => null };
+  }
+  async remove(ref) {
+    await this.withRetry(
+      () => this.provider.delete(ref),
+      {},
+      (error) => mapProviderError("Delete failed", error)
+    );
+  }
+  async exists(ref) {
     try {
-      stored = await this.provider.put(input);
+      return await this.provider.exists(ref);
     } catch (error) {
-      throw mapProviderError("Upload failed", error);
+      throw mapProviderError("Storage lookup failed", error);
     }
-    return { stored, sha256, size: input.data.byteLength };
   }
-  async download(ref) {
+  async stat(ref) {
     try {
-      return await this.provider.get(ref);
+      return await this.provider.stat(ref);
     } catch (error) {
-      throw mapProviderError("Download failed", error);
+      throw mapProviderError("Storage lookup failed", error);
     }
   }
-  async remove(ref) {
+  async health() {
     try {
-      await this.provider.delete(ref);
+      return await this.provider.healthCheck();
     } catch (error) {
-      throw mapProviderError("Delete failed", error);
+      return {
+        healthy: false,
+        latencyMs: null,
+        message: error instanceof Error ? error.message : "Storage health check failed",
+        targetTitle: null
+      };
     }
   }
   async verifyIntegrity(data, expectedSha256) {
     return sha256Hex(data) === expectedSha256;
   }
+  // ── internals ────────────────────────────────────────────────────────────
+  /** Materializes an upload input so the checksum can be computed. */
+  async readInput(input) {
+    if (input.data) return input.data;
+    if (!input.stream) {
+      throw new UploadFailedError("Upload input has neither data nor a stream");
+    }
+    const chunks = [];
+    for await (const chunk of input.stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  async withRetry(operation, control, wrapError) {
+    const { attempts, baseDelayMs } = this.retryPolicy;
+    let lastError;
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt += 1) {
+      throwIfAborted(control.signal);
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+        if (attempt >= attempts || !isRetryable(error)) break;
+        await delay(baseDelayMs * 2 ** (attempt - 1), control.signal);
+      }
+    }
+    throw wrapError(lastError);
+  }
 };
-function mapProviderError(message, error) {
-  if (error instanceof StorageProviderError) return error;
-  const detail = error instanceof Error ? error.message : String(error);
-  return new StorageProviderError(detail ? `${message}: ${detail}` : message, error);
+
+// ../core/src/services/query-resolver.ts
+async function resolveItemQuery(folders, userId, input) {
+  const query = {};
+  if (input.folderId !== void 0) query.folderId = input.folderId;
+  if (input.q && input.q.trim()) query.nameContains = input.q.trim();
+  if (input.ext) query.ext = input.ext.replace(/^\./, "").toLowerCase();
+  if (input.starred !== void 0) query.starred = input.starred;
+  if (input.minSize !== void 0) query.minSize = input.minSize;
+  if (input.maxSize !== void 0) query.maxSize = input.maxSize;
+  if (input.sort) query.sort = input.sort;
+  if (input.order) query.order = input.order;
+  switch (input.status) {
+    case "active":
+      query.trashed = false;
+      break;
+    case "trashed":
+      query.trashed = true;
+      break;
+    default:
+      query.trashed = void 0;
+      break;
+  }
+  if (input.type) {
+    const matchers = mimeMatchersForType(input.type);
+    if (matchers) query.mimeMatchers = matchers;
+  }
+  if (input.from) {
+    const from = new Date(input.from);
+    if (!Number.isNaN(from.getTime())) query.from = from;
+  }
+  if (input.to) {
+    const to = new Date(input.to);
+    if (!Number.isNaN(to.getTime())) query.to = to;
+  }
+  if (input.folderName) {
+    query.folderIds = await folders.findIdsByName(userId, input.folderName);
+  }
+  return query;
 }
 
+// ../core/src/services/activity-service.ts
+var ActivityService = class {
+  constructor(activity, retentionDays = 90) {
+    this.activity = activity;
+    this.retentionDays = retentionDays;
+  }
+  activity;
+  retentionDays;
+  /**
+   * Records an event. Never throws — a logging failure must not fail the
+   * user-facing operation that produced it.
+   */
+  async record(input) {
+    try {
+      await this.activity.record({
+        userId: input.userId,
+        action: input.action,
+        resourceType: input.resourceType,
+        resourceId: input.resourceId,
+        resourceName: input.resourceName ?? null,
+        metadata: sanitizeMetadata(input.metadata)
+      });
+    } catch {
+    }
+  }
+  async list(userId, page) {
+    return this.activity.list(userId, page);
+  }
+  /** Most recent distinct files for the given actions, for the Recent view. */
+  async recentFiles(userId, actions, limit) {
+    return this.activity.recentFiles(userId, actions, limit);
+  }
+  async prune() {
+    const cutoff = new Date(Date.now() - this.retentionDays * 24 * 60 * 60 * 1e3);
+    return this.activity.pruneOlderThan(cutoff);
+  }
+};
+var SENSITIVE_KEY = /(password|secret|token|session|hash|credential)/i;
+function sanitizeMetadata(metadata) {
+  if (!metadata) return null;
+  const clean = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (SENSITIVE_KEY.test(key)) continue;
+    if (value === void 0) continue;
+    clean[key] = value;
+  }
+  return Object.keys(clean).length > 0 ? clean : null;
+}
+var noopActivityRecorder = {
+  async record() {
+  }
+};
+
 // ../core/src/utils/filename.ts
 function sanitizeFileName(name) {
   const base = name.split(/[/\\]/).pop() ?? name;
@@ -413,170 +1170,588 @@ function sanitizeFileName(name) {
 
 // ../core/src/services/file-service.ts
 var FileService = class {
-  constructor(files, folders, engineFor) {
+  constructor(files, folders, engineFor, activity = noopActivityRecorder) {
     this.files = files;
     this.folders = folders;
     this.engineFor = engineFor;
+    this.activity = activity;
   }
   files;
   folders;
   engineFor;
+  activity;
+  // ── Upload ───────────────────────────────────────────────────────────────
   async upload(userId, input) {
     const name = sanitizeFileName(input.name);
     if (!name) throw new ValidationError("Invalid file name");
-    if (input.folderId !== null) {
-      const folder = await this.folders.findById(input.folderId);
-      if (!folder || folder.userId !== userId) throw new NotFoundError("Folder not found");
+    let folderId = input.folderId;
+    if (input.replaceFileId) {
+      const existing = await this.get(userId, input.replaceFileId);
+      folderId = existing.folderId;
+    } else if (folderId !== null) {
+      await this.assertFolder(userId, folderId);
     }
     const mimeType = mimeFromFilename(name);
     const engine = await this.engineFor(userId);
-    const { stored, sha256, size } = await engine.upload({ name, mimeType, data: input.data });
-    return this.files.create({
+    const control = {
+      onProgress: input.onProgress,
+      signal: input.signal
+    };
+    const { stored, sha256, size } = await engine.upload(
+      { name, mimeType, data: input.data },
+      control
+    );
+    const telegramMessageId = Number(stored.messageId);
+    if (input.replaceFileId) {
+      return this.replaceVersion(userId, input.replaceFileId, {
+        name,
+        size,
+        mimeType,
+        sha256,
+        telegramMessageId
+      });
+    }
+    const record = await this.files.create({
       userId,
-      folderId: input.folderId,
+      folderId,
       name,
       size,
       mimeType,
       sha256,
-      telegramMessageId: Number(stored.messageId)
+      telegramMessageId
     });
+    const version = await this.files.createVersion({
+      fileId: record.id,
+      userId,
+      size,
+      mimeType,
+      sha256,
+      telegramMessageId
+    });
+    const withVersion = await this.files.update(record.id, {
+      currentVersionId: version.id,
+      versionCount: 1
+    });
+    await this.activity.record({
+      userId,
+      action: "upload",
+      resourceType: "file",
+      resourceId: withVersion.id,
+      resourceName: withVersion.name,
+      metadata: { size, mimeType }
+    });
+    return withVersion;
+  }
+  /** Uploads a new version of an existing file and makes it current. */
+  async replaceVersion(userId, fileId, next) {
+    const existing = await this.get(userId, fileId);
+    const version = await this.files.createVersion({
+      fileId,
+      userId,
+      size: next.size,
+      mimeType: next.mimeType,
+      sha256: next.sha256,
+      telegramMessageId: next.telegramMessageId
+    });
+    const count = await this.files.countVersions(fileId);
+    const updated = await this.files.update(fileId, {
+      name: next.name,
+      size: next.size,
+      mimeType: next.mimeType,
+      sha256: next.sha256,
+      telegramMessageId: next.telegramMessageId,
+      currentVersionId: version.id,
+      versionCount: count
+    });
+    await this.activity.record({
+      userId,
+      action: "replace",
+      resourceType: "file",
+      resourceId: fileId,
+      resourceName: updated.name,
+      metadata: { previousSha256: existing.sha256, size: next.size }
+    });
+    return updated;
   }
+  // ── Reads ────────────────────────────────────────────────────────────────
   async list(userId, folderId) {
-    if (folderId !== null) {
-      const folder = await this.folders.findById(folderId);
-      if (!folder || folder.userId !== userId) throw new NotFoundError("Folder not found");
-    }
+    if (folderId !== null) await this.assertFolder(userId, folderId);
     return this.files.listByFolder(userId, folderId);
   }
+  async query(userId, input, page) {
+    if (input.folderId != null) await this.assertFolder(userId, input.folderId);
+    const query = await resolveItemQuery(this.folders, userId, input);
+    return this.files.query(userId, query, page);
+  }
   async get(userId, id) {
     const record = await this.files.findById(id);
-    if (!record || record.userId !== userId) throw new NotFoundError("File not found");
+    if (!record || record.userId !== userId) throw new NotFoundError("File not found", "file");
     return record;
   }
-  async rename(userId, id, name) {
+  /** Like get(), but rejects trashed files (for download/open). */
+  async getActive(userId, id) {
+    const record = await this.get(userId, id);
+    if (record.deletedAt) throw new NotFoundError("File not found", "file");
+    return record;
+  }
+  async listVersions(userId, id) {
     await this.get(userId, id);
+    return this.files.listVersions(id);
+  }
+  // ── Mutations ────────────────────────────────────────────────────────────
+  async rename(userId, id, name) {
+    const existing = await this.get(userId, id);
     const clean = sanitizeFileName(name);
     if (!clean) throw new ValidationError("Invalid file name");
-    return this.files.update(id, { name: clean });
+    const updated = await this.files.update(id, { name: clean });
+    await this.activity.record({
+      userId,
+      action: "rename",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: clean,
+      metadata: { previousName: existing.name }
+    });
+    return updated;
   }
   async move(userId, id, folderId) {
+    const existing = await this.get(userId, id);
+    if (folderId !== null) await this.assertFolder(userId, folderId);
+    const updated = await this.files.update(id, { folderId });
+    await this.activity.record({
+      userId,
+      action: "move",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: updated.name,
+      metadata: { from: existing.folderId, to: folderId }
+    });
+    return updated;
+  }
+  async setStarred(userId, id, starred) {
     await this.get(userId, id);
+    const updated = await this.files.update(id, { starred });
+    await this.activity.record({
+      userId,
+      action: starred ? "star" : "unstar",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: updated.name
+    });
+    return updated;
+  }
+  /**
+   * Moves a file to Trash (soft delete). The remote object is untouched, so
+   * restore is lossless.
+   */
+  async trash(userId, id) {
+    const record = await this.get(userId, id);
+    if (record.deletedAt) return record;
+    const updated = await this.files.update(id, {
+      deletedAt: /* @__PURE__ */ new Date(),
+      trashBatchId: `solo-${id}`
+    });
+    await this.activity.record({
+      userId,
+      action: "trash",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: updated.name
+    });
+    return updated;
+  }
+  /** Restores a trashed file to its previous folder (or root). */
+  async restore(userId, id) {
+    const record = await this.get(userId, id);
+    let folderId = record.folderId;
     if (folderId !== null) {
       const folder = await this.folders.findById(folderId);
-      if (!folder || folder.userId !== userId) throw new NotFoundError("Folder not found");
+      if (!folder || folder.userId !== userId || folder.deletedAt) folderId = null;
     }
-    return this.files.update(id, { folderId });
+    const updated = await this.files.update(id, { deletedAt: null, trashBatchId: null, folderId });
+    await this.activity.record({
+      userId,
+      action: "restore",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: updated.name
+    });
+    return updated;
   }
-  async delete(userId, id) {
+  /**
+   * Permanently deletes a file: the Telegram object is removed first, then the
+   * metadata. If the remote delete fails we keep the metadata so the user can
+   * retry, rather than silently orphaning the storage object.
+   */
+  async deletePermanently(userId, id) {
     const record = await this.get(userId, id);
     const engine = await this.engineFor(userId);
-    try {
-      await engine.remove({ messageId: String(record.telegramMessageId) });
-    } catch {
+    await engine.remove({ messageId: String(record.telegramMessageId) });
+    const versions = await this.files.listVersions(id);
+    for (const version of versions) {
+      if (version.telegramMessageId === record.telegramMessageId) continue;
+      try {
+        await engine.remove({ messageId: String(version.telegramMessageId) });
+      } catch {
+      }
+    }
+    await this.files.deleteVersionsByFileIds([id]);
+    await this.files.deleteMany([id]);
+    await this.activity.record({
+      userId,
+      action: "delete",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: record.name
+    });
+  }
+  /**
+   * v0.1-compatible hard delete used by the current API: permanently removes
+   * the file. Retained so existing clients keep working.
+   */
+  async delete(userId, id) {
+    await this.deletePermanently(userId, id);
+  }
+  // ── Download ─────────────────────────────────────────────────────────────
+  async download(userId, id, control = {}) {
+    const record = await this.getActive(userId, id);
+    const engine = await this.engineFor(userId);
+    const data = await engine.download({ messageId: String(record.telegramMessageId) }, control);
+    const integrityVerified = await engine.verifyIntegrity(data, record.sha256);
+    await this.activity.record({
+      userId,
+      action: "download",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: record.name,
+      metadata: { size: record.size, integrityVerified }
+    });
+    return { record, data, integrityVerified };
+  }
+  /** Records an "open" event (the UI opening the details panel, say). */
+  async touch(userId, id, action = "open") {
+    const record = await this.get(userId, id);
+    await this.activity.record({
+      userId,
+      action,
+      resourceType: "file",
+      resourceId: id,
+      resourceName: record.name
+    });
+  }
+  // ── Batch operations ─────────────────────────────────────────────────────
+  /**
+   * Applies an operation to many files, collecting per-item failures instead
+   * of aborting the whole batch.
+   */
+  async batch(userId, ids, operation, options = {}) {
+    const errors = [];
+    let succeeded = 0;
+    if (ids.length === 0) throw new ValidationError("No items selected");
+    if (operation === "move") {
+      const target = options.folderId ?? null;
+      if (target !== null) await this.assertFolder(userId, target);
+    }
+    for (const id of ids) {
+      try {
+        switch (operation) {
+          case "trash":
+            await this.trash(userId, id);
+            break;
+          case "restore":
+            await this.restore(userId, id);
+            break;
+          case "delete":
+            await this.deletePermanently(userId, id);
+            break;
+          case "star":
+            await this.setStarred(userId, id, true);
+            break;
+          case "unstar":
+            await this.setStarred(userId, id, false);
+            break;
+          case "move":
+            await this.move(userId, id, options.folderId ?? null);
+            break;
+        }
+        succeeded += 1;
+      } catch (error) {
+        errors.push({ id, message: error instanceof Error ? error.message : "Operation failed" });
+      }
     }
-    await this.files.deleteMany([record.id]);
+    return { requested: ids.length, succeeded, failed: errors.length, errors };
   }
-  async download(userId, id) {
-    const record = await this.get(userId, id);
-    const engine = await this.engineFor(userId);
-    const data = await engine.download({ messageId: String(record.telegramMessageId) });
-    const integrityVerified = await engine.verifyIntegrity(data, record.sha256);
-    return { record, data, integrityVerified };
+  // ── internals ────────────────────────────────────────────────────────────
+  async assertFolder(userId, folderId) {
+    const folder = await this.folders.findById(folderId);
+    if (!folder || folder.userId !== userId) {
+      throw new NotFoundError("Folder not found", "folder");
+    }
+    if (folder.deletedAt) throw new ConflictError("The target folder is in the Trash");
   }
 };
 
 // ../core/src/services/folder-service.ts
 var FolderService = class {
-  constructor(folders, files, engineFor) {
+  constructor(folders, files, engineFor, activity = noopActivityRecorder) {
     this.folders = folders;
     this.files = files;
     this.engineFor = engineFor;
+    this.activity = activity;
   }
   folders;
   files;
   engineFor;
+  activity;
+  // ── Create / read ────────────────────────────────────────────────────────
   async create(userId, input) {
     const name = sanitizeFileName(input.name);
     if (!name) throw new ValidationError("Invalid folder name");
     if (input.parentId !== null) {
-      const parent = await this.folders.findById(input.parentId);
-      if (!parent || parent.userId !== userId) throw new NotFoundError("Folder not found");
+      const parent = await this.get(userId, input.parentId);
+      if (parent.deletedAt) throw new ConflictError("The parent folder is in the Trash");
     }
-    return this.folders.create({ userId, parentId: input.parentId, name });
+    const folder = await this.folders.create({ userId, parentId: input.parentId, name });
+    await this.activity.record({
+      userId,
+      action: "create_folder",
+      resourceType: "folder",
+      resourceId: folder.id,
+      resourceName: folder.name
+    });
+    return folder;
   }
+  /** Active folders directly inside a folder (null = root). */
   async listChildren(userId, parentId) {
-    if (parentId !== null) {
-      const parent = await this.folders.findById(parentId);
-      if (!parent || parent.userId !== userId) throw new NotFoundError("Folder not found");
-    }
+    if (parentId !== null) await this.get(userId, parentId);
     return this.folders.listChildren(userId, parentId);
   }
+  async query(userId, input, page) {
+    const query = await resolveItemQuery(this.folders, userId, input);
+    return this.folders.query(userId, query, page);
+  }
+  /** Every active folder for the user (used to build trees). */
   async tree(userId) {
-    return this.folders.listByUser(userId);
+    const all = await this.folders.listByUser(userId);
+    return all.filter((folder) => folder.deletedAt === null);
   }
   async get(userId, id) {
     const record = await this.folders.findById(id);
-    if (!record || record.userId !== userId) throw new NotFoundError("Folder not found");
+    if (!record || record.userId !== userId) throw new NotFoundError("Folder not found", "folder");
     return record;
   }
+  // ── Mutations ────────────────────────────────────────────────────────────
   async rename(userId, id, name) {
-    await this.get(userId, id);
+    const existing = await this.get(userId, id);
     const clean = sanitizeFileName(name);
     if (!clean) throw new ValidationError("Invalid folder name");
-    return this.folders.update(id, { name: clean });
+    const updated = await this.folders.update(id, { name: clean });
+    await this.activity.record({
+      userId,
+      action: "rename",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: clean,
+      metadata: { previousName: existing.name }
+    });
+    return updated;
   }
   async move(userId, id, newParentId) {
-    await this.get(userId, id);
+    const existing = await this.get(userId, id);
     if (newParentId === id) throw new ValidationError("Cannot move a folder into itself");
     if (newParentId !== null) {
+      const target = await this.get(userId, newParentId);
+      if (target.deletedAt) throw new ConflictError("The target folder is in the Trash");
       let cursor = newParentId;
       while (cursor !== null) {
         if (cursor === id) {
           throw new ValidationError("Cannot move a folder into one of its subfolders");
         }
         const parent = await this.folders.findById(cursor);
-        if (!parent || parent.userId !== userId) throw new NotFoundError("Folder not found");
+        if (!parent || parent.userId !== userId)
+          throw new NotFoundError("Folder not found", "folder");
         cursor = parent.parentId;
       }
     }
-    return this.folders.update(id, { parentId: newParentId });
+    const updated = await this.folders.update(id, { parentId: newParentId });
+    await this.activity.record({
+      userId,
+      action: "move",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: updated.name,
+      metadata: { from: existing.parentId, to: newParentId }
+    });
+    return updated;
   }
-  async delete(userId, id) {
+  async setStarred(userId, id, starred) {
+    await this.get(userId, id);
+    const updated = await this.folders.update(id, { starred });
+    await this.activity.record({
+      userId,
+      action: starred ? "star" : "unstar",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: updated.name
+    });
+    return updated;
+  }
+  // ── Trash lifecycle ──────────────────────────────────────────────────────
+  /**
+   * Moves a folder and its entire subtree to the Trash. Nothing is deleted
+   * from Telegram, so restore is lossless.
+   */
+  async trash(userId, id) {
+    const record = await this.get(userId, id);
+    if (record.deletedAt) {
+      return { affectedFolders: 1, affectedFiles: 0 };
+    }
+    const subtree = await this.collectSubtree(userId, id);
+    const fileIds = await this.collectFileIds(userId, subtree);
+    const batchId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const stampedAt = /* @__PURE__ */ new Date();
+    await this.folders.updateMany(
+      subtree.map((folder) => folder.id),
+      { deletedAt: stampedAt, trashBatchId: batchId }
+    );
+    await this.files.updateMany(fileIds, { deletedAt: stampedAt, trashBatchId: batchId });
+    await this.activity.record({
+      userId,
+      action: "trash",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: record.name,
+      metadata: { folders: subtree.length, files: fileIds.length }
+    });
+    return { affectedFolders: subtree.length, affectedFiles: fileIds.length };
+  }
+  /**
+   * Restores a folder subtree. Only nodes trashed at the same instant as the
+   * folder itself are restored, so items the user trashed separately stay put.
+   */
+  async restore(userId, id) {
+    const record = await this.get(userId, id);
+    let parentId = record.parentId;
+    if (parentId !== null) {
+      const parent = await this.folders.findById(parentId);
+      if (!parent || parent.deletedAt) parentId = null;
+    }
+    const subtree = await this.collectSubtree(userId, id, { includeTrashed: true });
+    const batchId = record.trashBatchId;
+    const belongsToBatch = (deletedAt, marker) => deletedAt !== null && (batchId !== null ? marker === batchId : record.deletedAt !== null && deletedAt.getTime() === record.deletedAt.getTime());
+    const restorableFolders = subtree.filter(
+      (folder) => belongsToBatch(folder.deletedAt, folder.trashBatchId)
+    );
+    const restorableFolderIds = new Set(restorableFolders.map((folder) => folder.id));
+    const allFiles = await this.files.listByUser(userId);
+    const restorableFiles = allFiles.filter(
+      (file) => file.folderId !== null && restorableFolderIds.has(file.folderId) && belongsToBatch(file.deletedAt, file.trashBatchId)
+    );
+    const restorableFileIds = restorableFiles.map((file) => file.id);
+    if (restorableFolders.length > 0) {
+      await this.folders.updateMany(
+        restorableFolders.map((folder) => folder.id),
+        { deletedAt: null, trashBatchId: null }
+      );
+      await this.folders.update(id, { parentId });
+    }
+    if (restorableFileIds.length > 0) {
+      await this.files.updateMany(restorableFileIds, { deletedAt: null, trashBatchId: null });
+    }
+    await this.activity.record({
+      userId,
+      action: "restore",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: record.name,
+      metadata: { folders: restorableFolders.length, files: restorableFiles.length }
+    });
+    return { affectedFolders: restorableFolders.length, affectedFiles: restorableFiles.length };
+  }
+  /**
+   * Permanently deletes a folder subtree: remote objects first, then
+   * metadata. Files whose remote delete fails are left in the Trash so the
+   * user can retry rather than losing data silently.
+   */
+  async deletePermanently(userId, id) {
     await this.get(userId, id);
+    const subtree = await this.collectSubtree(userId, id, { includeTrashed: true });
+    const folderIds = subtree.map((folder) => folder.id);
+    const allFiles = await this.files.listByUser(userId);
+    const affected = allFiles.filter(
+      (file) => file.folderId !== null && folderIds.includes(file.folderId)
+    );
+    const engine = await this.engineFor(userId);
+    const removedFileIds = [];
+    for (const file of affected) {
+      try {
+        await engine.remove({ messageId: String(file.telegramMessageId) });
+        removedFileIds.push(file.id);
+      } catch {
+      }
+    }
+    if (removedFileIds.length > 0) {
+      await this.files.deleteVersionsByFileIds(removedFileIds);
+      await this.files.deleteMany(removedFileIds);
+    }
+    const remainingFolderIds = new Set(
+      affected.filter((file) => !removedFileIds.includes(file.id)).map((file) => file.folderId)
+    );
+    const deletable = folderIds.filter((folderId) => !remainingFolderIds.has(folderId));
+    if (deletable.length > 0) {
+      await this.folders.deleteMany(deletable);
+    }
+    await this.activity.record({
+      userId,
+      action: "delete",
+      resourceType: "folder",
+      resourceId: id,
+      resourceName: subtree[0]?.name ?? "folder",
+      metadata: { folders: deletable.length, files: removedFileIds.length }
+    });
+    return { affectedFolders: deletable.length, affectedFiles: removedFileIds.length };
+  }
+  /**
+   * v0.1-compatible recursive delete. Now routes through the v0.2 permanent
+   * delete so remote cleanup and orphan prevention are consistent.
+   */
+  async delete(userId, id) {
+    return this.deletePermanently(userId, id);
+  }
+  // ── internals ────────────────────────────────────────────────────────────
+  /** The folder plus every descendant (BFS), optionally including trashed. */
+  async collectSubtree(userId, rootId, options = {}) {
     const all = await this.folders.listByUser(userId);
     const childrenOf = /* @__PURE__ */ new Map();
     for (const folder of all) {
       const list = childrenOf.get(folder.parentId) ?? [];
-      list.push(folder.id);
+      list.push(folder);
       childrenOf.set(folder.parentId, list);
     }
-    const doomed = [id];
-    const queue = [id];
+    const root = all.find((folder) => folder.id === rootId);
+    if (!root) throw new NotFoundError("Folder not found", "folder");
+    const collected = [root];
+    const queue = [rootId];
     while (queue.length > 0) {
       const current = queue.shift();
       for (const child of childrenOf.get(current) ?? []) {
-        doomed.push(child);
-        queue.push(child);
-      }
-    }
-    const doomedSet = new Set(doomed);
-    const userFiles = await this.files.listByUser(userId);
-    const affectedFiles = userFiles.filter((f) => f.folderId !== null && doomedSet.has(f.folderId));
-    const engine = await this.engineFor(userId);
-    for (const file of affectedFiles) {
-      try {
-        await engine.remove({ messageId: String(file.telegramMessageId) });
-      } catch {
+        if (!options.includeTrashed && child.deletedAt) continue;
+        collected.push(child);
+        queue.push(child.id);
       }
     }
-    await this.files.deleteMany(affectedFiles.map((f) => f.id));
-    await this.folders.deleteMany(doomed);
-    return { deletedFolders: doomed.length, deletedFiles: affectedFiles.length };
+    return collected;
+  }
+  /** Ids of files inside the given folders that are not already trashed. */
+  async collectFileIds(userId, folders) {
+    const ids = new Set(folders.map((folder) => folder.id));
+    const allFiles = await this.files.listByUser(userId);
+    return allFiles.filter((file) => file.deletedAt === null && file.folderId !== null && ids.has(file.folderId)).map((file) => file.id);
   }
 };
 
 // ../core/src/services/search-service.ts
-var MAX_QUERY_LENGTH = 100;
+var MAX_QUERY_LENGTH = 200;
 var SearchService = class {
   constructor(files, folders) {
     this.files = files;
@@ -584,23 +1759,316 @@ var SearchService = class {
   }
   files;
   folders;
-  async search(userId, query, limit = 25) {
-    const q = query.trim();
-    if (!q) throw new ValidationError("Search query must not be empty");
-    if (q.length > MAX_QUERY_LENGTH) {
+  async search(userId, rawQuery, page, overrides = {}) {
+    const trimmed = rawQuery.trim();
+    if (!trimmed) throw new ValidationError("Search query must not be empty");
+    if (trimmed.length > MAX_QUERY_LENGTH) {
       throw new ValidationError(`Search query must be at most ${MAX_QUERY_LENGTH} characters`);
     }
-    const [fileResults, folderResults] = await Promise.all([
-      this.files.searchByName(userId, q, limit),
-      this.folders.searchByName(userId, q, limit)
+    const { query } = parseSearchQuery(trimmed, overrides);
+    if (query.status === void 0) query.status = "all";
+    const itemQuery = await resolveItemQuery(this.folders, userId, query);
+    const [filePage, folderPage] = await Promise.all([
+      this.files.query(userId, itemQuery, page),
+      this.folders.query(userId, itemQuery, page)
+    ]);
+    const total = filePage.total + folderPage.total;
+    return {
+      files: filePage.items,
+      folders: folderPage.items,
+      pagination: paginationMeta(page.page, page.limit, total)
+    };
+  }
+  /** Convenience wrapper returning the shared DTO shape. */
+  async searchDTO(userId, rawQuery, page) {
+    return this.search(userId, rawQuery, page);
+  }
+};
+
+// ../core/src/services/stats-service.ts
+var LARGEST_FILES = 10;
+var StatsService = class {
+  constructor(files, folders) {
+    this.files = files;
+    this.folders = folders;
+  }
+  files;
+  folders;
+  async stats(userId, quotaBytes = null) {
+    const [counters, allFiles] = await Promise.all([
+      this.files.statsByUser(userId),
+      // Metadata-only aggregation; v0.2 datasets fit comfortably in memory.
+      this.files.listByUser(userId)
+    ]);
+    const active = allFiles.filter((file) => file.deletedAt === null);
+    const categoryBytes = /* @__PURE__ */ new Map();
+    for (const file of active) {
+      const category = fileCategory(file.mimeType);
+      const bucket = categoryBytes.get(category) ?? { bytes: 0, count: 0 };
+      bucket.bytes += file.size;
+      bucket.count += 1;
+      categoryBytes.set(category, bucket);
+    }
+    const byType = [...categoryBytes.entries()].map(([category, bucket]) => ({ category, bytes: bucket.bytes, count: bucket.count })).sort((a, b) => b.bytes - a.bytes);
+    const largestFiles = [...active].sort((a, b) => b.size - a.size).slice(0, LARGEST_FILES);
+    return {
+      fileCount: counters.fileCount,
+      folderCount: counters.folderCount,
+      totalBytes: counters.totalBytes,
+      trashBytes: counters.trashBytes,
+      trashFileCount: counters.trashFileCount,
+      starredCount: counters.starredCount,
+      byType,
+      largestFiles,
+      quotaBytes
+    };
+  }
+};
+
+// ../core/src/services/trash-service.ts
+var TrashService = class {
+  constructor(files, folders, engineFor) {
+    this.files = files;
+    this.folders = folders;
+    this.engineFor = engineFor;
+  }
+  files;
+  folders;
+  engineFor;
+  async list(userId, page, extra = {}) {
+    const itemQuery = await resolveItemQuery(this.folders, userId, {
+      ...extra,
+      status: "trashed",
+      folderId: void 0
+    });
+    const [filePage, folderPage] = await Promise.all([
+      this.files.query(userId, itemQuery, page),
+      this.folders.query(userId, itemQuery, page)
     ]);
-    return { files: fileResults, folders: folderResults };
+    const total = filePage.total + folderPage.total;
+    return {
+      files: filePage.items,
+      folders: folderPage.items,
+      pagination: paginationMeta(page.page, page.limit, total)
+    };
+  }
+  /**
+   * Permanently removes everything in the Trash for a user. Folders are
+   * processed root-first so removing a parent also removes its contents.
+   */
+  async empty(userId) {
+    const engine = await this.engineFor(userId);
+    const allFiles = await this.files.listByUser(userId);
+    const trashedFiles = allFiles.filter((file) => file.deletedAt !== null);
+    let deletedFiles = 0;
+    let failedFiles = 0;
+    const deletedFileIds = [];
+    for (const file of trashedFiles) {
+      try {
+        await engine.remove({ messageId: String(file.telegramMessageId) });
+        deletedFileIds.push(file.id);
+        deletedFiles += 1;
+      } catch {
+        failedFiles += 1;
+      }
+    }
+    if (deletedFileIds.length > 0) {
+      await this.files.deleteVersionsByFileIds(deletedFileIds);
+      await this.files.deleteMany(deletedFileIds);
+    }
+    const allFolders = await this.folders.listByUser(userId);
+    const trashedFolders = allFolders.filter((folder) => folder.deletedAt !== null);
+    const depth = (folder) => {
+      let level = 0;
+      let cursor = folder.parentId;
+      const seen = /* @__PURE__ */ new Set();
+      while (cursor !== null && !seen.has(cursor)) {
+        seen.add(cursor);
+        const parent = allFolders.find((candidate) => candidate.id === cursor);
+        if (!parent) break;
+        level += 1;
+        cursor = parent.parentId;
+      }
+      return level;
+    };
+    trashedFolders.sort((a, b) => depth(a) - depth(b));
+    let deletedFolders = 0;
+    for (const folder of trashedFolders) {
+      const stillHasFiles = await this.files.query(
+        userId,
+        { folderId: folder.id, trashed: true },
+        { page: 1, limit: 1 }
+      );
+      if (stillHasFiles.total > 0) continue;
+      await this.folders.deleteMany([folder.id]);
+      deletedFolders += 1;
+    }
+    return { deletedFiles, deletedFolders, failedFiles };
+  }
+  /** Restores a single trashed item (used by the batch restore endpoint). */
+  async verifyTrashedFile(userId, id) {
+    const file = await this.files.findById(id);
+    if (!file || file.userId !== userId || file.deletedAt === null) {
+      throw new NotFoundError("File is not in the Trash", "file");
+    }
+    return file;
+  }
+};
+
+// ../core/src/services/integrity-service.ts
+var IntegrityService = class {
+  constructor(files, engineFor) {
+    this.files = files;
+    this.engineFor = engineFor;
+  }
+  files;
+  engineFor;
+  async check(userId, options = {}) {
+    const startedAt = Date.now();
+    const all = await this.files.listByUser(userId);
+    const active = all.filter((file) => file.deletedAt === null);
+    const targets = options.limit ? active.slice(0, options.limit) : active;
+    const engine = await this.engineFor(userId);
+    const issues = [];
+    let healthy = 0;
+    for (const file of targets) {
+      const issue = await this.inspect(file, options.deep ?? false, engine);
+      if (issue) issues.push(issue);
+      else healthy += 1;
+    }
+    const missing = issues.filter((issue) => issue.kind === "missing").length;
+    const inconsistent = issues.filter(
+      (issue) => issue.kind === "size_mismatch" || issue.kind === "hash_mismatch"
+    ).length;
+    const unreadable = issues.filter((issue) => issue.kind === "unreadable").length;
+    return {
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      filesChecked: targets.length,
+      healthy,
+      missing,
+      inconsistent,
+      unreadable,
+      issues,
+      durationMs: Date.now() - startedAt
+    };
+  }
+  async inspect(file, deep, engine) {
+    const ref = { messageId: String(file.telegramMessageId) };
+    let stat;
+    try {
+      stat = await engine.stat(ref);
+    } catch (error) {
+      return {
+        fileId: file.id,
+        name: file.name,
+        kind: "unreadable",
+        detail: error instanceof Error ? error.message : "Storage lookup failed"
+      };
+    }
+    if (!stat) {
+      return {
+        fileId: file.id,
+        name: file.name,
+        kind: "missing",
+        detail: "No message with this id exists in the storage channel"
+      };
+    }
+    if (stat.size !== file.size) {
+      return {
+        fileId: file.id,
+        name: file.name,
+        kind: "size_mismatch",
+        detail: `metadata=${file.size} storage=${stat.size}`
+      };
+    }
+    if (deep) {
+      try {
+        const data = await engine.download(ref);
+        const ok = await engine.verifyIntegrity(data, file.sha256);
+        if (!ok) {
+          return {
+            fileId: file.id,
+            name: file.name,
+            kind: "hash_mismatch",
+            detail: "Downloaded bytes do not match the stored SHA-256"
+          };
+        }
+      } catch (error) {
+        return {
+          fileId: file.id,
+          name: file.name,
+          kind: "unreadable",
+          detail: error instanceof Error ? error.message : "Download failed"
+        };
+      }
+    }
+    return null;
+  }
+};
+
+// ../core/src/services/recent-service.ts
+var RECENT_ACTIONS = [
+  "upload",
+  "download",
+  "open",
+  "rename",
+  "move",
+  "replace"
+];
+var RecentService = class {
+  constructor(activity, files) {
+    this.activity = activity;
+    this.files = files;
+  }
+  activity;
+  files;
+  async list(userId, page) {
+    const window = Math.min(page.page * page.limit * 3, 500);
+    const events = await this.activity.recentFiles(userId, RECENT_ACTIONS, window);
+    const seen = /* @__PURE__ */ new Set();
+    for (const event of events) {
+      seen.add(event.resourceId);
+    }
+    const fileIds = [...seen];
+    const records = fileIds.length > 0 ? await this.files.listByIds(userId, fileIds) : [];
+    const byId = new Map(records.map((record) => [record.id, record]));
+    const items = [];
+    for (const fileId of fileIds) {
+      const record = byId.get(fileId);
+      if (!record || record.deletedAt !== null) continue;
+      const event = events.find((candidate) => candidate.resourceId === fileId);
+      items.push({
+        file: {
+          id: record.id,
+          name: record.name,
+          size: record.size,
+          mimeType: record.mimeType,
+          sha256: record.sha256,
+          folderId: record.folderId,
+          starred: record.starred,
+          trashed: false,
+          deletedAt: null,
+          versionCount: record.versionCount,
+          currentVersionId: record.currentVersionId,
+          createdAt: record.createdAt.toISOString(),
+          updatedAt: record.updatedAt.toISOString()
+        },
+        lastAction: event.action,
+        lastActionAt: event.createdAt.toISOString()
+      });
+    }
+    const start = (page.page - 1) * page.limit;
+    const pageItems = items.slice(start, start + page.limit);
+    return {
+      items: pageItems,
+      pagination: paginationMeta(page.page, page.limit, items.length)
+    };
   }
 };
 
 // ../telegram/src/client.ts
 import { Api, TelegramClient } from "telegram";
-import { StringSession } from "telegram/sessions";
+import { StringSession } from "telegram/sessions/index.js";
 
 // ../telegram/src/errors.ts
 import { RPCError } from "telegram/errors/index.js";
@@ -636,26 +2104,44 @@ function mapTelegramError(error, fallbackMessage) {
       case "PHONE_NUMBER_BANNED":
         return new ForbiddenError("This phone number is banned from Telegram");
       case "AUTH_KEY_UNREGISTERED":
+      case "AUTH_KEY_DUPLICATED":
       case "SESSION_REVOKED":
+      case "SESSION_EXPIRED":
       case "USER_DEACTIVATED":
-        return new UnauthorizedError("The Telegram session is no longer valid \u2014 please reconnect");
+      case "USER_DEACTIVATED_BAN":
+        return new TelegramAuthRequiredError();
       case "CHANNEL_PRIVATE":
+      case "CHANNEL_INVALID":
       case "CHAT_ID_INVALID":
         return new StorageNotInitializedError();
+      case "MSG_ID_INVALID":
+      case "MESSAGE_ID_INVALID":
+        return new TelegramFileNotFoundError();
+      case "FILE_REFERENCE_EXPIRED":
+      case "FILE_REFERENCE_INVALID":
+        return new TelegramFileNotFoundError(
+          "The Telegram file reference expired \u2014 re-upload the file to refresh it"
+        );
       default:
-        return new StorageProviderError(fallbackMessage, {
+        return new TelegramConnectionError(fallbackMessage, {
           code: error.code,
           telegramError: msg
         });
     }
   }
-  return new StorageProviderError(
-    error instanceof Error ? `${fallbackMessage}: ${error.message}` : fallbackMessage,
+  const detail = error instanceof Error ? error.message : String(error);
+  if (/timeout|ECONNRESET|ENOTFOUND|socket|network|connect/i.test(detail)) {
+    return new TelegramConnectionError(`${fallbackMessage} (network error)`, error);
+  }
+  return new TelegramConnectionError(
+    detail ? `${fallbackMessage}: ${detail}` : fallbackMessage,
     error
   );
 }
 
 // ../telegram/src/client.ts
+var HEALTH_TTL_MS = 3e4;
+var RECONNECT_COOLDOWN_MS = 5e3;
 var TelegramClientManager = class {
   constructor(credentials, sessions) {
     this.credentials = credentials;
@@ -663,52 +2149,208 @@ var TelegramClientManager = class {
   }
   credentials;
   sessions;
-  clients = /* @__PURE__ */ new Map();
+  connections = /* @__PURE__ */ new Map();
+  lastReconnectAt = /* @__PURE__ */ new Map();
+  /** Returns a connected client, (re)connecting when needed. */
   async getForUser(userId) {
-    const cached = this.clients.get(userId);
-    if (cached) {
+    const existing = this.connections.get(userId);
+    if (existing) {
+      if (existing.state === "CONNECTED" && this.isConnected(existing.client)) {
+        return existing.client;
+      }
+      if (existing.pending) return existing.pending;
+      if (existing.state === "AUTH_REQUIRED") {
+        throw new TelegramAuthRequiredError();
+      }
+      return this.reconnect(userId, existing);
+    }
+    return this.connectUser(userId);
+  }
+  /** Connection status for health reporting and the storage dashboard. */
+  statusForUser(userId) {
+    const connection = this.connections.get(userId);
+    if (!connection) {
+      return { state: "DISCONNECTED", lastError: null, lastCheckAt: null, healthy: null };
+    }
+    return {
+      state: connection.state,
+      lastError: connection.lastError,
+      lastCheckAt: connection.lastCheckAt ? new Date(connection.lastCheckAt) : null,
+      healthy: connection.lastCheckOk
+    };
+  }
+  /**
+   * Probes a user's connection. Cheap by default (connection state only);
+   * `deep` performs a real Telegram round-trip to validate the session.
+   */
+  async healthCheck(userId, deep = false) {
+    const connection = this.connections.get(userId);
+    if (!connection) {
       try {
-        return await cached;
-      } catch {
-        this.clients.delete(userId);
+        await this.getForUser(userId);
+      } catch (error) {
+        const state = error instanceof TelegramAuthRequiredError ? "AUTH_REQUIRED" : "ERROR";
+        const current = this.connections.get(userId);
+        if (current) current.state = state;
+        return {
+          healthy: false,
+          latencyMs: null,
+          message: error instanceof Error ? error.message : "Telegram is not connected",
+          targetTitle: null
+        };
       }
     }
-    const session = await this.sessions.get(userId);
-    if (!session) {
-      throw new UnauthorizedError("Telegram account is not connected");
+    const active = this.connections.get(userId);
+    if (!deep && active.lastCheckAt && Date.now() - active.lastCheckAt < HEALTH_TTL_MS) {
+      return {
+        healthy: active.lastCheckOk ?? false,
+        latencyMs: null,
+        message: active.lastError,
+        targetTitle: null
+      };
     }
-    const promise = this.connect(session.stringSession);
-    this.clients.set(userId, promise);
+    const startedAt = Date.now();
     try {
-      return await promise;
+      await active.client.getMe();
+      active.lastCheckAt = Date.now();
+      active.lastCheckOk = true;
+      active.lastError = null;
+      active.state = "CONNECTED";
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startedAt,
+        message: null,
+        targetTitle: null
+      };
     } catch (error) {
-      this.clients.delete(userId);
-      throw mapTelegramError(error, "Could not connect to Telegram");
+      const mapped = mapTelegramError(error, "Telegram health check failed");
+      active.lastCheckAt = Date.now();
+      active.lastCheckOk = false;
+      active.lastError = mapped.message;
+      active.state = mapped instanceof TelegramAuthRequiredError || mapped instanceof UnauthorizedError ? "AUTH_REQUIRED" : "ERROR";
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startedAt,
+        message: mapped.message,
+        targetTitle: null
+      };
     }
   }
-  /** Registers an already-authenticated client (e.g. from the login flow). */
+  /** Registers an already-authenticated client (from the login flow). */
   cacheClient(userId, client) {
-    this.clients.set(userId, Promise.resolve(client));
+    this.connections.set(userId, {
+      client,
+      state: "CONNECTED",
+      pending: null,
+      lastError: null,
+      lastCheckAt: Date.now(),
+      lastCheckOk: true
+    });
+  }
+  /** Drops a user's connection (e.g. after logout) without touching storage. */
+  async disconnectUser(userId) {
+    const connection = this.connections.get(userId);
+    if (!connection) return;
+    this.connections.delete(userId);
+    try {
+      await connection.client.disconnect();
+    } catch {
+    }
   }
   async disconnectAll() {
-    for (const [userId, promise] of this.clients) {
-      this.clients.delete(userId);
+    const ids = [...this.connections.keys()];
+    await Promise.all(ids.map((userId) => this.disconnectUser(userId)));
+  }
+  // ── internals ────────────────────────────────────────────────────────────
+  isConnected(client) {
+    try {
+      return client.connected === true;
+    } catch {
+      return false;
+    }
+  }
+  async connectUser(userId) {
+    const session = await this.sessions.get(userId);
+    if (!session) {
+      throw new TelegramAuthRequiredError("Telegram account is not connected");
+    }
+    const connection = {
+      client: null,
+      state: "CONNECTING",
+      pending: null,
+      lastError: null,
+      lastCheckAt: null,
+      lastCheckOk: null
+    };
+    const attempt = this.establish(session.stringSession).then((client) => {
+      connection.client = client;
+      connection.state = "CONNECTED";
+      connection.pending = null;
+      connection.lastError = null;
+      return client;
+    });
+    connection.pending = attempt;
+    this.connections.set(userId, connection);
+    try {
+      return await attempt;
+    } catch (error) {
+      connection.pending = null;
+      const mapped = mapTelegramError(error, "Could not connect to Telegram");
+      connection.state = mapped instanceof TelegramAuthRequiredError || mapped instanceof UnauthorizedError ? "AUTH_REQUIRED" : "ERROR";
+      connection.lastError = mapped.message;
+      throw mapped;
+    }
+  }
+  async reconnect(userId, connection) {
+    const lastAttempt = this.lastReconnectAt.get(userId) ?? 0;
+    if (Date.now() - lastAttempt < RECONNECT_COOLDOWN_MS && connection.pending) {
+      return connection.pending;
+    }
+    this.lastReconnectAt.set(userId, Date.now());
+    connection.state = "RECONNECTING";
+    const session = await this.sessions.get(userId);
+    if (!session) {
+      connection.state = "AUTH_REQUIRED";
+      throw new TelegramAuthRequiredError("Telegram account is not connected");
+    }
+    const attempt = (async () => {
       try {
-        const client = await promise;
-        await client.disconnect();
+        await connection.client.disconnect().catch(() => void 0);
       } catch {
       }
-    }
+      return this.establish(session.stringSession);
+    })().then((client) => {
+      connection.client = client;
+      connection.state = "CONNECTED";
+      connection.pending = null;
+      connection.lastError = null;
+      return client;
+    }).catch((error) => {
+      connection.pending = null;
+      const mapped = mapTelegramError(error, "Could not reconnect to Telegram");
+      connection.state = mapped instanceof TelegramAuthRequiredError || mapped instanceof UnauthorizedError ? "AUTH_REQUIRED" : "ERROR";
+      connection.lastError = mapped.message;
+      throw mapped;
+    });
+    connection.pending = attempt;
+    return attempt;
   }
-  async connect(sessionString) {
+  async establish(sessionString) {
     const client = new TelegramClient(
       new StringSession(sessionString),
       this.credentials.apiId,
       this.credentials.apiHash,
       { connectionRetries: 3 }
     );
-    await client.connect();
-    return client;
+    try {
+      await client.connect();
+      if (!client.connected) {
+        throw new TelegramConnectionError("Telegram client did not connect");
+      }
+      return client;
+    } catch (error) {
+      throw mapTelegramError(error, "Could not connect to Telegram");
+    }
   }
 };
 function newTelegramClient(credentials) {
@@ -721,13 +2363,15 @@ function extractCreatedChannel(result) {
   for (const chat of chats) {
     if (chat instanceof Api.Channel) return chat;
   }
-  throw new StorageProviderError("Telegram did not return the created storage channel");
+  throw new TelegramConnectionError("Telegram did not return the created storage channel");
 }
 
 // ../telegram/src/provider.ts
+import { Readable as Readable2 } from "stream";
 import { Api as Api2 } from "telegram";
 import bigInt from "big-integer";
-import { CustomFile } from "telegram/client/uploads";
+import { CustomFile } from "telegram/client/uploads.js";
+var MAX_DOCUMENT_BYTES = 2 * 1024 * 1024 * 1024;
 var TelegramStorageProvider = class {
   constructor(client, options) {
     this.client = client;
@@ -735,48 +2379,100 @@ var TelegramStorageProvider = class {
       channelId: bigInt(options.chatId),
       accessHash: bigInt(options.accessHash)
     });
+    this.title = options.title ?? null;
   }
   client;
   name = "telegram";
   peer;
-  async put(input) {
+  title;
+  // ── Upload ───────────────────────────────────────────────────────────────
+  async put(input, control = {}) {
+    const data = await this.materialize(input);
+    if (data.byteLength > MAX_DOCUMENT_BYTES) {
+      throw new UploadFailedError(
+        `Telegram does not accept documents larger than ${MAX_DOCUMENT_BYTES / (1024 * 1024 * 1024)} GB`
+      );
+    }
+    this.throwIfAborted(control.signal);
+    const total = data.byteLength;
+    control.onProgress?.({ transferred: 0, total, percent: 0 });
     try {
-      const file = new CustomFile(input.name, input.data.byteLength, "", input.data);
+      const file = new CustomFile(input.name, total, "", data);
       const message = await this.client.sendFile(this.peer, {
         file,
         forceDocument: true,
-        workers: 1
+        workers: 1,
+        // Surface transport-level progress to the caller. GramJS reports a
+        // 0..1 fraction. `isCanceled` lets us abort an in-flight upload.
+        progressCallback: Object.assign(
+          (fraction) => {
+            const clamped = Math.max(0, Math.min(1, fraction));
+            control.onProgress?.({
+              transferred: Math.round(clamped * total),
+              total,
+              percent: Math.round(clamped * 100)
+            });
+          },
+          {
+            get isCanceled() {
+              return control.signal?.aborted === true;
+            }
+          }
+        )
       });
       if (!(message instanceof Api2.Message)) {
-        throw new StorageProviderError("Telegram returned an unexpected upload response");
+        throw new UploadFailedError("Telegram returned an unexpected upload response");
       }
+      control.onProgress?.({ transferred: total, total, percent: 100 });
       return {
         messageId: message.id.toString(),
         name: input.name,
-        size: input.data.byteLength,
+        size: total,
         mimeType: input.mimeType
       };
     } catch (error) {
+      if (error instanceof OperationCancelledError) throw error;
       throw mapTelegramError(error, "Telegram upload failed");
     }
   }
-  async get(ref) {
+  // ── Download ─────────────────────────────────────────────────────────────
+  async get(ref, control = {}) {
+    const message = await this.requireMessage(ref);
+    this.throwIfAborted(control.signal);
+    const size = this.documentSize(message);
+    control.onProgress?.({ transferred: 0, total: size, percent: 0 });
     let data;
     try {
-      const message = await this.getMessage(ref.messageId);
-      if (!message?.media) {
-        throw new StorageProviderError("The stored file is missing from Telegram");
-      }
-      data = await this.client.downloadMedia(message, {});
+      data = await this.client.downloadMedia(message, {
+        progressCallback: (downloaded, total) => {
+          const transferred = Number(downloaded.toString());
+          const totalBytes = Number(total.toString());
+          control.onProgress?.({
+            transferred,
+            total: totalBytes,
+            percent: totalBytes > 0 ? Math.round(transferred / totalBytes * 100) : null
+          });
+        }
+      });
     } catch (error) {
-      if (error instanceof StorageProviderError) throw error;
       throw mapTelegramError(error, "Telegram download failed");
     }
     if (!data || typeof data === "string") {
-      throw new StorageProviderError("Telegram did not return file content");
+      throw new TelegramFileNotFoundError("Telegram did not return file content");
     }
-    return Buffer.from(data);
+    const buffer = Buffer.from(data);
+    control.onProgress?.({
+      transferred: buffer.byteLength,
+      total: buffer.byteLength,
+      percent: 100
+    });
+    return buffer;
+  }
+  async getStream(ref, control = {}) {
+    const data = await this.get(ref, control);
+    return Readable2.from([data]);
   }
+  // ── Lifecycle ────────────────────────────────────────────────────────────
   async delete(ref) {
     try {
       await this.client.deleteMessages(this.peer, [Number(ref.messageId)], { revoke: true });
@@ -792,12 +2488,7 @@ var TelegramStorageProvider = class {
     }
   }
   async stat(ref) {
-    let message;
-    try {
-      message = await this.getMessage(ref.messageId);
-    } catch (error) {
-      throw mapTelegramError(error, "Telegram lookup failed");
-    }
+    const message = await this.getMessage(ref.messageId);
     if (!message?.media) return null;
     const document = message.document;
     if (!(document instanceof Api2.Document)) return null;
@@ -815,16 +2506,87 @@ var TelegramStorageProvider = class {
       mimeType: document.mimeType
     };
   }
+  // ── Health ───────────────────────────────────────────────────────────────
+  /**
+   * Validates that the client is connected and the storage channel is
+   * reachable (a real Telegram round-trip on the channel peer).
+   */
+  async healthCheck() {
+    const startedAt = Date.now();
+    try {
+      if (!this.client.connected) {
+        return {
+          healthy: false,
+          latencyMs: null,
+          message: "Telegram client is not connected",
+          targetTitle: this.title
+        };
+      }
+      const result = await this.client.invoke(
+        new Api2.channels.GetFullChannel({ channel: this.peer })
+      );
+      const title = result instanceof Api2.messages.ChatFull && result.chats[0] instanceof Api2.Channel ? result.chats[0].title : this.title;
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startedAt,
+        message: null,
+        targetTitle: title ?? null
+      };
+    } catch (error) {
+      const mapped = mapTelegramError(error, "Telegram storage health check failed");
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startedAt,
+        message: mapped.message,
+        targetTitle: this.title
+      };
+    }
+  }
+  // ── internals ────────────────────────────────────────────────────────────
+  throwIfAborted(signal) {
+    if (signal?.aborted) throw new OperationCancelledError();
+    if (!this.client.connected) {
+      throw new TelegramConnectionError("Telegram client is not connected");
+    }
+  }
+  async materialize(input) {
+    if (input.data) return input.data;
+    if (!input.stream) {
+      throw new UploadFailedError("Upload input has neither data nor a stream");
+    }
+    const chunks = [];
+    for await (const chunk of input.stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  documentSize(message) {
+    const document = message.document;
+    if (document instanceof Api2.Document) return Number(document.size.toString());
+    return null;
+  }
+  async requireMessage(ref) {
+    const message = await this.getMessage(ref.messageId);
+    if (!message?.media) {
+      throw new TelegramFileNotFoundError();
+    }
+    return message;
+  }
   async getMessage(id) {
-    const messages = await this.client.getMessages(this.peer, { ids: [Number(id)] });
-    const first = messages[0];
-    return first instanceof Api2.Message ? first : void 0;
+    try {
+      const messages = await this.client.getMessages(this.peer, { ids: [Number(id)] });
+      const first = messages[0];
+      return first instanceof Api2.Message ? first : void 0;
+    } catch (error) {
+      if (error instanceof TelegramAuthRequiredError) throw error;
+      throw mapTelegramError(error, "Telegram lookup failed");
+    }
   }
 };
 
 // ../telegram/src/connection.ts
 import { Api as Api3 } from "telegram";
-import { computeCheck } from "telegram/Password";
+import { computeCheck } from "telegram/Password.js";
 var TELEGRAM_PROVIDER = "telegram";
 var LOGIN_FLOW_TTL_MS = 5 * 60 * 1e3;
 var TelegramConnectionService = class {
@@ -921,7 +2683,7 @@ var TelegramConnectionService = class {
     }
     const accessHash = channel.accessHash?.toString();
     if (!accessHash) {
-      throw new StorageProviderError("Telegram did not provide the channel access hash");
+      throw new TelegramConnectionError("Telegram did not provide the channel access hash");
     }
     return this.repos.storages.create({
       userId,
@@ -987,21 +2749,32 @@ var TelegramConnectionService = class {
   }
 };
 export {
+  ActivityService,
   ERROR_CODES,
   FileService,
   FolderService,
+  IntegrityService,
   OmniCloudClient,
   OmniCloudError,
+  RecentService,
   SearchService,
+  StatsService,
   StorageEngine,
   TELEGRAM_PROVIDER,
   TelegramClientManager,
   TelegramConnectionService,
   TelegramStorageProvider,
+  TrashService,
   fileCategory,
+  isFileCategory,
   mapProviderError,
   mapTelegramError,
   mimeFromFilename,
+  mimeMatchersForType,
+  noopActivityRecorder,
+  paginationMeta,
+  parseSearchQuery,
+  parseSize,
   sanitizeFileName,
   sha256Hex
 };