@lacrous/omnicloud 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -1,14 +1,84 @@
+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 and constants shared between the API, the web app,
- * and the @lacrous/omnicloud SDK.
+ * Data transfer objects, constants and error codes shared between the API,
+ * the web app, and the @lacrous/omnicloud SDK.
  *
  * Telegram identifiers that may exceed JavaScript's safe integer range are
  * transported as strings across the API boundary.
@@ -25,54 +95,197 @@ interface StorageDTO {
     title: string;
     createdAt: string;
 }
+/** Connection state of the underlying storage backend. */
+type ConnectionState$1 = "DISCONNECTED" | "CONNECTING" | "CONNECTED" | "RECONNECTING" | "ERROR" | "AUTH_REQUIRED";
+type HealthStatus = "healthy" | "degraded" | "unavailable" | "unknown";
+interface StorageHealthDTO {
+    provider: string;
+    state: ConnectionState$1;
+    status: HealthStatus;
+    latencyMs: number | null;
+    message: string | null;
+    channelTitle: string | null;
+    checkedAt: string;
+}
 /** Returned by GET /api/auth/me. `user` is null when not signed in. */
 interface SessionInfo {
     user: UserDTO | null;
     storage: StorageDTO | null;
+    health: StorageHealthDTO | null;
 }
-interface FileDTO {
+/** POST /api/auth/telegram/verify response. */
+type TelegramVerifyResponse = {
+    status: "ok";
+    user: UserDTO;
+} | {
+    status: "password_required";
+};
+interface FileDTO$1 {
     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 {
+interface FolderDTO$1 {
     id: string;
     name: string;
     parentId: string | null;
+    starred: boolean;
+    trashed: boolean;
+    deletedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }
-interface SearchResultDTO {
-    files: FileDTO[];
-    folders: FolderDTO[];
+interface FileVersionDTO {
+    id: string;
+    fileId: string;
+    versionNumber: number;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
+    isCurrent: boolean;
+    createdAt: string;
 }
-interface DeleteFolderResultDTO {
-    deletedFolders: number;
+interface SearchResultDTO$1 {
+    files: FileDTO$1[];
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
+}
+/** Result of a recursive folder deletion / trash operation. */
+interface FolderMutationResultDTO {
+    affectedFolders: number;
+    affectedFiles: number;
+}
+interface EmptyTrashResultDTO {
     deletedFiles: number;
+    deletedFolders: number;
+    failedFiles: number;
+}
+
+interface PaginationDTO$1 {
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+}
+interface FilesPageDTO {
+    files: FileDTO$1[];
+    pagination: PaginationDTO$1;
+}
+interface FoldersPageDTO {
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
+}
+interface TrashPageDTO {
+    files: FileDTO$1[];
+    folders: FolderDTO$1[];
+    pagination: PaginationDTO$1;
+}
+interface RecentItemDTO$1 {
+    file: FileDTO$1;
+    lastAction: ActivityAction$1;
+    lastActionAt: string;
+}
+interface RecentPageDTO$1 {
+    items: RecentItemDTO$1[];
+    pagination: PaginationDTO$1;
+}
+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$1;
+    resourceType: ResourceType$1;
+    resourceId: string;
+    resourceName: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ActivityPageDTO {
+    events: ActivityEventDTO[];
+    pagination: PaginationDTO$1;
+}
+interface StorageTypeBreakdownDTO {
+    category: string;
+    bytes: number;
+    count: number;
+}
+interface StorageStatsDTO {
+    fileCount: number;
+    folderCount: number;
+    totalBytes: number;
+    trashBytes: number;
+    trashFileCount: number;
+    starredCount: number;
+    byType: StorageTypeBreakdownDTO[];
+    largestFiles: FileDTO$1[];
+    quotaBytes: number | null;
+}
+interface HealthDTO {
+    status: HealthStatus;
+    database: HealthStatus;
+    storage: HealthStatus;
+    uptimeSeconds: number;
+    version: string;
+}
+interface IntegrityIssueDTO$1 {
+    fileId: string;
+    name: string;
+    kind: "missing" | "size_mismatch" | "unreadable" | "hash_mismatch";
+    detail: string | null;
+}
+interface IntegrityReportDTO$1 {
+    checkedAt: string;
+    filesChecked: number;
+    healthy: number;
+    missing: number;
+    inconsistent: number;
+    unreadable: number;
+    issues: IntegrityIssueDTO$1[];
+    durationMs: number;
+}
+interface BatchResultDTO {
+    requested: number;
+    succeeded: number;
+    failed: number;
+    errors: {
+        id: string;
+        code: ErrorCode$1;
+        message: string;
+    }[];
 }
-/** POST /api/auth/telegram/verify response. */
-type TelegramVerifyResponse = {
-    status: "ok";
-    user: UserDTO;
-} | {
-    status: "password_required";
-};
 /** Stable machine-readable error codes returned in API error bodies. */
 declare const ERROR_CODES$1: {
-    readonly VALIDATION: "VALIDATION_ERROR";
-    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
-    readonly FORBIDDEN: "FORBIDDEN";
+    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 TELEGRAM_ERROR: "TELEGRAM_ERROR";
+    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$1 = (typeof ERROR_CODES$1)[keyof typeof ERROR_CODES$1];
@@ -81,19 +294,38 @@ interface ApiErrorBody {
         code: ErrorCode$1;
         message: string;
         details?: unknown;
+        requestId?: string;
     };
 }
 
+/**
+ * Errors surfaced by the SDK. `code` mirrors the server's stable error codes
+ * and `requestId` correlates with server logs.
+ */
 declare class OmniCloudError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    readonly requestId: string | undefined;
+    readonly details: unknown;
+    constructor(status: number, code: string, message: string, requestId?: string | undefined, details?: unknown);
+}
+interface RetryOptions {
+    /** Total attempts including the first. Default 3. */
+    attempts?: number;
+    /** Base backoff in ms (doubles per retry). Default 300. */
+    baseDelayMs?: number;
 }
 interface OmniCloudClientOptions {
-    /** Base URL of an OmniCloud server. Defaults to same-origin ("" is kept as-is). */
+    /** Base URL of an OmniCloud server (e.g. "https://cloud.example"). */
     baseUrl?: string;
-    /** Custom fetch implementation (e.g. for tests). */
+    /** Bearer token, when the deployment uses token auth instead of cookies. */
+    token?: string;
+    /** Custom fetch implementation (tests, polyfills). */
     fetchImpl?: typeof fetch;
+    /** Retry policy for transient failures. */
+    retry?: RetryOptions;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
 }
 interface UploadProgress {
     loaded: number;
@@ -103,22 +335,175 @@ interface UploadProgress {
 interface UploadOptions {
     folderId?: string | null;
     onProgress?: (progress: UploadProgress) => void;
+    /** Aborts the upload. */
+    signal?: AbortSignal;
+    /** Number of retry attempts for failed uploads. Default 2. */
+    retry?: number;
 }
 interface UploadInput {
-    /** File content: a File/Blob in the browser, or a Buffer/Uint8Array in Node. */
+    /** File content: Blob/File in the browser, Buffer/Uint8Array in Node. */
     data: Blob | Uint8Array;
+    /** Filename; also used to derive the MIME type server-side. */
     name: string;
 }
+interface DownloadProgress {
+    loaded: number;
+    total: number | null;
+    percent: number | null;
+}
+interface DownloadResult {
+    data: Buffer | Uint8Array;
+    contentType: string;
+    size: number;
+    sha256: string | null;
+    integrityVerified: boolean | null;
+}
 /**
- * HTTP client for an OmniCloud server.
+ * Naming: every endpoint group is a namespaced sub-client so calls read like
+ *
+ *   cloud.files.list({ folderId })
+ *   cloud.trash.empty()
+ *   cloud.storage.stats()
  *
- * Works in browsers (cookie sessions, upload progress via XHR) and Node.js
- * (fetch fallback, cookie forwarding is the caller's responsibility).
+ * Works in browsers (cookie sessions, XHR upload progress) and Node
+ * (fetch, Buffer downloads).
  */
 declare class OmniCloudClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
+    readonly files: FilesApi;
+    readonly folders: FoldersApi;
+    readonly trash: TrashApi;
+    readonly storage: StorageApi;
+    readonly search: SearchApi;
+    readonly recent: RecentApi;
+    readonly activity: ActivityApi;
+    readonly auth: AuthApi;
+    /** @internal */
+    readonly baseUrl: string;
+    /** @internal */
+    readonly fetchImpl: typeof fetch;
+    /** @internal */
+    readonly retry: Required<RetryOptions>;
+    /** @internal */
+    readonly defaultHeaders: Record<string, string>;
     constructor(options?: OmniCloudClientOptions);
+    /** Low-level request helper (retries transient failures). */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal */
+    rawRequest<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal */
+    withRetry<T>(operation: () => Promise<T>): Promise<T>;
+    /** @internal */
+    requestBinary(path: string, onProgress?: (p: DownloadProgress) => void): Promise<DownloadResult>;
+}
+declare class FilesApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    /** `folderId: null` = root; omit it to list every active file. */
+    list(query?: ListQuery): Promise<FilesPageDTO>;
+    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$1>;
+    private uploadOnce;
+    private uploadViaXhr;
+    /** Uploads a new version of an existing file. */
+    replace(id: string, input: UploadInput): Promise<FileDTO$1>;
+    download(id: string, onProgress?: (p: DownloadProgress) => void): Promise<DownloadResult>;
+    /** URL suitable for direct download (anchor href). */
+    downloadUrl(id: string): string;
+    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. */
+    batch(operation: "trash" | "restore" | "delete" | "star" | "unstar" | "move", ids: string[], options?: {
+        folderId?: string | null;
+    }): Promise<BatchResultDTO>;
+}
+declare class FoldersApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(query?: ListQuery & {
+        parentId?: string | null;
+    }): Promise<FoldersPageDTO>;
+    /** The full active folder tree (for move dialogs). */
+    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. */
+    delete(id: string): Promise<FolderMutationResultDTO>;
+    batch(operation: "trash" | "restore" | "delete" | "star" | "unstar" | "move", ids: string[], options?: {
+        parentId?: string | null;
+    }): Promise<BatchResultDTO>;
+}
+declare class TrashApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(query?: ListQuery): Promise<TrashPageDTO>;
+    /** Permanently removes everything in the Trash. */
+    empty(): Promise<EmptyTrashResultDTO>;
+}
+declare class StorageApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    /** Creates the private storage channel if it does not exist yet. */
+    ensure(): Promise<StorageDTO>;
+    stats(): Promise<StorageStatsDTO>;
+    health(): Promise<{
+        health: StorageHealthDTO;
+        stats: StorageStatsDTO;
+    }>;
+    /** Probes the storage backend; `deep` performs a real Telegram round-trip. */
+    check(deep?: boolean): Promise<StorageHealthDTO>;
+    /** Read-only integrity scan; nothing is repaired or deleted. */
+    integrityCheck(options?: {
+        deep?: boolean;
+    }): Promise<IntegrityReportDTO$1>;
+    /** Public server health (no authentication required). */
+    serverHealth(): Promise<HealthDTO>;
+}
+declare class SearchApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    /**
+     * Searches with the v0.2 query language:
+     *   `type:pdf`, `size:>100MB`, `folder:Projects`, `starred:true`, `after:2026-01-01`
+     */
+    query(q: string, page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<SearchResultDTO$1>;
+}
+declare class RecentApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<RecentPageDTO$1>;
+}
+declare class ActivityApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ActivityPageDTO>;
+}
+declare class AuthApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
     me(): Promise<SessionInfo>;
     startTelegramLogin(phone: string): Promise<void>;
     verifyTelegramCode(phone: string, code: string): Promise<TelegramVerifyResponse>;
