@lacrous/omnicloud 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,528 @@
+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;
+
+/**
+ * Data transfer objects and constants 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.
+ */
+interface UserDTO {
+    id: string;
+    username: string | null;
+    firstName: string | null;
+    lastName: string | null;
+}
+interface StorageDTO {
+    id: string;
+    provider: string;
+    title: string;
+    createdAt: string;
+}
+/** Returned by GET /api/auth/me. `user` is null when not signed in. */
+interface SessionInfo {
+    user: UserDTO | null;
+    storage: StorageDTO | null;
+}
+interface FileDTO {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    sha256: string;
+    folderId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FolderDTO {
+    id: string;
+    name: string;
+    parentId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SearchResultDTO {
+    files: FileDTO[];
+    folders: FolderDTO[];
+}
+interface DeleteFolderResultDTO {
+    deletedFolders: number;
+    deletedFiles: number;
+}
+/** 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 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$1 = (typeof ERROR_CODES$1)[keyof typeof ERROR_CODES$1];
+interface ApiErrorBody {
+    error: {
+        code: ErrorCode$1;
+        message: string;
+        details?: unknown;
+    };
+}
+
+declare class OmniCloudError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+interface OmniCloudClientOptions {
+    /** Base URL of an OmniCloud server. Defaults to same-origin ("" is kept as-is). */
+    baseUrl?: string;
+    /** Custom fetch implementation (e.g. for tests). */
+    fetchImpl?: typeof fetch;
+}
+interface UploadProgress {
+    loaded: number;
+    total: number;
+    percent: number;
+}
+interface UploadOptions {
+    folderId?: string | null;
+    onProgress?: (progress: UploadProgress) => void;
+}
+interface UploadInput {
+    /** File content: a File/Blob in the browser, or a Buffer/Uint8Array in Node. */
+    data: Blob | Uint8Array;
+    name: string;
+}
+/**
+ * HTTP client for an OmniCloud server.
+ *
+ * Works in browsers (cookie sessions, upload progress via XHR) and Node.js
+ * (fetch fallback, cookie forwarding is the caller's responsibility).
+ */
+declare class OmniCloudClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    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;
+    /**
+     * 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;
+}
+
+/** 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;
+        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;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+
+/** 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[];
+    }>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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 {
+    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;
+}
+
+declare const TELEGRAM_PROVIDER = "telegram";
+type VerifyCodeResult = {
+    status: "ok";
+    user: UserRecord;
+} | {
+    status: "password_required";
+};
+/**
+ * Orchestrates the full Telegram account connection flow:
+ * phone → code (→ 2FA password) → session persisted → user upserted →
+ * private storage channel created.
+ */
+declare class TelegramConnectionService {
+    private readonly repos;
+    private readonly clientManager;
+    private readonly credentials;
+    private flows;
+    constructor(repos: Repos, clientManager: TelegramClientManager, credentials: TelegramCredentials);
+    /** Sends the Telegram confirmation code for the phone number. */
+    startLogin(phone: string): Promise<void>;
+    /** Verifies the confirmation code. Returns `password_required` for 2FA accounts. */
+    verifyCode(phone: string, code: string): Promise<VerifyCodeResult>;
+    /** Completes sign-in for accounts with two-factor authentication enabled. */
+    verifyPassword(phone: string, password: string): Promise<VerifyCodeResult>;
+    /** Aborts a pending login flow (disconnects the client). */
+    cancelLogin(phone: string): Promise<void>;
+    /**
+     * Ensures the user has a registered private storage channel, creating it
+     * on first use. Idempotent.
+     */
+    ensureStorage(userId: string): Promise<StorageRecord>;
+    ensureStorageForClient(userId: string, client: TelegramClient): Promise<StorageRecord>;
+    private requireFlow;
+    private finalizeLogin;
+    private sweepExpiredFlows;
+    private disconnectQuietly;
+}
+
+export { type 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 };