@lacrous/omnicloud 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,14 +1,12 @@
-import { TelegramClient } from 'telegram';
-
-/** 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;
+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';
 
 /**
- * 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,11 +23,31 @@ 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;
 }
+/** POST /api/auth/telegram/verify response. */
+type TelegramVerifyResponse = {
+    status: "ok";
+    user: UserDTO;
+} | {
+    status: "password_required";
+};
 interface FileDTO {
     id: string;
     name: string;
@@ -37,6 +55,11 @@ interface FileDTO {
     mimeType: string;
     sha256: string;
     folderId: string | null;
+    starred: boolean;
+    trashed: boolean;
+    deletedAt: string | null;
+    versionCount: number;
+    currentVersionId: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -44,56 +67,193 @@ interface FolderDTO {
     id: string;
     name: string;
     parentId: string | null;
+    starred: boolean;
+    trashed: boolean;
+    deletedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }
+interface FileVersionDTO {
+    id: string;
+    fileId: string;
+    versionNumber: number;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    telegramMessageId: number;
+    isCurrent: boolean;
+    createdAt: string;
+}
 interface SearchResultDTO {
     files: FileDTO[];
     folders: FolderDTO[];
+    pagination: PaginationDTO;
 }
-interface DeleteFolderResultDTO {
-    deletedFolders: number;
+/** Result of a recursive folder deletion / trash operation. */
+interface FolderMutationResultDTO {
+    affectedFolders: number;
+    affectedFiles: number;
+}
+interface EmptyTrashResultDTO {
     deletedFiles: number;
+    deletedFolders: number;
+    failedFiles: number;
+}
+
+interface PaginationDTO {
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+}
+interface FilesPageDTO {
+    files: FileDTO[];
+    pagination: PaginationDTO;
+}
+interface FoldersPageDTO {
+    folders: FolderDTO[];
+    pagination: PaginationDTO;
+}
+interface TrashPageDTO {
+    files: FileDTO[];
+    folders: FolderDTO[];
+    pagination: PaginationDTO;
+}
+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 ActivityEventDTO {
+    id: string;
+    action: ActivityAction;
+    resourceType: ResourceType;
+    resourceId: string;
+    resourceName: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ActivityPageDTO {
+    events: ActivityEventDTO[];
+    pagination: PaginationDTO;
+}
+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[];
+    quotaBytes: number | null;
+}
+interface HealthDTO {
+    status: HealthStatus;
+    database: HealthStatus;
+    storage: HealthStatus;
+    uptimeSeconds: number;
+    version: string;
+}
+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;
+}
+interface BatchResultDTO {
+    requested: number;
+    succeeded: number;
+    failed: number;
+    errors: {
+        id: string;
+        code: ErrorCode;
+        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";
+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 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];
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
 interface ApiErrorBody {
     error: {
-        code: ErrorCode$1;
+        code: ErrorCode;
         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,426 +263,186 @@ 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
  *
- * Works in browsers (cookie sessions, upload progress via XHR) and Node.js
- * (fetch fallback, cookie forwarding is the caller's responsibility).
+ *   cloud.files.list({ folderId })
+ *   cloud.trash.empty()
+ *   cloud.storage.stats()
+ *
+ * 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);
-    me(): Promise<SessionInfo>;
-    startTelegramLogin(phone: string): Promise<void>;
-    verifyTelegramCode(phone: string, code: string): Promise<TelegramVerifyResponse>;
-    submitTelegramPassword(phone: string, password: string): Promise<{
-        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;
+    /** 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>;
+    versions(id: string): Promise<FileVersionDTO[]>;
     /**
-     * Uploads a file. Uses XMLHttpRequest when available so `onProgress`
-     * works (browsers); falls back to fetch without progress in Node.
+     * Uploads a file with progress and retry support. Uses XMLHttpRequest when
+     * available (browsers) so progress and cancellation work; falls back to
+     * fetch elsewhere.
      */
-    uploadFile(input: UploadInput, options?: UploadOptions): Promise<FileDTO>;
-    search(query: string): Promise<SearchResultDTO>;
+    upload(input: UploadInput, options?: UploadOptions): Promise<FileDTO>;
+    private uploadOnce;
     private uploadViaXhr;
-    private request;
-}
-
-/** 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 NOT_FOUND: "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 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;
-    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);
-}
-
-/**
- * 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;
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface FileRecord {
-    id: string;
-    userId: string;
-    folderId: string | null;
-    name: string;
-    size: number;
-    mimeType: string;
-    sha256: string;
-    telegramMessageId: number;
-    createdAt: Date;
-    updatedAt: Date;
-}
-
-/**
- * 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 StorageRepository {
-    findByUserAndProvider(userId: string, provider: string): Promise<StorageRecord | null>;
-    create(input: {
-        userId: string;
-        provider: string;
-        title: string;
-        telegramChatId: string;
-        telegramAccessHash: string;
-    }): Promise<StorageRecord>;
-}
-interface FolderRepository {
-    create(input: {
-        userId: string;
-        parentId: string | null;
-        name: string;
-    }): Promise<FolderRecord>;
-    findById(id: string): Promise<FolderRecord | null>;
-    /** Every folder belonging to the user (used for trees and cascade deletes). */
-    listByUser(userId: string): Promise<FolderRecord[]>;
-    listChildren(userId: string, parentId: string | null): Promise<FolderRecord[]>;
-    update(id: string, patch: {
-        name?: string;
-        parentId?: string | null;
-    }): Promise<FolderRecord>;
-    deleteMany(ids: string[]): Promise<void>;
-    searchByName(userId: string, query: string, limit: number): Promise<FolderRecord[]>;
-}
-interface FileRepository {
-    create(input: {
-        userId: string;
-        folderId: string | null;
-        name: string;
-        size: number;
-        mimeType: string;
-        sha256: string;
-        telegramMessageId: number;
-    }): Promise<FileRecord>;
-    findById(id: string): Promise<FileRecord | null>;
-    listByFolder(userId: string, folderId: string | null): Promise<FileRecord[]>;
-    listByUser(userId: string): Promise<FileRecord[]>;
-    update(id: string, patch: {
-        name?: string;
+    /** Uploads a new version of an existing file. */
+    replace(id: string, input: UploadInput): Promise<FileDTO>;
+    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>;
+    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>;
+    /** 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<FileRecord>;
-    deleteMany(ids: string[]): Promise<void>;
-    searchByName(userId: string, query: string, limit: number): Promise<FileRecord[]>;
-}
-interface Repos {
-    users: UserRepository;
-    sessions: SessionRepository;
-    storages: StorageRepository;
-    folders: FolderRepository;
-    files: FileRepository;
+    }): Promise<BatchResultDTO>;
 }
-
-/**
- * Generic storage abstraction. The application must never depend on
- * Telegram-specific details — it talks to a StorageProvider.
- */
-/** 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;
-}
-interface StorageUploadInput {
-    name: string;
-    mimeType: string;
-    data: Buffer;
-}
-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>;
-    /** 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>;
-}
-
-declare function sha256Hex(data: Uint8Array): string;
-
-interface EngineUploadResult {
-    stored: StoredObject;
-    sha256: string;
-    size: number;
-}
-/**
- * Sits between the application and the raw StorageProvider and adds the
- * cross-cutting guarantees: SHA-256 integrity and consistent error mapping.
- *
- * 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);
-    get providerName(): string;
-    /** Uploads an object and computes its checksum in one step. */
-    upload(input: StorageUploadInput): Promise<EngineUploadResult>;
-    download(ref: StoredRef): Promise<Buffer>;
-    remove(ref: StoredRef): Promise<void>;
-    verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
-}
-declare function mapProviderError(message: string, error: unknown): StorageProviderError;
-
-interface FileDownload {
-    record: FileRecord;
-    data: Buffer;
-    integrityVerified: boolean;
-}
-type EngineResolver = (userId: string) => Promise<StorageEngine>;
-/**
- * All file metadata operations. Every method verifies ownership: records
- * belonging to other users are reported as missing.
- */
-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>;
-    list(userId: string, folderId: string | null): Promise<FileRecord[]>;
-    get(userId: string, id: string): Promise<FileRecord>;
-    rename(userId: string, id: string, name: string): Promise<FileRecord>;
-    move(userId: string, id: string, folderId: string | null): Promise<FileRecord>;
-    delete(userId: string, id: string): Promise<void>;
-    download(userId: string, id: string): Promise<FileDownload>;
-}
-
-interface FolderDeletionResult {
-    deletedFolders: number;
-    deletedFiles: number;
+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[]>;
+    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>;
+    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>;
 }
-/**
- * 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.
- */
-declare class FolderService {
-    private readonly folders;
-    private readonly files;
-    private readonly engineFor;
-    constructor(folders: FolderRepository, files: FileRepository, engineFor: EngineResolver);
-    create(userId: string, input: {
-        name: string;
-        parentId: string | null;
-    }): Promise<FolderRecord>;
-    listChildren(userId: string, parentId: string | null): Promise<FolderRecord[]>;
-    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>;
+declare class TrashApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(query?: ListQuery): Promise<TrashPageDTO>;
+    /** Permanently removes everything in the Trash. */
+    empty(): Promise<EmptyTrashResultDTO>;
 }
-
-/** Metadata-based search over file and folder names (PostgreSQL-backed). */
-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[];
+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>;
+    /** 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>;
 }
-
-/**
- * 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;
-}
-/**
- * Keeps one connected TelegramClient per authenticated user. Clients are
- * restored from the persisted MTProto session string and cached for the
- * lifetime of the process.
- */
-declare class TelegramClientManager {
-    private readonly credentials;
-    private readonly sessions;
-    private clients;
-    constructor(credentials: TelegramCredentials, sessions: SessionRepository);
-    getForUser(userId: string): Promise<TelegramClient>;
-    /** Registers an already-authenticated client (e.g. from the login flow). */
-    cacheClient(userId: string, client: TelegramClient): void;
-    disconnectAll(): Promise<void>;
-    private connect;
+declare class RecentApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<RecentPageDTO>;
 }
-
-/**
- * Maps a Telegram (GramJS) failure to a structured domain error with an
- * appropriate HTTP status and client-facing message.
- */
-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;
+declare class ActivityApi {
+    private readonly client;
+    constructor(client: OmniCloudClient);
+    list(page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ActivityPageDTO>;
 }
-/**
- * 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.
- */
-declare class TelegramStorageProvider implements StorageProvider {
+declare class AuthApi {
     private readonly client;
-    readonly name = "telegram";
-    private readonly peer;
-    constructor(client: TelegramClient, options: TelegramStorageOptions);
-    put(input: StorageUploadInput): Promise<StoredObject>;
-    get(ref: StoredRef): Promise<Buffer>;
-    delete(ref: StoredRef): Promise<void>;
-    exists(ref: StoredRef): Promise<boolean>;
-    stat(ref: StoredRef): Promise<StoredObject | null>;
-    private getMessage;
+    constructor(client: OmniCloudClient);
+    me(): Promise<SessionInfo>;
+    startTelegramLogin(phone: string): Promise<void>;
+    verifyTelegramCode(phone: string, code: string): Promise<TelegramVerifyResponse>;
+    submitTelegramPassword(phone: string, password: string): Promise<{
+        status: "ok";
+        user: UserDTO;
+    }>;
+    logout(): Promise<void>;
 }
 
-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;
-}
+/** Connection state of the underlying storage backend. */
+type ConnectionState = "DISCONNECTED" | "CONNECTING" | "CONNECTED" | "RECONNECTING" | "ERROR" | "AUTH_REQUIRED";
 
-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 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 };