@@ -126,42 +511,96 @@ declare class OmniCloudClient {
         status: "ok";
         user: UserDTO;
     }>;
-    ensureStorage(): Promise<StorageDTO>;
     logout(): Promise<void>;
-    listFolders(parentId: string | null): Promise<FolderDTO[]>;
-    folderTree(): Promise<FolderDTO[]>;
-    createFolder(name: string, parentId?: string | null): Promise<FolderDTO>;
-    renameFolder(id: string, name: string): Promise<FolderDTO>;
-    moveFolder(id: string, parentId: string | null): Promise<FolderDTO>;
-    deleteFolder(id: string): Promise<DeleteFolderResultDTO>;
-    listFiles(folderId: string | null): Promise<FileDTO[]>;
-    getFile(id: string): Promise<FileDTO>;
-    renameFile(id: string, name: string): Promise<FileDTO>;
-    moveFile(id: string, folderId: string | null): Promise<FileDTO>;
-    deleteFile(id: string): Promise<void>;
-    /** URL of the download endpoint (usable as href for direct downloads). */
-    fileDownloadUrl(id: string): string;
-    /**
-     * Uploads a file. Uses XMLHttpRequest when available so `onProgress`
-     * works (browsers); falls back to fetch without progress in Node.
-     */
-    uploadFile(input: UploadInput, options?: UploadOptions): Promise<FileDTO>;
-    search(query: string): Promise<SearchResultDTO>;
-    private uploadViaXhr;
-    private request;
 }
 
