@lacrous/omnicloud 0.2.1 → 0.2.2

package/dist/index.js

@@ -130,6 +130,65 @@ var OmniCloudClient = class {
     throw lastError;
   }
   /** @internal */
+  /**
+   * Opens a binary response as a stream. Bytes are delivered as they arrive, so
+   * memory does not grow with the file. The stream errors with DOWNLOAD_INCOMPLETE
+   * if the body ends before Content-Length.
+   */
+  async requestStream(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 source = response.body;
+    if (!source) {
+      throw new OmniCloudError(0, "DOWNLOAD_FAILED", "The response has no body to stream");
+    }
+    let loaded = 0;
+    const reader = source.getReader();
+    const stream = new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await reader.read();
+        if (done) {
+          if (total !== null && loaded !== total) {
+            controller.error(
+              new OmniCloudError(
+                0,
+                "DOWNLOAD_INCOMPLETE",
+                `Download ended after ${loaded} of ${total} bytes`
+              )
+            );
+            return;
+          }
+          controller.close();
+          return;
+        }
+        loaded += value.byteLength;
+        onProgress?.({
+          loaded,
+          total,
+          percent: total ? Math.round(loaded / total * 100) : null
+        });
+        controller.enqueue(value);
+      },
+      cancel(reason) {
+        return reader.cancel(reason);
+      }
+    });
+    return { stream, contentType, size: total, sha256 };
+  }
   async requestBinary(path, onProgress) {
     const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
       headers: this.defaultHeaders,
@@ -153,6 +212,28 @@ var OmniCloudClient = class {
     return { data, contentType, size: data.byteLength, sha256, integrityVerified };
   }
 };
+async function toBlob(input) {
+  if (input.path !== void 0) {
+    const { readFile } = await import("fs/promises");
+    return new Blob([new Uint8Array(await readFile(input.path))]);
+  }
+  const data = input.data;
+  if (data === void 0) throw new OmniCloudError(0, "INVALID_REQUEST", "No upload content given");
+  if (typeof Blob !== "undefined" && data instanceof Blob) return data;
+  if (data instanceof Uint8Array) return new Blob([new Uint8Array(data)]);
+  const parts = [];
+  if (typeof data.getReader === "function") {
+    const reader = data.getReader();
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parts.push(value);
+    }
+  } else {
+    for await (const chunk of data) parts.push(chunk);
+  }
+  return new Blob(parts);
+}
 async function readBody(response, total, onProgress) {
   const body = response.body;
   if (!body) {
@@ -176,6 +257,13 @@ async function readBody(response, total, onProgress) {
       });
     }
   }
+  if (total !== null && loaded !== total) {
+    throw new OmniCloudError(
+      0,
+      "DOWNLOAD_INCOMPLETE",
+      `Download ended after ${loaded} of ${total} bytes`
+    );
+  }
   const merged = new Uint8Array(loaded);
   let offset = 0;
   for (const chunk of chunks) {
@@ -225,9 +313,9 @@ var FilesApi = class {
     }
     throw lastError;
   }
