@lacrous/omnicloud 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -1,8 +1,80 @@
-import { ListQuery } from './query';
-export { ItemStatus, ListQuery, SortField, SortOrder } from './query';
-export { ActivityEventRecord, ActivityRecorder, ActivityService, DomainError, EngineResolver, EngineRetryPolicy, EngineUploadResult, FileDownload, FileRecord, FileService, FileTypeBucket, FileVersionRecord, FolderMutationResult, FolderRecord, FolderService, IntegrityCheckOptions, IntegrityService, ItemQuery, PageRequest, Paged, RecentService, Repos, SearchService, StatsService, StorageEngine, StorageHealth, StorageProvider, StorageRecord, StorageStats, StorageUploadInput, StoredObject, StoredRef, TransferControl, TransferProgress, TrashService, UserRecord, mapProviderError, noopActivityRecorder, sanitizeFileName, sha256Hex } from './errors';
-export { ConnectionStatus, TELEGRAM_PROVIDER, TelegramClientManager, TelegramConnectionService, TelegramCredentials, TelegramStorageOptions, TelegramStorageProvider, mapTelegramError } from './client';
-export { FileCategory, fileCategory, isFileCategory, mimeFromFilename, mimeMatchersForType, paginationMeta, parseSearchQuery, parseSize } from './mime';
+import { Readable } from 'node:stream';
+import { TelegramClient } from 'telegram';
+
+/**
+ * Search query parsing, pagination and sorting primitives.
+ *
+ * Self-contained (no runtime imports from the package root) so the API, web
+ * app and SDK can all share one query language without import cycles.
+ *
+ * Query language (v0.2):
+ *   report                                  → name contains "report"
+ *   name:report                             → same, explicit
+ *   type:pdf  type:image  type:application/zip
+ *   ext:zip                                 → file extension (no dot)
+ *   size:>100MB  size:<1KB  size:5mb
+ *   folder:Projects                         → folder-name filter
+ *   starred:true  trashed:true
+ *   after:2026-01-01  before:2026-06-01
+ */
+declare const SORT_FIELDS: readonly ["name", "size", "createdAt", "updatedAt", "type"];
+type SortField = (typeof SORT_FIELDS)[number];
+declare const SORT_ORDERS: readonly ["asc", "desc"];
+type SortOrder = (typeof SORT_ORDERS)[number];
+declare const ITEM_STATUSES: readonly ["active", "trashed", "all"];
+type ItemStatus = (typeof ITEM_STATUSES)[number];
+/** Query parameters accepted by the file/folder listing endpoints. */
+interface ListQuery {
+    folderId?: string | null;
+    page?: number;
+    limit?: number;
+    sort?: SortField;
+    order?: SortOrder;
+    /** MIME type or coarse category (image, video, pdf, document, …). */
+    type?: string;
+    /** File extension without the dot. */
+    ext?: string;
+    starred?: boolean;
+    status?: ItemStatus;
+    /** Name substring filter. */
+    q?: string;
+    /** Folder-name filter (search parser); resolved to ids by the caller. */
+    folderName?: string;
+    minSize?: number;
+    maxSize?: number;
+    /** Inclusive date bounds (ISO strings). */
+    from?: string;
+    to?: string;
+}
+/** Parses "100MB", "1.5gb", "512" into bytes. Returns null when unparseable. */
+declare function parseSize(value: string): number | null;
+/** Parses a raw user query string into structured filters. */
+declare function parseSearchQuery(input: string, base?: ListQuery): {
+    query: ListQuery;
+    freeText: string;
+};
+/** Builds the pagination envelope for a result page. */
+declare function paginationMeta(page: number, limit: number, total: number): {
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+};
+
+/** Derives a MIME type from the filename extension. Never trusts client input. */
+declare function mimeFromFilename(filename: string): string;
+type FileCategory = "image" | "video" | "audio" | "pdf" | "archive" | "document" | "text" | "other";
+/** Coarse category used for icon selection in the UI. */
+declare function fileCategory(mimeType: string): FileCategory;
+declare function isFileCategory(value: string): value is FileCategory;
+/**
+ * Expands a `type:` filter into a set of MIME matchers.
+ *
+ * Accepts either a coarse category ("image", "pdf") or an exact MIME type
+ * ("application/pdf"); the repository layer turns these into prefix/equality
+ * filters. Returns null when the value matches nothing usable.
+ */
+declare function mimeMatchersForType(value: string): readonly string[] | null;
 
 /**
  * Data transfer objects, constants and error codes shared between the API,
@@ -48,7 +120,7 @@ type TelegramVerifyResponse = {
 } | {
     status: "password_required";
 };
-interface FileDTO {
+interface FileDTO$1 {
     id: string;
     name: string;
     size: number;
@@ -63,7 +135,7 @@ interface FileDTO {
     createdAt: string;
     updatedAt: string;
 }
-interface FolderDTO {
+interface FolderDTO$1 {
     id: string;
     name: string;
     parentId: string | null;
@@ -84,10 +156,10 @@ interface FileVersionDTO {
     isCurrent: boolean;
     createdAt: string;
 }
-interface SearchResultDTO {
-    files: FileDTO[];
-    folders: FolderDTO[];
-    pagination: PaginationDTO;
+interface SearchResultDTO$1 {
+    files: FileDTO$1[];
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
 }
 /** Result of a recursive folder deletion / trash operation. */
 interface FolderMutationResultDTO {
@@ -100,42 +172,42 @@ interface EmptyTrashResultDTO {
     failedFiles: number;
 }
 
-interface PaginationDTO {
+interface PaginationDTO$1 {
     page: number;
     limit: number;
     total: number;
     hasMore: boolean;
 }
 interface FilesPageDTO {
-    files: FileDTO[];
-    pagination: PaginationDTO;
+    files: FileDTO$1[];
+    pagination: PaginationDTO$1;
 }
 interface FoldersPageDTO {
-    folders: FolderDTO[];
-    pagination: PaginationDTO;
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
 }
 interface TrashPageDTO {
-    files: FileDTO[];
-    folders: FolderDTO[];
-    pagination: PaginationDTO;
+    files: FileDTO$1[];
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
 }
-interface RecentItemDTO {
-    file: FileDTO;
-    lastAction: ActivityAction;
+interface RecentItemDTO$1 {
+    file: FileDTO$1;
+    lastAction: ActivityAction$1;
     lastActionAt: string;
 }
-interface RecentPageDTO {
-    items: RecentItemDTO[];
-    pagination: PaginationDTO;
+interface RecentPageDTO$1 {
+    items: RecentItemDTO$1[];
+    pagination: PaginationDTO$1;
 }
-declare const ACTIVITY_ACTIONS: readonly ["upload", "download", "open", "rename", "move", "star", "unstar", "trash", "restore", "delete", "create_folder", "replace"];
-type ActivityAction = (typeof ACTIVITY_ACTIONS)[number];
-declare const RESOURCE_TYPES: readonly ["file", "folder", "storage"];
-type ResourceType = (typeof RESOURCE_TYPES)[number];
+declare const ACTIVITY_ACTIONS$1: readonly ["upload", "download", "open", "rename", "move", "star", "unstar", "trash", "restore", "delete", "create_folder", "replace"];
+type ActivityAction$1 = (typeof ACTIVITY_ACTIONS$1)[number];
+declare const RESOURCE_TYPES$1: readonly ["file", "folder", "storage"];
+type ResourceType$1 = (typeof RESOURCE_TYPES$1)[number];
 interface ActivityEventDTO {
     id: string;
-    action: ActivityAction;
-    resourceType: ResourceType;
+    action: ActivityAction$1;
+    resourceType: ResourceType$1;
     resourceId: string;
     resourceName: string | null;
     metadata: Record<string, unknown> | null;
@@ -143,7 +215,7 @@ interface ActivityEventDTO {
 }
 interface ActivityPageDTO {
     events: ActivityEventDTO[];
-    pagination: PaginationDTO;
+    pagination: PaginationDTO$1;
 }
 interface StorageTypeBreakdownDTO {
     category: string;
@@ -158,7 +230,7 @@ interface StorageStatsDTO {
     trashFileCount: number;
     starredCount: number;
     byType: StorageTypeBreakdownDTO[];
-    largestFiles: FileDTO[];
+    largestFiles: FileDTO$1[];
     quotaBytes: number | null;
 }
 interface HealthDTO {
@@ -168,20 +240,22 @@ interface HealthDTO {
     uptimeSeconds: number;
     version: string;
 }
-interface IntegrityIssueDTO {
+interface IntegrityIssueDTO$1 {
     fileId: string;
+    /** Set when the issue is with a historical version rather than the current object. */
+    versionId?: string;
     name: string;
     kind: "missing" | "size_mismatch" | "unreadable" | "hash_mismatch";
     detail: string | null;
 }
-interface IntegrityReportDTO {
+interface IntegrityReportDTO$1 {
     checkedAt: string;
     filesChecked: number;
     healthy: number;
     missing: number;
     inconsistent: number;
     unreadable: number;
-    issues: IntegrityIssueDTO[];
+    issues: IntegrityIssueDTO$1[];
     durationMs: number;
 }
 interface BatchResultDTO {
@@ -190,12 +264,12 @@ interface BatchResultDTO {
     failed: number;
     errors: {
         id: string;
-        code: ErrorCode;
+        code: ErrorCode$1;
         message: string;
     }[];
 }
 /** Stable machine-readable error codes returned in API error bodies. */
-declare const ERROR_CODES: {
+declare const ERROR_CODES$1: {
     readonly AUTH_REQUIRED: "AUTH_REQUIRED";
     readonly AUTH_INVALID: "AUTH_INVALID";
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
@@ -216,10 +290,10 @@ declare const ERROR_CODES: {
     readonly INTEGRITY_CHECK_FAILED: "INTEGRITY_CHECK_FAILED";
     readonly INTERNAL: "INTERNAL_ERROR";
 };
-type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+type ErrorCode$1 = (typeof ERROR_CODES$1)[keyof typeof ERROR_CODES$1];
 interface ApiErrorBody {
     error: {
-        code: ErrorCode;
+        code: ErrorCode$1;
         message: string;
         details?: unknown;
         requestId?: string;
@@ -269,8 +343,14 @@ interface UploadOptions {
     retry?: number;
 }
 interface UploadInput {
-    /** File content: Blob/File in the browser, Buffer/Uint8Array in Node. */
-    data: Blob | Uint8Array;
+    /**
+     * File content: a Blob/File, a Uint8Array/Buffer, a web ReadableStream, or (in
+     * Node) a Readable stream. Streams are read in chunks; the caller never has to
+     * build one large buffer.
+     */
+    data?: Blob | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+    /** Node only: a path to read the file from. Use instead of `data`. */
+    path?: string;
     /** Filename; also used to derive the MIME type server-side. */
     name: string;
 }
@@ -279,6 +359,13 @@ interface DownloadProgress {
     total: number | null;
     percent: number | null;
 }
+interface StreamedDownload {
+    stream: ReadableStream<Uint8Array>;
+    contentType: string;
+    /** Declared byte length, or null when the server did not send one. */
+    size: number | null;
+    sha256: string | null;
+}
 interface DownloadResult {
     data: Buffer | Uint8Array;
     contentType: string;
@@ -321,6 +408,12 @@ declare class OmniCloudClient {
     /** @internal */
     withRetry<T>(operation: () => Promise<T>): Promise<T>;
     /** @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.
+     */
+    requestStream(path: string, onProgress?: (p: DownloadProgress) => void): Promise<StreamedDownload>;
     requestBinary(path: string, onProgress?: (p: DownloadProgress) => void): Promise<DownloadResult>;
 }
 declare class FilesApi {
@@ -328,26 +421,42 @@ declare class FilesApi {
     constructor(client: OmniCloudClient);
     /** `folderId: null` = root; omit it to list every active file. */
     list(query?: ListQuery): Promise<FilesPageDTO>;
-    get(id: string): Promise<FileDTO>;
+    get(id: string): Promise<FileDTO$1>;
     versions(id: string): Promise<FileVersionDTO[]>;
     /**
      * Uploads a file with progress and retry support. Uses XMLHttpRequest when
      * available (browsers) so progress and cancellation work; falls back to
      * fetch elsewhere.
      */
-    upload(input: UploadInput, options?: UploadOptions): Promise<FileDTO>;
+    upload(input: UploadInput, options?: UploadOptions): Promise<FileDTO$1>;
     private uploadOnce;
     private uploadViaXhr;
     /** Uploads a new version of an existing file. */
-    replace(id: string, input: UploadInput): Promise<FileDTO>;
+    replace(id: string, input: UploadInput): Promise<FileDTO$1>;
     download(id: string, onProgress?: (p: DownloadProgress) => void): Promise<DownloadResult>;
+    /**
+     * 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.
+     */
+    downloadStream(id: string, onProgress?: (p: DownloadProgress) => void): Promise<StreamedDownload>;
+    /**
+     * 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`.
+     */
+    downloadToFile(id: string, targetPath: string, onProgress?: (p: DownloadProgress) => void): Promise<{
+        path: string;
+        bytes: number;
+        sha256: string | null;
+    }>;
     /** URL suitable for direct download (anchor href). */
     downloadUrl(id: string): string;
-    rename(id: string, name: string): Promise<FileDTO>;
-    star(id: string, starred?: boolean): Promise<FileDTO>;
-    move(id: string, folderId: string | null): Promise<FileDTO>;
-    trash(id: string): Promise<FileDTO>;
-    restore(id: string): Promise<FileDTO>;
+    rename(id: string, name: string): Promise<FileDTO$1>;
+    star(id: string, starred?: boolean): Promise<FileDTO$1>;
+    move(id: string, folderId: string | null): Promise<FileDTO$1>;
+    trash(id: string): Promise<FileDTO$1>;
+    restore(id: string): Promise<FileDTO$1>;
     /** Permanently deletes a file and its Telegram objects. */
     delete(id: string): Promise<void>;
     /** Batch operation: trash | restore | delete | star | unstar | move. */
@@ -362,11 +471,11 @@ declare class FoldersApi {
         parentId?: string | null;
     }): Promise<FoldersPageDTO>;
     /** The full active folder tree (for move dialogs). */
-    tree(): Promise<FolderDTO[]>;
-    create(name: string, parentId?: string | null): Promise<FolderDTO>;
-    rename(id: string, name: string): Promise<FolderDTO>;
-    star(id: string, starred?: boolean): Promise<FolderDTO>;
-    move(id: string, parentId: string | null): Promise<FolderDTO>;
+    tree(): Promise<FolderDTO$1[]>;
+    create(name: string, parentId?: string | null): Promise<FolderDTO$1>;
+    rename(id: string, name: string): Promise<FolderDTO$1>;
+    star(id: string, starred?: boolean): Promise<FolderDTO$1>;
+    move(id: string, parentId: string | null): Promise<FolderDTO$1>;
     trash(id: string): Promise<FolderMutationResultDTO>;
     restore(id: string): Promise<FolderMutationResultDTO>;
     /** Permanently deletes the folder subtree and its Telegram objects. */
@@ -397,7 +506,7 @@ declare class StorageApi {
     /** Read-only integrity scan; nothing is repaired or deleted. */
     integrityCheck(options?: {
         deep?: boolean;
-    }): Promise<IntegrityReportDTO>;
+    }): Promise<IntegrityReportDTO$1>;
     /** Public server health (no authentication required). */
     serverHealth(): Promise<HealthDTO>;
 }
@@ -411,7 +520,7 @@ declare class SearchApi {
     query(q: string, page?: {
         page?: number;
         limit?: number;
-    }): Promise<SearchResultDTO>;
+    }): Promise<SearchResultDTO$1>;
 }
 declare class RecentApi {
     private readonly client;
@@ -419,7 +528,7 @@ declare class RecentApi {
     list(page?: {
         page?: number;
         limit?: number;
-    }): Promise<RecentPageDTO>;
+    }): Promise<RecentPageDTO$1>;
 }
 declare class ActivityApi {
     private readonly client;
@@ -444,5 +553,1092 @@ declare class AuthApi {
 
 /** Connection state of the underlying storage backend. */
 type ConnectionState = "DISCONNECTED" | "CONNECTING" | "CONNECTED" | "RECONNECTING" | "ERROR" | "AUTH_REQUIRED";
+interface FileDTO {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    folderId: string | null;
+    starred: boolean;
+    trashed: boolean;
+    deletedAt: string | null;
+    versionCount: number;
+    currentVersionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FolderDTO {
+    id: string;
+    name: string;
+    parentId: string | null;
+    starred: boolean;
+    trashed: boolean;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SearchResultDTO {
+    files: FileDTO[];
+    folders: FolderDTO[];
+    pagination: PaginationDTO;
+}
+interface PaginationDTO {
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+}
+interface RecentItemDTO {
+    file: FileDTO;
+    lastAction: ActivityAction;
+    lastActionAt: string;
+}
+interface RecentPageDTO {
+    items: RecentItemDTO[];
+    pagination: PaginationDTO;
+}
+declare const ACTIVITY_ACTIONS: readonly ["upload", "download", "open", "rename", "move", "star", "unstar", "trash", "restore", "delete", "create_folder", "replace"];
+type ActivityAction = (typeof ACTIVITY_ACTIONS)[number];
+declare const RESOURCE_TYPES: readonly ["file", "folder", "storage"];
+type ResourceType = (typeof RESOURCE_TYPES)[number];
+interface IntegrityIssueDTO {
+    fileId: string;
+    /** Set when the issue is with a historical version rather than the current object. */
+    versionId?: string;
+    name: string;
+    kind: "missing" | "size_mismatch" | "unreadable" | "hash_mismatch";
+    detail: string | null;
+}
+interface IntegrityReportDTO {
+    checkedAt: string;
+    filesChecked: number;
+    healthy: number;
+    missing: number;
+    inconsistent: number;
+    unreadable: number;
+    issues: IntegrityIssueDTO[];
+    durationMs: number;
+}
+/** Stable machine-readable error codes returned in API error bodies. */
+declare const ERROR_CODES: {
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly AUTH_INVALID: "AUTH_INVALID";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    readonly FOLDER_NOT_FOUND: "FOLDER_NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly STORAGE_NOT_INITIALIZED: "STORAGE_NOT_INITIALIZED";
+    readonly STORAGE_UNAVAILABLE: "STORAGE_UNAVAILABLE";
+    readonly TELEGRAM_AUTH_REQUIRED: "TELEGRAM_AUTH_REQUIRED";
+    readonly TELEGRAM_CONNECTION_FAILED: "TELEGRAM_CONNECTION_FAILED";
+    readonly TELEGRAM_FILE_NOT_FOUND: "TELEGRAM_FILE_NOT_FOUND";
+    readonly UPLOAD_FAILED: "UPLOAD_FAILED";
+    readonly DOWNLOAD_FAILED: "DOWNLOAD_FAILED";
+    readonly INTEGRITY_CHECK_FAILED: "INTEGRITY_CHECK_FAILED";
+    readonly INTERNAL: "INTERNAL_ERROR";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+/**
+ * Base class for all domain errors. The API maps these to structured HTTP
+ * responses; everything else becomes a 500.
+ */
+declare class DomainError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    readonly details?: unknown;
+    /** Whether repeating the same operation may succeed. Defaults to false. */
+    readonly retryable: boolean;
+    /** Server-requested delay before a retry, in seconds, when the provider gave one. */
+    readonly retryAfterSeconds?: number;
+    constructor(code: ErrorCode, status: number, message: string, details?: unknown, retry?: {
+        retryable?: boolean;
+        retryAfterSeconds?: number;
+    });
+}
+/**
+ * Wraps an arbitrary provider failure as an UploadFailedError (the default
+ * storage-operation error), preserving domain errors untouched.
+ */
+declare function mapProviderError(message: string, error: unknown): DomainError;
+
+/**
+ * Domain records. Repository implementations (e.g. the Prisma layer) map
+ * their persistence models onto these records; the rest of the application
+ * only ever works with them.
+ *
+ * Telegram identifiers are represented as strings/numbers that fit in
+ * JavaScript's safe integer range; the persistence layer converts as needed.
+ */
+
+interface UserRecord {
+    id: string;
+    telegramUserId: string;
+    username: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    phone: string | null;
+    createdAt: Date;
+}
+interface TelegramSessionRecord {
+    userId: string;
+    stringSession: string;
+}
+interface StorageRecord {
+    id: string;
+    userId: string;
+    provider: string;
+    title: string;
+    telegramChatId: string;
+    telegramAccessHash: string;
+    createdAt: Date;
+}
+interface FolderRecord {
+    id: string;
+    userId: string;
+    parentId: string | null;
+    name: string;
+    starred: boolean;
+    /** Soft-delete marker (null = active). */
+    deletedAt: Date | null;
+    /**
+     * Groups everything moved to the Trash by one operation, so restoring a
+     * folder restores exactly what it took (and leaves separately-trashed
+     * items alone). Null for items trashed individually.
+     */
+    trashBatchId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface FileRecord {
+    id: string;
+    userId: string;
+    folderId: string | null;
+    name: string;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
+    starred: boolean;
+    /** Soft-delete marker (null = active). */
+    deletedAt: Date | null;
+    /** See FolderRecord.trashBatchId. */
+    trashBatchId: string | null;
+    /** Current version row, if versioning has been initialized for this file. */
+    currentVersionId: string | null;
+    versionCount: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface FileVersionRecord {
+    id: string;
+    fileId: string;
+    userId: string;
+    versionNumber: number;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
+    createdAt: Date;
+}
+interface ActivityEventRecord {
+    id: string;
+    userId: string;
+    action: ActivityAction;
+    resourceType: ResourceType;
+    resourceId: string;
+    resourceName: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+}
+/** Resolved, repository-ready item query (search parser output resolved). */
+interface ItemQuery {
+    /** Restrict to a folder (null = root). Undefined = any folder. */
+    folderId?: string | null;
+    /** Restrict to a set of folder ids (used for `folder:Name` filters). */
+    folderIds?: string[];
+    nameContains?: string;
+    /** MIME matchers: exact values or prefixes ending in "/". */
+    mimeMatchers?: readonly string[];
+    ext?: string;
+    starred?: boolean;
+    /** false = active only, true = trashed only, undefined = both. */
+    trashed?: boolean;
+    minSize?: number;
+    maxSize?: number;
+    from?: Date;
+    to?: Date;
+    sort?: SortField;
+    order?: SortOrder;
+}
+interface PageRequest {
+    page: number;
+    limit: number;
+}
+interface Paged<T> {
+    items: T[];
+    total: number;
+}
+interface FileTypeBucket {
+    category: string;
+    bytes: number;
+    count: number;
+}
+interface StorageStats {
+    fileCount: number;
+    folderCount: number;
+    totalBytes: number;
+    trashBytes: number;
+    trashFileCount: number;
+    starredCount: number;
+    byType: FileTypeBucket[];
+    largestFiles: FileRecord[];
+    /** Optional quota ceiling (null = unlimited, the v0.2 default). */
+    quotaBytes: number | null;
+}
+
+/**
+ * Upload operations are the durable record of one logical upload. They exist so
+ * that a retried request (same operation id) can resume or replay instead of
+ * writing a second Telegram object and a second file record.
+ *
+ * PENDING    accepted, Telegram write not started
+ * UPLOADING  Telegram write in progress or its outcome unknown
+ * COMPLETED  Telegram object stored and file record committed; result is final
+ * FAILED     Telegram write definitively failed; the operation may be retried
+ *            under a new id
+ */
+type UploadOperationStatus = "PENDING" | "UPLOADING" | "COMPLETED" | "FAILED";
+
+/**
+ * Repository interfaces. The application depends on these, not on a specific
+ * database — the Prisma implementation lives in @omnicloud/database, and
+ * tests use in-memory implementations.
+ */
+interface UserRepository {
+    findById(id: string): Promise<UserRecord | null>;
+    findByTelegramId(telegramUserId: string): Promise<UserRecord | null>;
+    upsertFromTelegram(input: {
+        telegramUserId: string;
+        username: string | null;
+        firstName: string | null;
+        lastName: string | null;
+        phone: string | null;
+    }): Promise<UserRecord>;
+}
+interface SessionRepository {
+    get(userId: string): Promise<TelegramSessionRecord | null>;
+    save(userId: string, stringSession: string): Promise<void>;
+    delete(userId: string): Promise<void>;
+}
+interface BrowserSessionRecord {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    createdAt: Date;
+    expiresAt: Date;
+    revokedAt: Date | null;
+    lastUsedAt: Date | null;
+    userAgent: string | null;
+    ip: string | null;
+}
+/** Server-side browser sessions. Holds only token hashes, never raw tokens. */
+interface BrowserSessionRepository {
+    create(input: {
+        userId: string;
+        tokenHash: string;
+        expiresAt: Date;
+        userAgent: string | null;
+        ip: string | null;
+    }): Promise<BrowserSessionRecord>;
+    findByTokenHash(tokenHash: string): Promise<BrowserSessionRecord | null>;
+    touch(id: string, at: Date): Promise<void>;
+    revoke(id: string, at: Date): Promise<void>;
+    revokeAllForUser(userId: string, at: Date): Promise<number>;
+    listActiveForUser(userId: string, now: Date): Promise<BrowserSessionRecord[]>;
+    deleteExpiredBefore(cutoff: Date): Promise<number>;
+}
+interface StorageRepository {
+    findByUserAndProvider(userId: string, provider: string): Promise<StorageRecord | null>;
+    create(input: {
+        userId: string;
+        provider: string;
+        title: string;
+        telegramChatId: string;
+        telegramAccessHash: string;
+    }): Promise<StorageRecord>;
+}
+interface FolderCreateInput {
+    userId: string;
+    parentId: string | null;
+    name: string;
+}
+interface FolderRepository {
+    create(input: FolderCreateInput): Promise<FolderRecord>;
+    /**
+     * Re-parents a folder only if the result stays acyclic. The ancestor check and
+     * the write are one atomic step, so two concurrent moves cannot each pass the
+     * check and together create a cycle. Throws ConflictError on a cycle.
+     */
+    moveSafely(id: string, newParentId: string | null): Promise<FolderRecord>;
+    findById(id: string): Promise<FolderRecord | null>;
+    /** Every folder belonging to the user (used for trees and cascade logic). */
+    listByUser(userId: string): Promise<FolderRecord[]>;
+    listChildren(userId: string, parentId: string | null): Promise<FolderRecord[]>;
+    /** Filtered, sorted, paginated listing. */
+    query(userId: string, query: ItemQuery, page: PageRequest): Promise<Paged<FolderRecord>>;
+    /** Folder ids matching a name substring (used to resolve `folder:` filters). */
+    findIdsByName(userId: string, name: string): Promise<string[]>;
+    update(id: string, patch: {
+        name?: string;
+        parentId?: string | null;
+        starred?: boolean;
+        deletedAt?: Date | null;
+        trashBatchId?: string | null;
+    }): Promise<FolderRecord>;
+    /** Bulk trash/restore/star without touching files. */
+    updateMany(ids: string[], patch: {
+        starred?: boolean;
+        deletedAt?: Date | null;
+        trashBatchId?: string | null;
+    }): Promise<number>;
+    deleteMany(ids: string[]): Promise<void>;
+    countByUser(userId: string): Promise<number>;
+}
+interface FileCreateInput {
+    userId: string;
+    folderId: string | null;
+    name: string;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
+}
+interface UploadOperationRecord {
+    id: string;
+    userId: string;
+    operationId: string;
+    status: UploadOperationStatus;
+    /** Set once the Telegram object exists, so recovery can commit without re-uploading. */
+    telegramMessageId: number | null;
+    sha256: string | null;
+    size: number | null;
+    fileId: string | null;
+    error: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Durable upload attempts, scoped to the owning user. */
+interface UploadOperationRepository {
+    findByOperationId(userId: string, operationId: string): Promise<UploadOperationRecord | null>;
+    /** Operations for a user in the given states (used by reconciliation). */
+    listByStatus(userId: string, status: UploadOperationStatus): Promise<UploadOperationRecord[]>;
+    create(input: {
+        userId: string;
+        operationId: string;
+    }): Promise<UploadOperationRecord>;
+    /**
+     * Atomically moves an operation from `from` to `to` if, and only if, it is
+     * still in `from`. Returns false when another request already moved it, so
+     * exactly one request performs the upload.
+     */
+    claim(id: string, from: UploadOperationStatus, to: UploadOperationStatus): Promise<boolean>;
+    update(id: string, patch: Partial<Pick<UploadOperationRecord, "status" | "telegramMessageId" | "sha256" | "size" | "fileId" | "error">>): Promise<UploadOperationRecord>;
+}
+interface FileRepository {
+    create(input: FileCreateInput): Promise<FileRecord>;
+    findById(id: string): Promise<FileRecord | null>;
+    /** Active files directly inside a folder (null = root). */
+    listByFolder(userId: string, folderId: string | null): Promise<FileRecord[]>;
+    listByUser(userId: string): Promise<FileRecord[]>;
+    listByIds(userId: string, ids: string[]): Promise<FileRecord[]>;
+    query(userId: string, query: ItemQuery, page: PageRequest): Promise<Paged<FileRecord>>;
+    update(id: string, patch: {
+        name?: string;
+        folderId?: string | null;
+        starred?: boolean;
+        deletedAt?: Date | null;
+        trashBatchId?: string | null;
+        size?: number;
+        mimeType?: string;
+        sha256?: string;
+        telegramMessageId?: number;
+        currentVersionId?: string | null;
+        versionCount?: number;
+    }): Promise<FileRecord>;
+    updateMany(ids: string[], patch: {
+        folderId?: string | null;
+        starred?: boolean;
+        deletedAt?: Date | null;
+        trashBatchId?: string | null;
+    }): Promise<number>;
+    /** Aggregate counters used by the storage dashboard. */
+    statsByUser(userId: string): Promise<{
+        fileCount: number;
+        folderCount: number;
+        totalBytes: number;
+        trashBytes: number;
+        trashFileCount: number;
+        starredCount: number;
+    }>;
+    deleteMany(ids: string[]): Promise<void>;
+    createVersion(input: {
+        fileId: string;
+        userId: string;
+        size: number;
+        mimeType: string;
+        sha256: string;
+        telegramMessageId: number;
+    }): Promise<FileVersionRecord>;
+    listVersions(fileId: string): Promise<FileVersionRecord[]>;
+    /** All versions for many files in one query, grouped by file id. */
+    listVersionsForFiles(fileIds: string[]): Promise<Map<string, FileVersionRecord[]>>;
+    findVersionById(versionId: string): Promise<FileVersionRecord | null>;
+    countVersions(fileId: string): Promise<number>;
+    deleteVersionsByFileIds(fileIds: string[]): Promise<void>;
+}
+interface ActivityRepository {
+    record(input: {
+        userId: string;
+        action: ActivityAction;
+        resourceType: ResourceType;
+        resourceId: string;
+        resourceName?: string | null;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<void>;
+    /** Newest-first activity for a user. */
+    list(userId: string, page: PageRequest): Promise<Paged<ActivityEventRecord>>;
+    /**
+     * Most recent distinct files for the given actions, newest first. Only
+     * events whose action is listed are considered, so a file whose latest
+     * event is (say) a star still surfaces via its last meaningful action.
+     */
+    recentFiles(userId: string, actions: readonly ActivityAction[], limit: number): Promise<ActivityEventRecord[]>;
+    countByUser(userId: string): Promise<number>;
+    /** Housekeeping: drop events older than the retention window. */
+    pruneOlderThan(cutoff: Date): Promise<number>;
+}
+interface Repos {
+    users: UserRepository;
+    sessions: SessionRepository;
+    browserSessions: BrowserSessionRepository;
+    uploadOperations: UploadOperationRepository;
+    storages: StorageRepository;
+    folders: FolderRepository;
+    files: FileRepository;
+    activity: ActivityRepository;
+}
+
+/**
+ * Generic storage abstraction. The application must never depend on
+ * Telegram-specific details — it talks to a StorageProvider.
+ *
+ * v0.2 adds streaming, progress reporting, cancellation and health checks
+ * while keeping the abstraction provider-agnostic.
+ */
+/** Reference to an object inside the backing store (opaque to callers). */
+interface StoredRef {
+    messageId: string;
+}
+interface StoredObject extends StoredRef {
+    name: string;
+    size: number;
+    mimeType: string;
+}
+/** Transfer progress emitted during upload/download. */
+interface TransferProgress {
+    /** Bytes transferred so far. */
+    transferred: number;
+    /** Total bytes, when known upfront. */
+    total: number | null;
+    /** 0–100 when total is known, otherwise null. */
+    percent: number | null;
+}
+interface TransferControl {
+    /** Aborted when the caller cancels the operation. */
+    signal?: AbortSignal;
+    onProgress?: (progress: TransferProgress) => void;
+}
+/**
+ * Upload input. Exactly one of `data` (small, in memory) or `path` (a spooled
+ * file on disk, read in slices by the provider) must be given.
+ */
+interface StorageUploadInput {
+    name: string;
+    mimeType: string;
+    /** Whole-object buffer (small files). */
+    data?: Buffer;
+    /** Path to a spooled file (large files). Its bytes are never fully loaded. */
+    path?: string;
+    /** Total byte length of the object. Required with `path`. */
+    size?: number;
+    /** SHA-256 of the spooled bytes, computed while they were written. Required with `path`. */
+    sha256?: string;
+}
+interface StorageHealth {
+    /** Reachable and usable. */
+    healthy: boolean;
+    /** Round-trip latency of the probe in milliseconds, when measured. */
+    latencyMs: number | null;
+    message: string | null;
+    /** Name of the storage channel/target, when available. */
+    targetTitle: string | null;
+}
+interface StorageProvider {
+    readonly name: string;
+    /**
+     * Uploads an object and returns the stored reference. Reports progress and
+     * honors `control.signal` for cancellation.
+     */
+    put(input: StorageUploadInput, control?: TransferControl): Promise<StoredObject>;
+    /** Downloads the object's content as a Buffer. */
+    get(ref: StoredRef, control?: TransferControl): Promise<Buffer>;
+    /** Opens a stream for the object (large-file friendly). */
+    getStream(ref: StoredRef, control?: TransferControl): Promise<Readable>;
+    /** Deletes the object. Deleting an already-missing object must not throw. */
+    delete(ref: StoredRef): Promise<void>;
+    exists(ref: StoredRef): Promise<boolean>;
+    stat(ref: StoredRef): Promise<StoredObject | null>;
+    /**
+     * Lists the objects the backing store holds, newest first, read-only. Used by
+     * reconciliation; it must never modify anything. Implementations page through
+     * the store and stop once `limit` objects are returned.
+     */
+    listObjects(limit: number): Promise<StoredObject[]>;
+    /** Validates that the backing store is reachable and usable. */
+    healthCheck(): Promise<StorageHealth>;
+}
+
+declare function sha256Hex(data: Uint8Array): string;
+
+interface EngineUploadResult {
+    stored: StoredObject;
+    sha256: string;
+    size: number;
+}
+interface EngineRetryPolicy {
+    /** Total attempts, including the first. */
+    attempts: number;
+    /** Base delay in ms; doubles per retry. */
+    baseDelayMs: number;
+}
+/**
+ * Sits between the application and the raw StorageProvider and adds the
+ * cross-cutting guarantees: SHA-256 integrity, streaming, progress reporting,
+ * cancellation and bounded retries.
+ *
+ * The active provider is chosen per user by the host application (each user
+ * has their own Telegram storage channel).
+ */
+declare class StorageEngine {
+    private readonly provider;
+    private readonly retryPolicy;
+    constructor(provider: StorageProvider, retryPolicy?: EngineRetryPolicy);
+    get providerName(): string;
+    /**
+     * Uploads an object, computing its SHA-256 as it goes and reporting
+     * progress. Retries transient failures with exponential backoff.
+     */
+    upload(input: StorageUploadInput, control?: TransferControl): Promise<EngineUploadResult>;
+    download(ref: StoredRef, control?: TransferControl): Promise<Buffer>;
+    /**
+     * 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.
+     */
+    downloadStream(ref: StoredRef, expectedSha256: string, control?: TransferControl): Promise<Readable>;
+    remove(ref: StoredRef): Promise<void>;
+    exists(ref: StoredRef): Promise<boolean>;
+    /** Read-only listing of stored objects, for reconciliation. Never modifies anything. */
+    list(limit: number): Promise<StoredObject[]>;
+    stat(ref: StoredRef): Promise<StoredObject | null>;
+    health(): Promise<StorageHealth>;
+    verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
+    private withRetry;
+}
+
+interface OperationSink {
+    info(record: Record<string, unknown>, message: string): void;
+    warn(record: Record<string, unknown>, message: string): void;
+}
+
+interface RecordActivityInput {
+    userId: string;
+    action: ActivityAction;
+    resourceType: ResourceType;
+    resourceId: string;
+    resourceName?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * The narrow interface other services depend on for activity logging, so a
+ * no-op recorder can be substituted in tests and activity failures never
+ * break the operation being logged.
+ */
+interface ActivityRecorder {
+    record(input: RecordActivityInput): Promise<void>;
+}
+/** Activity log with best-effort recording and retention pruning. */
+declare class ActivityService implements ActivityRecorder {
+    private readonly activity;
+    /** Days to retain events; older rows are pruned on demand. */
+    private readonly retentionDays;
+    constructor(activity: ActivityRepository, 
+    /** Days to retain events; older rows are pruned on demand. */
+    retentionDays?: number);
+    /**
+     * Records an event. Never throws — a logging failure must not fail the
+     * user-facing operation that produced it.
+     */
+    record(input: RecordActivityInput): Promise<void>;
+    list(userId: string, page: PageRequest): Promise<Paged<ActivityEventRecord>>;
+    /** Most recent distinct files for the given actions, for the Recent view. */
+    recentFiles(userId: string, actions: readonly ActivityAction[], limit: number): Promise<ActivityEventRecord[]>;
+    prune(): Promise<number>;
+}
+/** A recorder that discards events (used where activity is not wired up). */
+declare const noopActivityRecorder: ActivityRecorder;
+
+interface FileDownload {
+    record: FileRecord;
+    data: Buffer;
+    integrityVerified: boolean;
+}
+interface FileStreamDownload {
+    record: FileRecord;
+    /** Errors with IntegrityCheckError instead of ending if the bytes do not match. */
+    stream: Readable;
+}
+type EngineResolver = (userId: string) => Promise<StorageEngine>;
+interface FileUploadInput {
+    folderId: string | null;
+    name: string;
+    /** In-memory content. Use `spooled` for anything large. */
+    data?: Buffer;
+    /** A file already written to disk by `spoolToFile`, with its checksum. */
+    spooled?: {
+        path: string;
+        size: number;
+        sha256: string;
+    };
+    /** When set, uploads a new version of this file instead of creating one. */
+    replaceFileId?: string;
+    /** Client-supplied id that makes the upload idempotent across retries. */
+    operationId?: string;
+    /** Progress callback forwarded from the transport layer. */
+    onProgress?: (progress: TransferProgress) => void;
+    signal?: AbortSignal;
+}
+/**
+ * File metadata operations. Every method verifies ownership: records
+ * belonging to other users are reported as missing.
+ *
+ * Reliability rules honored here:
+ *  - metadata is written only after the storage upload succeeds;
+ *  - permanent deletion removes the remote object before the metadata;
+ *  - client-supplied ownership is never trusted (userId is server-derived).
+ */
+declare class FileService {
+    private readonly files;
+    private readonly folders;
+    private readonly engineFor;
+    private readonly activity;
+    private readonly operations;
+    private readonly log;
+    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver, activity?: ActivityRecorder, operations?: UploadOperationRepository | null, log?: OperationSink | null);
+    upload(userId: string, input: FileUploadInput): Promise<FileRecord>;
+    /**
+     * 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.
+     */
+    private uploadOnce;
+    /**
+     * 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.
+     */
+    private followWinner;
+    /** Commits metadata for an object that is already in Telegram. */
+    private commitStoredObject;
+    private performUpload;
+    /** Persists the file (or the new version of a file) for an object already stored. */
+    private commitRecord;
+    /** Uploads a new version of an existing file and makes it current. */
+    private replaceVersion;
+    list(userId: string, folderId: string | null): Promise<FileRecord[]>;
+    query(userId: string, input: ListQuery, page: PageRequest): Promise<Paged<FileRecord>>;
+    get(userId: string, id: string): Promise<FileRecord>;
+    /** Like get(), but rejects trashed files (for download/open). */
+    getActive(userId: string, id: string): Promise<FileRecord>;
+    listVersions(userId: string, id: string): Promise<FileVersionRecord[]>;
+    rename(userId: string, id: string, name: string): Promise<FileRecord>;
+    move(userId: string, id: string, folderId: string | null): Promise<FileRecord>;
+    setStarred(userId: string, id: string, starred: boolean): Promise<FileRecord>;
+    /**
+     * Moves a file to Trash (soft delete). The remote object is untouched, so
+     * restore is lossless.
+     */
+    trash(userId: string, id: string): Promise<FileRecord>;
+    /** Restores a trashed file to its previous folder (or root). */
+    restore(userId: string, id: string): Promise<FileRecord>;
+    /**
+     * 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.
+     */
+    deletePermanently(userId: string, id: string): Promise<void>;
+    private performPermanentDelete;
+    /**
+     * v0.1-compatible hard delete used by the current API: permanently removes
+     * the file. Retained so existing clients keep working.
+     */
+    delete(userId: string, id: string): Promise<void>;
+    download(userId: string, id: string, control?: TransferControl): Promise<FileDownload>;
+    /**
+     * 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.
+     */
+    downloadStreamed(userId: string, id: string, control?: TransferControl): Promise<FileStreamDownload>;
+    private performStreamedDownload;
+    /** Records an "open" event (the UI opening the details panel, say). */
+    touch(userId: string, id: string, action?: "open"): Promise<void>;
+    /**
+     * Applies an operation to many files, collecting per-item failures instead
+     * of aborting the whole batch.
+     */
+    batch(userId: string, ids: string[], operation: "trash" | "restore" | "delete" | "star" | "unstar" | "move", options?: {
+        folderId?: string | null;
+        operationId?: string;
+    }): Promise<{
+        operationId?: string;
+        requested: number;
+        succeeded: number;
+        failed: number;
+        errors: {
+            id: string;
+            message: string;
+        }[];
+    }>;
+    private assertFolder;
+}
+
+interface FolderMutationResult {
+    affectedFolders: number;
+    affectedFiles: number;
+}
+/**
+ * Folder lifecycle (v0.2):
+ *
+ *  - Folders are virtual OmniCloud objects with a parent-child hierarchy.
+ *  - Trashing a folder trashes its whole subtree (folders + files) without
+ *    touching Telegram, so restore is lossless.
+ *  - Restoring a folder restores only the nodes that were trashed together
+ *    with it; anything the user trashed separately stays in the Trash.
+ *  - Permanent deletion removes remote objects first, then metadata.
+ */
+declare class FolderService {
+    private readonly folders;
+    private readonly files;
+    private readonly engineFor;
+    private readonly activity;
+    constructor(folders: FolderRepository, files: FileRepository, engineFor: EngineResolver, activity?: ActivityRecorder);
+    create(userId: string, input: {
+        name: string;
+        parentId: string | null;
+    }): Promise<FolderRecord>;
+    /** Active folders directly inside a folder (null = root). */
+    listChildren(userId: string, parentId: string | null): Promise<FolderRecord[]>;
+    query(userId: string, input: ListQuery, page: PageRequest): Promise<Paged<FolderRecord>>;
+    /** Every active folder for the user (used to build trees). */
+    tree(userId: string): Promise<FolderRecord[]>;
+    get(userId: string, id: string): Promise<FolderRecord>;
+    rename(userId: string, id: string, name: string): Promise<FolderRecord>;
+    move(userId: string, id: string, newParentId: string | null): Promise<FolderRecord>;
+    setStarred(userId: string, id: string, starred: boolean): Promise<FolderRecord>;
+    /**
+     * Moves a folder and its entire subtree to the Trash. Nothing is deleted
+     * from Telegram, so restore is lossless.
+     */
+    trash(userId: string, id: string): Promise<FolderMutationResult>;
+    /**
+     * 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.
+     */
+    restore(userId: string, id: string): Promise<FolderMutationResult>;
+    /**
+     * 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.
+     */
+    deletePermanently(userId: string, id: string): Promise<FolderMutationResult>;
+    /**
+     * v0.1-compatible recursive delete. Now routes through the v0.2 permanent
+     * delete so remote cleanup and orphan prevention are consistent.
+     */
+    delete(userId: string, id: string): Promise<FolderMutationResult>;
+    /** The folder plus every descendant (BFS), optionally including trashed. */
+    private collectSubtree;
+    /** Ids of files inside the given folders that are not already trashed. */
+    private collectFileIds;
+}
+
+interface SearchResult {
+    files: FileRecord[];
+    folders: FolderRecord[];
+    pagination: PaginationDTO;
+}
+/**
+ * PostgreSQL-backed search (no Elasticsearch, per the v0.2 scope).
+ *
+ * The user query is parsed into structured filters (`type:`, `size:`,
+ * `folder:`, …) and evaluated by the repository layer, so results respect
+ * ownership and stay safely parameterized.
+ */
+declare class SearchService {
+    private readonly files;
+    private readonly folders;
+    constructor(files: FileRepository, folders: FolderRepository);
+    search(userId: string, rawQuery: string, page: PageRequest, overrides?: ListQuery): Promise<SearchResult>;
+    /** Convenience wrapper returning the shared DTO shape. */
+    searchDTO(userId: string, rawQuery: string, page: PageRequest): Promise<Omit<SearchResultDTO, "files" | "folders"> & SearchResult>;
+}
+
+/**
+ * Storage dashboard statistics, computed from PostgreSQL metadata only —
+ * no Telegram round-trips, so the page is fast and works offline.
+ */
+declare class StatsService {
+    private readonly files;
+    private readonly folders;
+    constructor(files: FileRepository, folders: FolderRepository);
+    stats(userId: string, quotaBytes?: number | null): Promise<StorageStats>;
+}
+
+interface TrashListing {
+    files: FileRecord[];
+    folders: FolderRecord[];
+    pagination: PaginationDTO;
+}
+interface EmptyTrashResult {
+    deletedFiles: number;
+    deletedFolders: number;
+    failedFiles: number;
+}
+/**
+ * Trash is a virtual view over soft-deleted rows. Listing shows only the
+ * explicitly trashed items; emptying removes their remote objects before the
+ * metadata, and reports failures instead of hiding them.
+ */
+declare class TrashService {
+    private readonly files;
+    private readonly folders;
+    private readonly engineFor;
+    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver);
+    list(userId: string, page: PageRequest, extra?: ListQuery): Promise<TrashListing>;
+    /**
+     * Permanently removes everything in the Trash for a user. Folders are
+     * processed root-first so removing a parent also removes its contents.
+     */
+    empty(userId: string): Promise<EmptyTrashResult>;
+    /** Restores a single trashed item (used by the batch restore endpoint). */
+    verifyTrashedFile(userId: string, id: string): Promise<FileRecord>;
+}
+
+interface IntegrityCheckOptions {
+    /** Re-download and re-hash objects (slow but authoritative). */
+    deep?: boolean;
+    /** Maximum files to inspect in one pass. */
+    limit?: number;
+}
+/**
+ * Detects drift between PostgreSQL metadata and Telegram storage:
+ *
+ *  - `missing`     — metadata exists, the Telegram message is gone
+ *  - `size_mismatch` — the stored object's size differs from the metadata
+ *  - `hash_mismatch` — deep mode only: downloaded bytes don't match sha256
+ *  - `unreadable`  — the provider errored while inspecting the object
+ *
+ * The checker is strictly read-only: repairs are a separate, explicit step so
+ * nothing is ever deleted silently (see the v0.2 reliability rules).
+ */
+declare class IntegrityService {
+    private readonly files;
+    private readonly engineFor;
+    constructor(files: FileRepository, engineFor: EngineResolver);
+    check(userId: string, options?: IntegrityCheckOptions): Promise<IntegrityReportDTO>;
+    private inspect;
+    private inspectObject;
+}
+
+/**
+ * Recent view: the most recently touched active files, newest activity first.
+ * Trashed and permanently-deleted files are filtered out so the view never
+ * surfaces items the user cannot open.
+ */
+declare class RecentService {
+    private readonly activity;
+    private readonly files;
+    constructor(activity: ActivityRepository, files: FileRepository);
+    list(userId: string, page: PageRequest): Promise<RecentPageDTO>;
+}
+
+/**
+ * Sanitizes a client-supplied filename into a safe, single path component.
+ * Returns an empty string when nothing usable remains.
+ */
+declare function sanitizeFileName(name: string): string;
+
+interface TelegramCredentials {
+    apiId: number;
+    apiHash: string;
+}
+interface ConnectionStatus {
+    state: ConnectionState;
+    lastError: string | null;
+    lastCheckAt: Date | null;
+    healthy: boolean | null;
+}
+/**
+ * Owns one Telegram (MTProto) connection per authenticated user and tracks an
+ * explicit lifecycle state for each:
+ *
+ *   DISCONNECTED → CONNECTING → CONNECTED
+ *                              ↘ RECONNECTING → CONNECTED
+ *                              ↘ ERROR | AUTH_REQUIRED
+ *
+ * Responsibilities: connect, disconnect, reconnect, validateSession,
+ * healthCheck, refreshConnection. Sessions never leave the server.
+ */
+declare class TelegramClientManager {
+    private readonly credentials;
+    private readonly sessions;
+    private connections;
+    private lastReconnectAt;
+    constructor(credentials: TelegramCredentials, sessions: SessionRepository);
+    /** Returns a connected client, (re)connecting when needed. */
+    getForUser(userId: string): Promise<TelegramClient>;
+    /** Connection status for health reporting and the storage dashboard. */
+    statusForUser(userId: string): ConnectionStatus;
+    /**
+     * Probes a user's connection. Cheap by default (connection state only);
+     * `deep` performs a real Telegram round-trip to validate the session.
+     */
+    healthCheck(userId: string, deep?: boolean): Promise<StorageHealth>;
+    /** Registers an already-authenticated client (from the login flow). */
+    cacheClient(userId: string, client: TelegramClient): void;
+    /** Drops a user's connection (e.g. after logout) without touching storage. */
+    disconnectUser(userId: string): Promise<void>;
+    disconnectAll(): Promise<void>;
+    private isConnected;
+    private connectUser;
+    private reconnect;
+    private establish;
+}
+
+/**
+ * Maps a Telegram (GramJS) failure to a structured domain error with an
+ * appropriate HTTP status and a client-facing message that never leaks
+ * credentials or session material.
+ */
+declare function mapTelegramError(error: unknown, fallbackMessage: string): DomainError;
+
+interface TelegramStorageOptions {
+    /** Raw channel id of the user's private storage channel. */
+    chatId: string;
+    /** Channel access hash required to build the input peer. */
+    accessHash: string;
+    /** Human-readable channel title, surfaced in health reporting. */
+    title?: string;
+}
+/**
+ * StorageProvider implementation backed by the user's private Telegram
+ * channel. Files are sent as force-downloaded documents (no compression), so
+ * every upload is a document message in the channel.
+ *
+ * v0.2 adds progress reporting, cancellation, streamed downloads and a
+ * health check, all translated into the provider-agnostic core vocabulary.
+ */
+declare class TelegramStorageProvider implements StorageProvider {
+    private readonly client;
+    readonly name = "telegram";
+    private readonly peer;
+    private readonly title;
+    constructor(client: TelegramClient, options: TelegramStorageOptions);
+    put(input: StorageUploadInput, control?: TransferControl): Promise<StoredObject>;
+    get(ref: StoredRef, control?: TransferControl): Promise<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.
+     */
+    getStream(ref: StoredRef, control?: TransferControl): Promise<Readable>;
+    delete(ref: StoredRef): Promise<void>;
+    exists(ref: StoredRef): Promise<boolean>;
+    /**
+     * 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.
+     */
+    listObjects(limit: number): Promise<StoredObject[]>;
+    stat(ref: StoredRef): Promise<StoredObject | null>;
+    /**
+     * Validates that the client is connected and the storage channel is
+     * reachable (a real Telegram round-trip on the channel peer).
+     */
+    healthCheck(): Promise<StorageHealth>;
+    private throwIfAborted;
+    private documentSize;
+    private requireMessage;
+    private getMessage;
+}
+
+declare const TELEGRAM_PROVIDER = "telegram";
+type VerifyCodeResult = {
+    status: "ok";
+    user: UserRecord;
+} | {
+    status: "password_required";
+};
+/**
+ * Orchestrates the full Telegram account connection flow:
+ * phone → code (→ 2FA password) → session persisted → user upserted →
+ * private storage channel created.
+ */
+declare class TelegramConnectionService {
+    private readonly repos;
+    private readonly clientManager;
+    private readonly credentials;
+    private flows;
+    constructor(repos: Repos, clientManager: TelegramClientManager, credentials: TelegramCredentials);
+    /** Sends the Telegram confirmation code for the phone number. */
+    startLogin(phone: string): Promise<void>;
+    /** Verifies the confirmation code. Returns `password_required` for 2FA accounts. */
+    verifyCode(phone: string, code: string): Promise<VerifyCodeResult>;
+    /** Completes sign-in for accounts with two-factor authentication enabled. */
+    verifyPassword(phone: string, password: string): Promise<VerifyCodeResult>;
+    /** Aborts a pending login flow (disconnects the client). */
+    cancelLogin(phone: string): Promise<void>;
+    /**
+     * Ensures the user has a registered private storage channel, creating it
+     * on first use. Idempotent.
+     */
+    ensureStorage(userId: string): Promise<StorageRecord>;
+    ensureStorageForClient(userId: string, client: TelegramClient): Promise<StorageRecord>;
+    private requireFlow;
+    private finalizeLogin;
+    private sweepExpiredFlows;
+    private disconnectQuietly;
+}
 
-export { type ActivityEventDTO, type ActivityPageDTO, type ApiErrorBody, type BatchResultDTO, type ConnectionState, type DownloadProgress, type DownloadResult, ERROR_CODES, type EmptyTrashResultDTO, type ErrorCode, type FileDTO, type FileVersionDTO, type FilesPageDTO, type FolderDTO, type FolderMutationResultDTO, type FoldersPageDTO, type HealthDTO, type HealthStatus, type IntegrityIssueDTO, type IntegrityReportDTO, OmniCloudClient, type OmniCloudClientOptions, OmniCloudError, type PaginationDTO, type RecentItemDTO, type RecentPageDTO, type RetryOptions, type SearchResultDTO, type SessionInfo, type StorageDTO, type StorageHealthDTO, type StorageStatsDTO, type StorageTypeBreakdownDTO, type TelegramVerifyResponse, type TrashPageDTO, type UploadInput, type UploadOptions, type UploadProgress, type UserDTO };
+export { type ActivityEventDTO, type ActivityEventRecord, type ActivityPageDTO, type ActivityRecorder, ActivityService, type ApiErrorBody, type BatchResultDTO, type ConnectionState, type ConnectionStatus, DomainError, type DownloadProgress, type DownloadResult, ERROR_CODES$1 as ERROR_CODES, type EmptyTrashResultDTO, type EngineResolver, type EngineRetryPolicy, type EngineUploadResult, type ErrorCode$1 as ErrorCode, type FileCategory, type FileDTO$1 as FileDTO, type FileDownload, type FileRecord, FileService, type FileTypeBucket, type FileVersionDTO, type FileVersionRecord, type FilesPageDTO, type FolderDTO$1 as FolderDTO, type FolderMutationResult, type FolderMutationResultDTO, type FolderRecord, FolderService, type FoldersPageDTO, type HealthDTO, type HealthStatus, type IntegrityCheckOptions, type IntegrityIssueDTO$1 as IntegrityIssueDTO, type IntegrityReportDTO$1 as IntegrityReportDTO, IntegrityService, type ItemQuery, type ItemStatus, type ListQuery, OmniCloudClient, type OmniCloudClientOptions, OmniCloudError, type PageRequest, type Paged, type PaginationDTO$1 as PaginationDTO, type RecentItemDTO$1 as RecentItemDTO, type RecentPageDTO$1 as RecentPageDTO, RecentService, type Repos, type RetryOptions, type SearchResultDTO$1 as SearchResultDTO, SearchService, type SessionInfo, type SortField, type SortOrder, StatsService, type StorageDTO, StorageEngine, type StorageHealth, type StorageHealthDTO, type StorageProvider, type StorageRecord, type StorageStats, type StorageStatsDTO, type StorageTypeBreakdownDTO, type StorageUploadInput, type StoredObject, type StoredRef, type StreamedDownload, TELEGRAM_PROVIDER, TelegramClientManager, TelegramConnectionService, type TelegramCredentials, type TelegramStorageOptions, TelegramStorageProvider, type TelegramVerifyResponse, type TransferControl, type TransferProgress, type TrashPageDTO, TrashService, type UploadInput, type UploadOptions, type UploadProgress, type UserDTO, type UserRecord, fileCategory, isFileCategory, mapProviderError, mapTelegramError, mimeFromFilename, mimeMatchersForType, noopActivityRecorder, paginationMeta, parseSearchQuery, parseSize, sanitizeFileName, sha256Hex };