+/** 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;
+    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 VALIDATION: "VALIDATION_ERROR";
-    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
-    readonly FORBIDDEN: "FORBIDDEN";
+    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 TELEGRAM_ERROR: "TELEGRAM_ERROR";
+    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];
@@ -176,10 +615,11 @@ declare class DomainError extends Error {
     readonly details?: unknown;
     constructor(code: ErrorCode, status: number, message: string, details?: unknown);
 }
-/** The underlying storage backend (e.g. Telegram) failed. */
-declare class StorageProviderError extends DomainError {
-    constructor(message: string, details?: unknown);
-}
+/**
+ * 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
@@ -189,6 +629,7 @@ declare class StorageProviderError extends DomainError {
  * 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;
@@ -216,6 +657,15 @@ interface FolderRecord {
     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;
 }
@@ -228,9 +678,83 @@ interface FileRecord {
     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;
+}
 
 /**
  * Repository interfaces. The application depends on these, not on a specific
@@ -263,42 +787,116 @@ interface StorageRepository {
         telegramAccessHash: string;
     }): Promise<StorageRecord>;
 }
+interface FolderCreateInput {
+    userId: string;
+    parentId: string | null;
+    name: string;
+}
 interface FolderRepository {
-    create(input: {
-        userId: string;
-        parentId: string | null;
-        name: string;
-    }): Promise<FolderRecord>;
+    create(input: FolderCreateInput): Promise<FolderRecord>;
     findById(id: string): Promise<FolderRecord | null>;
-    /** Every folder belonging to the user (used for trees and cascade deletes). */
+    /** 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>;
-    searchByName(userId: string, query: string, limit: number): Promise<FolderRecord[]>;
+    countByUser(userId: string): Promise<number>;
+}
+interface FileCreateInput {
+    userId: string;
+    folderId: string | null;
+    name: string;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
 }
 interface FileRepository {
-    create(input: {
-        userId: string;
-        folderId: string | null;
-        name: string;
-        size: number;
-        mimeType: string;
-        sha256: string;
-        telegramMessageId: number;
-    }): Promise<FileRecord>;
+    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>;
-    searchByName(userId: string, query: string, limit: number): Promise<FileRecord[]>;
+    createVersion(input: {
+        fileId: string;
+        userId: string;
+        size: number;
+        mimeType: string;
+        sha256: string;
+        telegramMessageId: number;
+    }): Promise<FileVersionRecord>;
+    listVersions(fileId: string): Promise<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;
@@ -306,11 +904,15 @@ interface Repos {
     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 {
@@ -321,21 +923,57 @@ interface StoredObject extends StoredRef {
     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. `data` is a Buffer; `stream` is used for large files. */
 interface StorageUploadInput {
     name: string;
     mimeType: string;
-    data: Buffer;
+    /** Whole-object buffer (small files). */
+    data?: Buffer;
+    /** Streaming source (large files). Either `data` or `stream` is required. */
+    stream?: Readable;
+    /** Total byte length, required when streaming. */
+    size?: number;
+}
+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 the object and returns the stored reference. */
-    put(input: StorageUploadInput): Promise<StoredObject>;
-    /** Downloads the object's content. */
-    get(ref: StoredRef): Promise<Buffer>;
+    /**
+     * 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>;
+    /** Validates that the backing store is reachable and usable. */
+    healthCheck(): Promise<StorageHealth>;
 }
 
 declare function sha256Hex(data: Uint8Array): string;