-  uploadOnce(input, options) {
+  async uploadOnce(input, options) {
     const form = new FormData();
-    const blob = typeof Blob !== "undefined" && input.data instanceof Blob ? input.data : new Blob([new Uint8Array(input.data)]);
+    const blob = await toBlob(input);
     form.append("file", blob, input.name);
     if (options.folderId) form.append("folderId", options.folderId);
     if (typeof XMLHttpRequest === "function") {
@@ -287,6 +375,45 @@ var FilesApi = class {
   async download(id, onProgress) {
     return this.client.requestBinary(`/api/files/${id}/download`, onProgress);
   }
+  /**
+   * Streams a file's bytes without holding the whole file in memory. Use this for
+   * large files. Read `stream` to the end: a truncated transfer errors instead of
+   * ending quietly.
+   */
+  async downloadStream(id, onProgress) {
+    return this.client.requestStream(`/api/files/${id}/download`, onProgress);
+  }
+  /**
+   * Node only. Streams a file to `targetPath` through a `.part` file that is
+   * renamed into place only after the full length is verified. A truncated or
+   * failed transfer leaves nothing at `targetPath`.
+   */
+  async downloadToFile(id, targetPath, onProgress) {
+    const { createWriteStream: createWriteStream2 } = await import("fs");
+    const { rename, rm: rm2 } = await import("fs/promises");
+    const { Readable: Readable3 } = await import("stream");
+    const { pipeline: pipeline2 } = await import("stream/promises");
+    const download = await this.downloadStream(id, onProgress);
+    const partPath = `${targetPath}.part`;
+    let bytes = 0;
+    try {
+      await pipeline2(
+        Readable3.fromWeb(download.stream),
+        async function* (source) {
+          for await (const chunk of source) {
+            bytes += chunk.byteLength;
+            yield chunk;
+          }
+        },
+        createWriteStream2(partPath)
+      );
+      await rename(partPath, targetPath);
+    } catch (error) {
+      await rm2(partPath, { force: true });
+      throw error;
+    }
+    return { path: targetPath, bytes, sha256: download.sha256 };
+  }
   /** URL suitable for direct download (anchor href). */
   downloadUrl(id) {
     return `${this.client.baseUrl}/api/files/${id}/download`;
@@ -841,12 +968,18 @@ var DomainError = class extends Error {
   code;
   status;
   details;
-  constructor(code, status, message, details) {
+  /** Whether repeating the same operation may succeed. Defaults to false. */
+  retryable = false;
+  /** Server-requested delay before a retry, in seconds, when the provider gave one. */
+  retryAfterSeconds;
+  constructor(code, status, message, details, retry) {
     super(message);
     this.name = new.target.name;
     this.code = code;
     this.status = status;
     this.details = details;
+    this.retryable = retry?.retryable ?? false;
+    this.retryAfterSeconds = retry?.retryAfterSeconds;
   }
 };
 var ValidationError = class extends DomainError {
@@ -879,8 +1012,11 @@ var ConflictError = class extends DomainError {
   }
 };
 var RateLimitedError = class extends DomainError {
-  constructor(message = "Too many requests, please retry later") {
-    super(ERROR_CODES.RATE_LIMITED, 429, message);
+  constructor(message = "Too many requests, please retry later", options = {}) {
+    super(ERROR_CODES.RATE_LIMITED, 429, message, void 0, {
+      retryable: true,
+      retryAfterSeconds: options.retryAfterSeconds
+    });
   }
 };
 var StorageNotInitializedError = class extends DomainError {
@@ -895,7 +1031,7 @@ var TelegramAuthRequiredError = class extends DomainError {
 };
 var TelegramConnectionError = class extends DomainError {
   constructor(message = "Could not reach Telegram", details) {
-    super(ERROR_CODES.TELEGRAM_CONNECTION_FAILED, 502, message, details);
+    super(ERROR_CODES.TELEGRAM_CONNECTION_FAILED, 502, message, details, { retryable: true });
   }
 };
 var TelegramFileNotFoundError = class extends DomainError {
@@ -908,6 +1044,11 @@ var UploadFailedError = class extends DomainError {
     super(ERROR_CODES.UPLOAD_FAILED, 502, message, details);
   }
 };
+var IntegrityCheckError = class extends DomainError {
+  constructor(message = "Integrity check failed", details) {
+    super(ERROR_CODES.INTEGRITY_CHECK_FAILED, 502, message, details);
+  }
+};
 var OperationCancelledError = class extends DomainError {
   constructor(message = "Operation cancelled") {
     super(ERROR_CODES.INVALID_REQUEST, 499, message);
@@ -920,7 +1061,22 @@ function mapProviderError(message, error) {
 }
 
 // ../core/src/storage/engine.ts
-import { Readable } from "stream";
+import { createHash as createHash2 } from "crypto";
+import { Readable, Transform } from "stream";
+
+// ../core/src/storage/retry.ts
+function isRetryableError(error) {
+  if (error instanceof OperationCancelledError) return false;
+  if (error instanceof DomainError) return error.retryable;
+  return false;
+}
+function retryDelayMs(error, attempt, baseDelayMs, random = Math.random) {
+  if (error instanceof DomainError && error.retryAfterSeconds !== void 0) {
+    return error.retryAfterSeconds * 1e3;
+  }
+  const ceiling = baseDelayMs * 2 ** (attempt - 1);
+  return Math.floor(random() * ceiling);
+}
 
 // ../core/src/utils/hash.ts
 import { createHash } from "crypto";
@@ -930,15 +1086,6 @@ 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) {
@@ -974,16 +1121,30 @@ var StorageEngine = class {
    * 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 });
+    if (input.data) {
+      const sha2562 = sha256Hex(input.data);
+      const size2 = input.data.byteLength;
+      control.onProgress?.({ transferred: 0, total: size2, percent: 0 });
+      const stored2 = await this.withRetry(
+        () => this.provider.put(input, control),
+        control,
+        (error) => new UploadFailedError("Upload failed", error)
+      );
+      control.onProgress?.({ transferred: size2, total: size2, percent: 100 });
+      return { stored: stored2, sha256: sha2562, size: size2 };
+    }
+    const { path, size, sha256 } = input;
+    if (!path || size === void 0 || !sha256) {
+      throw new UploadFailedError("Upload input has neither data nor a complete spooled file");
+    }
+    control.onProgress?.({ transferred: 0, total: size, percent: 0 });
     const stored = await this.withRetry(
-      () => this.provider.put({ ...input, data }, control),
+      () => this.provider.put(input, control),
       control,
       (error) => new UploadFailedError("Upload failed", error)
     );
-    control.onProgress?.({ transferred: data.byteLength, total: data.byteLength, percent: 100 });
-    return { stored, sha256, size: data.byteLength };
+    control.onProgress?.({ transferred: size, total: size, percent: 100 });
+    return { stored, sha256, size };
   }
   async download(ref, control = {}) {
     return this.withRetry(
@@ -992,14 +1153,41 @@ var StorageEngine = class {
       (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(
+  /**
+   * Streams the object and verifies its SHA-256 against `expectedSha256`.
+   *
+   * The last chunk is held back until the digest of everything before it has
+   * been checked, so a corrupt object errors the stream before its final bytes
+   * are released. A consumer therefore never sees a complete-looking body that
+   * fails the checksum. Memory stays bounded to about two provider chunks.
+   */
+  async downloadStream(ref, expectedSha256, control = {}) {
+    const source = await this.withRetry(
       () => this.provider.getStream(ref, control),
       control,
       (error) => mapProviderError("Download failed", error)
     );
-    return { stream, hash: () => null };
+    const hash = createHash2("sha256");
+    let held = null;
+    const gate = new Transform({
+      transform(chunk, _encoding, callback) {
+        hash.update(chunk);
+        if (held) this.push(held);
+        held = chunk;
+        callback();
+      },
+      flush(callback) {
+        if (hash.digest("hex") !== expectedSha256) {
+          callback(new IntegrityCheckError("Downloaded content does not match its checksum"));
+          return;
+        }
+        if (held) this.push(held);
+        callback();
+      }
+    });
+    source.once("error", (error) => gate.destroy(error));
+    source.pipe(gate);
+    return gate;
   }
   async remove(ref) {
     await this.withRetry(
@@ -1015,6 +1203,14 @@ var StorageEngine = class {
       throw mapProviderError("Storage lookup failed", error);
     }
   }
+  /** Read-only listing of stored objects, for reconciliation. Never modifies anything. */
+  async list(limit) {
+    try {
+      return await this.provider.listObjects(limit);
+    } catch (error) {
+      throw mapProviderError("Storage listing failed", error);
+    }
+  }
   async stat(ref) {
     try {
       return await this.provider.stat(ref);
@@ -1038,18 +1234,6 @@ var StorageEngine = class {
     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;
@@ -1059,8 +1243,8 @@ var StorageEngine = class {
         return await operation();
       } catch (error) {
         lastError = error;
-        if (attempt >= attempts || !isRetryable(error)) break;
-        await delay(baseDelayMs * 2 ** (attempt - 1), control.signal);
+        if (attempt >= attempts || !isRetryableError(error)) break;
+        await delay(retryDelayMs(error, attempt, baseDelayMs), control.signal);
       }
     }
     throw wrapError(lastError);
@@ -1107,6 +1291,51 @@ async function resolveItemQuery(folders, userId, input) {
   return query;
 }
 
+// ../core/src/services/auth-session-service.ts
+import { createHash as createHash3, randomBytes } from "crypto";
+
+// ../core/src/services/upload-operation.ts
+function isValidOperationId(id) {
+  return /^[A-Za-z0-9_-]{8,64}$/.test(id);
+}
+var OperationAlreadyExistsError = class extends Error {
+  constructor() {
+    super("An upload with this operation id already exists");
+    this.name = "OperationAlreadyExistsError";
+  }
+};
+
+// ../core/src/utils/operation-log.ts
+async function timedOperation(sink, base, run, now = Date.now) {
+  const started = now();
+  const emit = (status, errorCode) => {
+    if (!sink) return;
+    const record = {
+      operation: base.operation,
+      userId: base.userId,
+      resourceId: base.resourceId ?? null,
+      sizeBytes: base.sizeBytes ?? null,
+      durationMs: now() - started,
+      status,
+      errorCode
+    };
+    try {
+      if (status === "ok") sink.info({ ...record }, `${base.operation}.completed`);
+      else sink.warn({ ...record }, `${base.operation}.failed`);
+    } catch {
+    }
+  };
+  try {
+    const result = await run();
+    emit("ok", null);
+    return result;
+  } catch (error) {
+    const code = error.code ?? "INTERNAL_ERROR";
+    emit("error", code);
+    throw error;
+  }
+}
+
 // ../core/src/services/activity-service.ts
 var ActivityService = class {
   constructor(activity, retentionDays = 90) {
@@ -1170,18 +1399,120 @@ function sanitizeFileName(name) {
 
 // ../core/src/services/file-service.ts
 var FileService = class {
-  constructor(files, folders, engineFor, activity = noopActivityRecorder) {
+  constructor(files, folders, engineFor, activity = noopActivityRecorder, operations = null, log = null) {
     this.files = files;
     this.folders = folders;
     this.engineFor = engineFor;
     this.activity = activity;
+    this.operations = operations;
+    this.log = log;
   }
   files;
   folders;
   engineFor;
   activity;
+  operations;
+  log;
   // ── Upload ───────────────────────────────────────────────────────────────
   async upload(userId, input) {
+    return timedOperation(
+      this.log,
+      {
+        operation: "upload",
+        userId,
+        resourceId: input.replaceFileId ?? null,
+        sizeBytes: input.spooled?.size ?? input.data?.byteLength ?? null
+      },
+      () => input.operationId && this.operations ? this.uploadOnce(userId, input, input.operationId, this.operations) : this.performUpload(userId, input)
+    );
+  }
+  /**
+   * Idempotent upload keyed by a client-supplied operation id. A retry never
+   * writes a second Telegram object: a completed operation returns its file, and
+   * an operation whose object was already stored is committed without uploading.
+   */
+  async uploadOnce(userId, input, operationId, operations) {
+    if (!isValidOperationId(operationId)) {
+      throw new ValidationError("Invalid upload operation id");
+    }
+    let op = await operations.findByOperationId(userId, operationId);
+    if (op?.status === "COMPLETED" && op.fileId) {
+      return this.get(userId, op.fileId);
+    }
+    if (op?.status === "UPLOADING" && op.telegramMessageId !== null) {
+      return this.commitStoredObject(userId, input, operations, op);
+    }
+    if (!op) {
+      try {
+        op = await operations.create({ userId, operationId });
+      } catch (error) {
+        if (!(error instanceof OperationAlreadyExistsError)) throw error;
+        const outcome = await this.followWinner(userId, input, operationId, operations);
+        if (outcome) return outcome;
+        throw new ConflictError("A concurrent upload with this operation id is still in progress");
+      }
+    }
+    const claimed = await operations.claim(op.id, "PENDING", "UPLOADING") || await operations.claim(op.id, "FAILED", "UPLOADING");
+    if (!claimed) {
+      const outcome = await this.followWinner(userId, input, operationId, operations);
+      if (outcome) return outcome;
+      throw new ConflictError("A concurrent upload with this operation id is still in progress");
+    }
+    try {
+      const record = await this.performUpload(userId, input, {
+        onStored: async (stored) => {
+          await operations.update(op.id, { telegramMessageId: Number(stored.messageId) });
+        }
+      });
+      await operations.update(op.id, { status: "COMPLETED", fileId: record.id });
+      return record;
+    } catch (error) {
+      await operations.update(op.id, {
+        status: "FAILED",
+        error: error instanceof Error ? error.message.slice(0, 200) : "upload failed"
+      });
+      throw error;
+    }
+  }
+  /**
+   * Follows an operation another request is driving, for a bounded time. Returns
+   * the finished file if the winner completes, or the stored object's commit if
+   * it has stored one. Returns null when the winner is still in progress after the
+   * budget, so the caller can report a conflict instead of waiting forever.
+   */
+  async followWinner(userId, input, operationId, operations) {
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+      const current = await operations.findByOperationId(userId, operationId);
+      if (current?.status === "COMPLETED" && current.fileId) {
+        return this.get(userId, current.fileId);
+      }
+      if (current?.status === "FAILED") {
+        return null;
+      }
+      if (current?.status === "UPLOADING" && current.telegramMessageId !== null) {
+        return this.commitStoredObject(userId, input, operations, current);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    return null;
+  }
+  /** Commits metadata for an object that is already in Telegram. */
+  async commitStoredObject(userId, input, operations, op) {
+    const name = sanitizeFileName(input.name);
+    const mimeType = mimeFromFilename(name);
+    const size = op.size ?? input.spooled?.size ?? input.data?.byteLength ?? 0;
+    const sha256 = op.sha256 ?? input.spooled?.sha256 ?? sha256Hex(input.data ?? Buffer.alloc(0));
+    const record = await this.commitRecord(userId, input, {
+      name,
+      mimeType,
+      size,
+      sha256,
+      telegramMessageId: op.telegramMessageId
+    });
+    await operations.update(op.id, { status: "COMPLETED", fileId: record.id });
+    return record;
+  }
+  async performUpload(userId, input, hooks = {}) {
     const name = sanitizeFileName(input.name);
     if (!name) throw new ValidationError("Invalid file name");
     let folderId = input.folderId;
@@ -1197,11 +1528,36 @@ var FileService = class {
       onProgress: input.onProgress,
       signal: input.signal
     };
+    if (!input.data && !input.spooled) {
+      throw new ValidationError("An upload needs content");
+    }
     const { stored, sha256, size } = await engine.upload(
-      { name, mimeType, data: input.data },
+      input.spooled ? {
+        name,
+        mimeType,
+        path: input.spooled.path,
+        size: input.spooled.size,
+        sha256: input.spooled.sha256
+      } : { name, mimeType, data: input.data },
       control
     );
-    const telegramMessageId = Number(stored.messageId);
+    await hooks.onStored?.(stored);
+    try {
+      return await this.commitRecord(userId, input, {
+        name,
+        mimeType,
+        size,
+        sha256,
+        telegramMessageId: Number(stored.messageId)
+      });
+    } catch (error) {
+      await engine.remove({ messageId: String(stored.messageId) }).catch(() => void 0);
+      throw error;
+    }
+  }
+  /** Persists the file (or the new version of a file) for an object already stored. */
+  async commitRecord(userId, input, next) {
+    const { name, mimeType, size, sha256, telegramMessageId } = next;
     if (input.replaceFileId) {
       return this.replaceVersion(userId, input.replaceFileId, {
         name,
@@ -1211,6 +1567,10 @@ var FileService = class {
         telegramMessageId
       });
     }
+    const folderId = input.folderId;
+    if (folderId !== null) {
+      await this.assertFolder(userId, folderId);
+    }
     const record = await this.files.create({
       userId,
       folderId,
@@ -1384,16 +1744,20 @@ var FileService = class {
    * retry, rather than silently orphaning the storage object.
    */
   async deletePermanently(userId, id) {
+    return timedOperation(
+      this.log,
+      { operation: "delete", userId, resourceId: id },
+      () => this.performPermanentDelete(userId, id)
+    );
+  }
+  async performPermanentDelete(userId, id) {
     const record = await this.get(userId, id);
     const engine = await this.engineFor(userId);
-    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 {
-      }
+    const messageIds = /* @__PURE__ */ new Set([String(record.telegramMessageId)]);
+    for (const version of versions) messageIds.add(String(version.telegramMessageId));
+    for (const messageId of messageIds) {
+      await engine.remove({ messageId });
     }
     await this.files.deleteVersionsByFileIds([id]);
     await this.files.deleteMany([id]);
@@ -1428,6 +1792,36 @@ var FileService = class {
     });
     return { record, data, integrityVerified };
   }
+  /**
+   * Streaming download for large files. The caller must consume `stream` to
+   * the end and then await `verified` to learn whether the bytes match the
+   * stored checksum. The download activity is recorded when the stream opens.
+   */
+  async downloadStreamed(userId, id, control = {}) {
+    return timedOperation(
+      this.log,
+      { operation: "download", userId, resourceId: id },
+      () => this.performStreamedDownload(userId, id, control)
+    );
+  }
+  async performStreamedDownload(userId, id, control) {
+    const record = await this.getActive(userId, id);
+    const engine = await this.engineFor(userId);
+    const stream = await engine.downloadStream(
+      { messageId: String(record.telegramMessageId) },
+      record.sha256,
+      control
+    );
+    await this.activity.record({
+      userId,
+      action: "download",
+      resourceType: "file",
+      resourceId: id,
+      resourceName: record.name,
+      metadata: { size: record.size, streamed: true }
+    });
+    return { record, stream };
+  }
   /** Records an "open" event (the UI opening the details panel, say). */
   async touch(userId, id, action = "open") {
     const record = await this.get(userId, id);
@@ -1479,7 +1873,13 @@ var FileService = class {
         errors.push({ id, message: error instanceof Error ? error.message : "Operation failed" });
       }
     }
-    return { requested: ids.length, succeeded, failed: errors.length, errors };
+    return {
+      ...options.operationId ? { operationId: options.operationId } : {},
+      requested: ids.length,
+      succeeded,
+      failed: errors.length,
+      errors
+    };
   }
   // ── internals ────────────────────────────────────────────────────────────
   async assertFolder(userId, folderId) {
@@ -1573,7 +1973,7 @@ var FolderService = class {
         cursor = parent.parentId;
       }
     }
-    const updated = await this.folders.update(id, { parentId: newParentId });
+    const updated = await this.folders.moveSafely(id, newParentId);
     await this.activity.record({
       userId,
       action: "move",
@@ -1634,7 +2034,7 @@ var FolderService = class {
     let parentId = record.parentId;
     if (parentId !== null) {
       const parent = await this.folders.findById(parentId);
-      if (!parent || parent.deletedAt) parentId = null;
+      if (!parent || parent.userId !== userId || parent.deletedAt) parentId = null;
     }
     const subtree = await this.collectSubtree(userId, id, { includeTrashed: true });
     const batchId = record.trashBatchId;
@@ -1931,10 +2331,28 @@ var IntegrityService = class {
     const engine = await this.engineFor(userId);
     const issues = [];
     let healthy = 0;
+    const versionsByFile = await this.files.listVersionsForFiles(targets.map((file) => file.id));
     for (const file of targets) {
       const issue = await this.inspect(file, options.deep ?? false, engine);
       if (issue) issues.push(issue);
       else healthy += 1;
+      for (const version of versionsByFile.get(file.id) ?? []) {
+        if (version.telegramMessageId === file.telegramMessageId) continue;
+        const versionIssue = await this.inspectObject(
+          {
+            id: file.id,
+            name: file.name,
+            telegramMessageId: version.telegramMessageId,
+            size: version.size,
+            sha256: version.sha256
+          },
+          options.deep ?? false,
+          engine,
+          version.id
+        );
+        if (versionIssue) issues.push(versionIssue);
+        else healthy += 1;
+      }
     }
     const missing = issues.filter((issue) => issue.kind === "missing").length;
     const inconsistent = issues.filter(
@@ -1953,53 +2371,69 @@ var IntegrityService = class {
     };
   }
   async inspect(file, deep, engine) {
-    const ref = { messageId: String(file.telegramMessageId) };
+    return this.inspectObject(
+      {
+        id: file.id,
+        name: file.name,
+        telegramMessageId: file.telegramMessageId,
+        size: file.size,
+        sha256: file.sha256
+      },
+      deep,
+      engine,
+      void 0
+    );
+  }
+  async inspectObject(target, deep, engine, versionId) {
+    const ref = { messageId: String(target.telegramMessageId) };
+    const withVersion = (issue) => versionId ? { ...issue, versionId } : issue;
     let stat;
     try {
       stat = await engine.stat(ref);
     } catch (error) {
-      return {
-        fileId: file.id,
-        name: file.name,
+      return withVersion({
+        fileId: target.id,
+        name: target.name,
         kind: "unreadable",
         detail: error instanceof Error ? error.message : "Storage lookup failed"
-      };
+      });
     }
     if (!stat) {
-      return {
-        fileId: file.id,
-        name: file.name,
+      return withVersion({
+        fileId: target.id,
+        name: target.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,
+    if (stat.size !== target.size) {
+      return withVersion({
+        fileId: target.id,
+        name: target.name,
         kind: "size_mismatch",
-        detail: `metadata=${file.size} storage=${stat.size}`
-      };
+        detail: `metadata=${target.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,
+        const stream = await engine.downloadStream(ref, target.sha256);
+        for await (const _chunk of stream) {
+        }
+      } catch (error) {
+        if (error instanceof IntegrityCheckError) {
+          return withVersion({
+            fileId: target.id,
+            name: target.name,
             kind: "hash_mismatch",
             detail: "Downloaded bytes do not match the stored SHA-256"
-          };
+          });
         }
-      } catch (error) {
-        return {
-          fileId: file.id,
-          name: file.name,
+        return withVersion({
+          fileId: target.id,
+          name: target.name,
           kind: "unreadable",
           detail: error instanceof Error ? error.message : "Download failed"
-        };
+        });
       }
     }
     return null;
@@ -2066,6 +2500,18 @@ var RecentService = class {
   }
 };
 
+// ../core/src/utils/spool.ts
+import { createHash as createHash4 } from "crypto";
+import { createWriteStream } from "fs";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { Transform as Transform2 } from "stream";
+import { pipeline } from "stream/promises";
+
+// ../core/src/utils/secret-box.ts
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2, scryptSync } from "crypto";
+
 // ../telegram/src/client.ts
 import { Api, TelegramClient } from "telegram";
 import { StringSession } from "telegram/sessions/index.js";
@@ -2084,7 +2530,9 @@ function mapTelegramError(error, fallbackMessage) {
     const msg = error.errorMessage ?? "";
     if (msg.startsWith("FLOOD_WAIT_")) {
       const seconds = Number(msg.slice("FLOOD_WAIT_".length)) || 60;
-      return new RateLimitedError(`Telegram rate limit reached \u2014 retry in ${seconds} seconds`);
+      return new RateLimitedError(`Telegram rate limit reached \u2014 retry in ${seconds} seconds`, {
+        retryAfterSeconds: seconds
+      });
     }
     switch (msg) {
       case "PHONE_NUMBER_INVALID":
@@ -2372,6 +2820,7 @@ import { Api as Api2 } from "telegram";
 import bigInt from "big-integer";
 import { CustomFile } from "telegram/client/uploads.js";
 var MAX_DOCUMENT_BYTES = 2 * 1024 * 1024 * 1024;
+var DOWNLOAD_CHUNK_BYTES = 512 * 1024;
 var TelegramStorageProvider = class {
   constructor(client, options) {
     this.client = client;
@@ -2387,17 +2836,19 @@ var TelegramStorageProvider = class {
   title;
   // ── Upload ───────────────────────────────────────────────────────────────
   async put(input, control = {}) {
-    const data = await this.materialize(input);
-    if (data.byteLength > MAX_DOCUMENT_BYTES) {
+    const total = input.data ? input.data.byteLength : input.size;
+    if (total === void 0 || !input.data && !input.path) {
+      throw new UploadFailedError("Upload input has neither data nor a spooled file");
+    }
+    if (total > 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, total, "", data);
+      const file = input.data ? new CustomFile(input.name, total, "", input.data) : new CustomFile(input.name, total, input.path);
       const message = await this.client.sendFile(this.peer, {
         file,
         forceDocument: true,
@@ -2468,9 +2919,47 @@ var TelegramStorageProvider = class {
     });
     return buffer;
   }
+  /**
+   * Streams the object in Telegram-sized chunks, so memory use stays bounded
+   * by one chunk regardless of file size. The first request happens here so
+   * that a missing message fails before the caller starts consuming bytes.
+   */
   async getStream(ref, control = {}) {
-    const data = await this.get(ref, control);
-    return Readable2.from([data]);
+    const message = await this.requireMessage(ref);
+    this.throwIfAborted(control.signal);
+    const size = this.documentSize(message);
+    const media = message.media;
+    if (size === null || !media) {
+      throw new TelegramFileNotFoundError("Telegram did not return file content");
+    }
+    const iterator = this.client.iterDownload({
+      file: media,
+      fileSize: bigInt(size),
+      requestSize: DOWNLOAD_CHUNK_BYTES
+    });
+    let transferred = 0;
+    control.onProgress?.({ transferred: 0, total: size, percent: 0 });
+    const signal = control.signal;
+    return Readable2.from(
+      (async function* () {
+        try {
+          for await (const chunk of iterator) {
+            if (signal?.aborted) throw new OperationCancelledError();
+            const buffer = Buffer.from(chunk);
+            transferred += buffer.byteLength;
+            control.onProgress?.({
+              transferred,
+              total: size,
+              percent: size > 0 ? Math.round(transferred / size * 100) : null
+            });
+            yield buffer;
+          }
+        } catch (error) {
+          if (error instanceof OperationCancelledError) throw error;
+          throw mapTelegramError(error, "Telegram download failed");
+        }
+      })()
+    );
   }
   // ── Lifecycle ────────────────────────────────────────────────────────────
   async delete(ref) {
@@ -2487,6 +2976,38 @@ var TelegramStorageProvider = class {
       throw mapTelegramError(error, "Telegram lookup failed");
     }
   }
+  /**
+   * Read-only listing of stored documents in the channel, newest first, up to
+   * `limit`. Only messages that carry a document are returned; text messages and
+   * service messages are skipped. Nothing is modified.
+   */
+  async listObjects(limit) {
+    const objects = [];
+    try {
+      for await (const message of this.client.iterMessages(this.peer, { limit: limit * 2 })) {
+        if (objects.length >= limit) break;
+        if (!(message instanceof Api2.Message)) continue;
+        const document = message.document;
+        if (!(document instanceof Api2.Document)) continue;
+        let fileName;
+        for (const attr of document.attributes) {
+          if (attr instanceof Api2.DocumentAttributeFilename) {
+            fileName = attr.fileName;
+            break;
+          }
+        }
+        objects.push({
+          messageId: message.id.toString(),
+          name: fileName ?? "file",
+          size: Number(document.size.toString()),
+          mimeType: document.mimeType
+        });
+      }
+    } catch (error) {
+      throw mapTelegramError(error, "Telegram listing failed");
+    }
+    return objects;
+  }
   async stat(ref) {
     const message = await this.getMessage(ref.messageId);
     if (!message?.media) return null;
@@ -2549,17 +3070,6 @@ var TelegramStorageProvider = class {
       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());