@@ -345,24 +983,82 @@ interface EngineUploadResult {
     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 and consistent error mapping.
+ * 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;
-    constructor(provider: StorageProvider);
+    private readonly retryPolicy;
+    constructor(provider: StorageProvider, retryPolicy?: EngineRetryPolicy);
     get providerName(): string;
-    /** Uploads an object and computes its checksum in one step. */
-    upload(input: StorageUploadInput): Promise<EngineUploadResult>;
-    download(ref: StoredRef): Promise<Buffer>;
+    /**
+     * 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, computing the checksum on the fly when requested. */
+    downloadStream(ref: StoredRef, control?: TransferControl): Promise<{
+        stream: Readable;
+        hash: () => string | null;
+    }>;
     remove(ref: StoredRef): Promise<void>;
+    exists(ref: StoredRef): Promise<boolean>;
+    stat(ref: StoredRef): Promise<StoredObject | null>;
+    health(): Promise<StorageHealth>;
     verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
+    /** Materializes an upload input so the checksum can be computed. */
+    private readInput;
+    private withRetry;
+}
+
+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>;
 }
-declare function mapProviderError(message: string, error: unknown): StorageProviderError;
+/** 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;
@@ -370,64 +1066,239 @@ interface FileDownload {
     integrityVerified: boolean;
 }
 type EngineResolver = (userId: string) => Promise<StorageEngine>;
+interface FileUploadInput {
+    folderId: string | null;
+    name: string;
+    data: Buffer;
+    /** When set, uploads a new version of this file instead of creating one. */
+    replaceFileId?: string;
+    /** Progress callback forwarded from the transport layer. */
+    onProgress?: (progress: TransferProgress) => void;
+    signal?: AbortSignal;
+}
 /**
- * All file metadata operations. Every method verifies ownership: records
+ * 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;
-    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver);
-    upload(userId: string, input: {
-        folderId: string | null;
-        name: string;
-        data: Buffer;
-    }): Promise<FileRecord>;
+    private readonly activity;
+    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver, activity?: ActivityRecorder);
+    upload(userId: string, input: FileUploadInput): Promise<FileRecord>;
+    /** 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>;
+    /**
+     * 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): Promise<FileDownload>;
+    download(userId: string, id: string, control?: TransferControl): Promise<FileDownload>;
+    /** 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;
+    }): Promise<{
+        requested: number;
+        succeeded: number;
+        failed: number;
+        errors: {
+            id: string;
+            message: string;
+        }[];
+    }>;
+    private assertFolder;
 }
 
-interface FolderDeletionResult {
-    deletedFolders: number;
-    deletedFiles: number;
+interface FolderMutationResult {
+    affectedFolders: number;
+    affectedFiles: number;
 }
 /**
- * Folder deletion semantics (v0.1): deleting a folder recursively deletes
- * all descendant folders and the files inside them, including the remote
- * storage objects. Files directly inside the deleted hierarchy are removed,
- * not relocated.
+ * 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;
-    constructor(folders: FolderRepository, files: FileRepository, engineFor: EngineResolver);
+    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>;
-    delete(userId: string, id: string): Promise<FolderDeletionResult>;
+    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;
 }
 
-/** Metadata-based search over file and folder names (PostgreSQL-backed). */
+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, query: string, limit?: number): Promise<{
-        files: FileRecord[];
-        folders: FolderRecord[];
-    }>;
+    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;
+}
+
+/**
+ * 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>;
 }
 
 /**
@@ -440,26 +1311,53 @@ interface TelegramCredentials {
     apiId: number;
     apiHash: string;
 }
+interface ConnectionStatus {
+    state: ConnectionState;
+    lastError: string | null;
+    lastCheckAt: Date | null;
+    healthy: boolean | null;
+}
 /**
- * Keeps one connected TelegramClient per authenticated user. Clients are
- * restored from the persisted MTProto session string and cached for the
- * lifetime of the process.
+ * 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 clients;
+    private connections;
+    private lastReconnectAt;
     constructor(credentials: TelegramCredentials, sessions: SessionRepository);
+    /** Returns a connected client, (re)connecting when needed. */
     getForUser(userId: string): Promise<TelegramClient>;
-    /** Registers an already-authenticated client (e.g. from the login flow). */
+    /** 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 connect;
+    private isConnected;
+    private connectUser;
+    private reconnect;
+    private establish;
 }
 
 /**
  * Maps a Telegram (GramJS) failure to a structured domain error with an
- * appropriate HTTP status and client-facing message.
+ * appropriate HTTP status and a client-facing message that never leaks
+ * credentials or session material.
  */
 declare function mapTelegramError(error: unknown, fallbackMessage: string): DomainError;
 
@@ -468,22 +1366,38 @@ interface TelegramStorageOptions {
     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.
+ * 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): Promise<StoredObject>;
-    get(ref: StoredRef): Promise<Buffer>;
+    put(input: StorageUploadInput, control?: TransferControl): Promise<StoredObject>;
+    get(ref: StoredRef, control?: TransferControl): Promise<Buffer>;
+    getStream(ref: StoredRef, control?: TransferControl): Promise<Readable>;
     delete(ref: StoredRef): Promise<void>;
     exists(ref: StoredRef): Promise<boolean>;
     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 materialize;
+    private documentSize;
+    private requireMessage;
     private getMessage;
 }
 
@@ -525,4 +1439,4 @@ declare class TelegramConnectionService {
     private disconnectQuietly;
 }
 
-export { type ApiErrorBody, type DeleteFolderResultDTO, DomainError, ERROR_CODES$1 as ERROR_CODES, type EngineUploadResult, type ErrorCode$1 as ErrorCode, type FileCategory, type FileDTO, type FileDownload, type FileRecord, FileService, type FolderDTO, type FolderDeletionResult, type FolderRecord, FolderService, OmniCloudClient, type OmniCloudClientOptions, OmniCloudError, type Repos, type SearchResultDTO, SearchService, type SessionInfo, type StorageDTO, StorageEngine, type StorageProvider, type StorageRecord, type StorageUploadInput, type StoredObject, type StoredRef, TELEGRAM_PROVIDER, TelegramClientManager, TelegramConnectionService, type TelegramCredentials, type TelegramStorageOptions, TelegramStorageProvider, type TelegramVerifyResponse, type UploadInput, type UploadOptions, type UploadProgress, type UserDTO, type UserRecord, fileCategory, mapProviderError, mapTelegramError, mimeFromFilename, sanitizeFileName, sha256Hex };
+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, 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 };