@lacrous/omnicloud 0.2.1 → 0.2.2

package/dist/index.d.cts

@@ -242,6 +242,8 @@ interface HealthDTO {
 }
 interface IntegrityIssueDTO$1 {
     fileId: string;
+    /** Set when the issue is with a historical version rather than the current object. */
+    versionId?: string;
     name: string;
     kind: "missing" | "size_mismatch" | "unreadable" | "hash_mismatch";
     detail: string | null;
@@ -341,8 +343,14 @@ interface UploadOptions {
     retry?: number;
 }
 interface UploadInput {
-    /** File content: Blob/File in the browser, Buffer/Uint8Array in Node. */
-    data: Blob | Uint8Array;
+    /**
+     * File content: a Blob/File, a Uint8Array/Buffer, a web ReadableStream, or (in
+     * Node) a Readable stream. Streams are read in chunks; the caller never has to
+     * build one large buffer.
+     */
+    data?: Blob | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+    /** Node only: a path to read the file from. Use instead of `data`. */
+    path?: string;
     /** Filename; also used to derive the MIME type server-side. */
     name: string;
 }
@@ -351,6 +359,13 @@ interface DownloadProgress {
     total: number | null;
     percent: number | null;
 }
+interface StreamedDownload {
+    stream: ReadableStream<Uint8Array>;
+    contentType: string;
+    /** Declared byte length, or null when the server did not send one. */
+    size: number | null;
+    sha256: string | null;
+}
 interface DownloadResult {
     data: Buffer | Uint8Array;
     contentType: string;
@@ -393,6 +408,12 @@ declare class OmniCloudClient {
     /** @internal */
     withRetry<T>(operation: () => Promise<T>): Promise<T>;
     /** @internal */
+    /**
+     * Opens a binary response as a stream. Bytes are delivered as they arrive, so
+     * memory does not grow with the file. The stream errors with DOWNLOAD_INCOMPLETE
+     * if the body ends before Content-Length.
+     */
+    requestStream(path: string, onProgress?: (p: DownloadProgress) => void): Promise<StreamedDownload>;
     requestBinary(path: string, onProgress?: (p: DownloadProgress) => void): Promise<DownloadResult>;
 }
 declare class FilesApi {
@@ -413,6 +434,22 @@ declare class FilesApi {
     /** 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>;
+    /**
+     * Streams a file's bytes without holding the whole file in memory. Use this for
+     * large files. Read `stream` to the end: a truncated transfer errors instead of
+     * ending quietly.
+     */
+    downloadStream(id: string, onProgress?: (p: DownloadProgress) => void): Promise<StreamedDownload>;
+    /**
+     * Node only. Streams a file to `targetPath` through a `.part` file that is
+     * renamed into place only after the full length is verified. A truncated or
+     * failed transfer leaves nothing at `targetPath`.
+     */
+    downloadToFile(id: string, targetPath: string, onProgress?: (p: DownloadProgress) => void): Promise<{
+        path: string;
+        bytes: number;
+        sha256: string | null;
+    }>;
     /** URL suitable for direct download (anchor href). */
     downloadUrl(id: string): string;
     rename(id: string, name: string): Promise<FileDTO$1>;
@@ -567,6 +604,8 @@ declare const RESOURCE_TYPES: readonly ["file", "folder", "storage"];
 type ResourceType = (typeof RESOURCE_TYPES)[number];
 interface IntegrityIssueDTO {
     fileId: string;
+    /** Set when the issue is with a historical version rather than the current object. */
+    versionId?: string;
     name: string;
     kind: "missing" | "size_mismatch" | "unreadable" | "hash_mismatch";
     detail: string | null;
@@ -613,7 +652,14 @@ declare class DomainError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
     readonly details?: unknown;
-    constructor(code: ErrorCode, status: number, message: string, details?: unknown);
+    /** Whether repeating the same operation may succeed. Defaults to false. */
+    readonly retryable: boolean;
+    /** Server-requested delay before a retry, in seconds, when the provider gave one. */
+    readonly retryAfterSeconds?: number;
+    constructor(code: ErrorCode, status: number, message: string, details?: unknown, retry?: {
+        retryable?: boolean;
+        retryAfterSeconds?: number;
+    });
 }
 /**
  * Wraps an arbitrary provider failure as an UploadFailedError (the default
@@ -756,6 +802,19 @@ interface StorageStats {
     quotaBytes: number | null;
 }
 
+/**
+ * Upload operations are the durable record of one logical upload. They exist so
+ * that a retried request (same operation id) can resume or replay instead of
+ * writing a second Telegram object and a second file record.
+ *
+ * PENDING    accepted, Telegram write not started
+ * UPLOADING  Telegram write in progress or its outcome unknown
+ * COMPLETED  Telegram object stored and file record committed; result is final
+ * FAILED     Telegram write definitively failed; the operation may be retried
+ *            under a new id
+ */
+type UploadOperationStatus = "PENDING" | "UPLOADING" | "COMPLETED" | "FAILED";
+
 /**
  * Repository interfaces. The application depends on these, not on a specific
  * database — the Prisma implementation lives in @omnicloud/database, and
@@ -777,6 +836,33 @@ interface SessionRepository {
     save(userId: string, stringSession: string): Promise<void>;
     delete(userId: string): Promise<void>;
 }
+interface BrowserSessionRecord {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    createdAt: Date;
+    expiresAt: Date;
+    revokedAt: Date | null;
+    lastUsedAt: Date | null;
+    userAgent: string | null;
+    ip: string | null;
+}
+/** Server-side browser sessions. Holds only token hashes, never raw tokens. */
+interface BrowserSessionRepository {
+    create(input: {
+        userId: string;
+        tokenHash: string;
+        expiresAt: Date;
+        userAgent: string | null;
+        ip: string | null;
+    }): Promise<BrowserSessionRecord>;
+    findByTokenHash(tokenHash: string): Promise<BrowserSessionRecord | null>;
+    touch(id: string, at: Date): Promise<void>;
+    revoke(id: string, at: Date): Promise<void>;
+    revokeAllForUser(userId: string, at: Date): Promise<number>;
+    listActiveForUser(userId: string, now: Date): Promise<BrowserSessionRecord[]>;
+    deleteExpiredBefore(cutoff: Date): Promise<number>;
+}
 interface StorageRepository {
     findByUserAndProvider(userId: string, provider: string): Promise<StorageRecord | null>;
     create(input: {
@@ -794,6 +880,12 @@ interface FolderCreateInput {
 }
 interface FolderRepository {
     create(input: FolderCreateInput): Promise<FolderRecord>;
+    /**
+     * Re-parents a folder only if the result stays acyclic. The ancestor check and
+     * the write are one atomic step, so two concurrent moves cannot each pass the
+     * check and together create a cycle. Throws ConflictError on a cycle.
+     */
+    moveSafely(id: string, newParentId: string | null): Promise<FolderRecord>;
     findById(id: string): Promise<FolderRecord | null>;
     /** Every folder belonging to the user (used for trees and cascade logic). */
     listByUser(userId: string): Promise<FolderRecord[]>;
@@ -827,6 +919,37 @@ interface FileCreateInput {
     sha256: string;
     telegramMessageId: number;
 }
+interface UploadOperationRecord {
+    id: string;
+    userId: string;
+    operationId: string;
+    status: UploadOperationStatus;
+    /** Set once the Telegram object exists, so recovery can commit without re-uploading. */
+    telegramMessageId: number | null;
+    sha256: string | null;
+    size: number | null;
+    fileId: string | null;
+    error: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Durable upload attempts, scoped to the owning user. */
+interface UploadOperationRepository {
+    findByOperationId(userId: string, operationId: string): Promise<UploadOperationRecord | null>;
+    /** Operations for a user in the given states (used by reconciliation). */
+    listByStatus(userId: string, status: UploadOperationStatus): Promise<UploadOperationRecord[]>;
+    create(input: {
+        userId: string;
+        operationId: string;
+    }): Promise<UploadOperationRecord>;
+    /**
+     * Atomically moves an operation from `from` to `to` if, and only if, it is
+     * still in `from`. Returns false when another request already moved it, so
+     * exactly one request performs the upload.
+     */
+    claim(id: string, from: UploadOperationStatus, to: UploadOperationStatus): Promise<boolean>;
+    update(id: string, patch: Partial<Pick<UploadOperationRecord, "status" | "telegramMessageId" | "sha256" | "size" | "fileId" | "error">>): Promise<UploadOperationRecord>;
+}
 interface FileRepository {
     create(input: FileCreateInput): Promise<FileRecord>;
     findById(id: string): Promise<FileRecord | null>;
@@ -873,6 +996,8 @@ interface FileRepository {
         telegramMessageId: number;
     }): Promise<FileVersionRecord>;
     listVersions(fileId: string): Promise<FileVersionRecord[]>;
+    /** All versions for many files in one query, grouped by file id. */
+    listVersionsForFiles(fileIds: string[]): Promise<Map<string, FileVersionRecord[]>>;
     findVersionById(versionId: string): Promise<FileVersionRecord | null>;
     countVersions(fileId: string): Promise<number>;
     deleteVersionsByFileIds(fileIds: string[]): Promise<void>;
@@ -901,6 +1026,8 @@ interface ActivityRepository {
 interface Repos {
     users: UserRepository;
     sessions: SessionRepository;
+    browserSessions: BrowserSessionRepository;
+    uploadOperations: UploadOperationRepository;
     storages: StorageRepository;
     folders: FolderRepository;
     files: FileRepository;
@@ -937,16 +1064,21 @@ interface TransferControl {
     signal?: AbortSignal;
     onProgress?: (progress: TransferProgress) => void;
 }
-/** Upload input. `data` is a Buffer; `stream` is used for large files. */
+/**
+ * Upload input. Exactly one of `data` (small, in memory) or `path` (a spooled
+ * file on disk, read in slices by the provider) must be given.
+ */
 interface StorageUploadInput {
     name: string;
     mimeType: string;
     /** Whole-object buffer (small files). */
     data?: Buffer;
-    /** Streaming source (large files). Either `data` or `stream` is required. */
-    stream?: Readable;
-    /** Total byte length, required when streaming. */
+    /** Path to a spooled file (large files). Its bytes are never fully loaded. */
+    path?: string;
+    /** Total byte length of the object. Required with `path`. */
     size?: number;
+    /** SHA-256 of the spooled bytes, computed while they were written. Required with `path`. */
+    sha256?: string;
 }
 interface StorageHealth {
     /** Reachable and usable. */
@@ -972,6 +1104,12 @@ interface StorageProvider {
     delete(ref: StoredRef): Promise<void>;
     exists(ref: StoredRef): Promise<boolean>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
+    /**
+     * Lists the objects the backing store holds, newest first, read-only. Used by
+     * reconciliation; it must never modify anything. Implementations page through
+     * the store and stop once `limit` objects are returned.
+     */
+    listObjects(limit: number): Promise<StoredObject[]>;
     /** Validates that the backing store is reachable and usable. */
     healthCheck(): Promise<StorageHealth>;
 }
@@ -1008,21 +1146,30 @@ declare class StorageEngine {
      */
     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;
-    }>;
+    /**
+     * Streams the object and verifies its SHA-256 against `expectedSha256`.
+     *
+     * The last chunk is held back until the digest of everything before it has
+     * been checked, so a corrupt object errors the stream before its final bytes
+     * are released. A consumer therefore never sees a complete-looking body that
+     * fails the checksum. Memory stays bounded to about two provider chunks.
+     */
+    downloadStream(ref: StoredRef, expectedSha256: string, control?: TransferControl): Promise<Readable>;
     remove(ref: StoredRef): Promise<void>;
     exists(ref: StoredRef): Promise<boolean>;
+    /** Read-only listing of stored objects, for reconciliation. Never modifies anything. */
+    list(limit: number): Promise<StoredObject[]>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     health(): Promise<StorageHealth>;
     verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
-    /** Materializes an upload input so the checksum can be computed. */
-    private readInput;
     private withRetry;
 }
 
+interface OperationSink {
+    info(record: Record<string, unknown>, message: string): void;
+    warn(record: Record<string, unknown>, message: string): void;
+}
+
 interface RecordActivityInput {
     userId: string;
     action: ActivityAction;
@@ -1065,13 +1212,27 @@ interface FileDownload {
     data: Buffer;
     integrityVerified: boolean;
 }
+interface FileStreamDownload {
+    record: FileRecord;
+    /** Errors with IntegrityCheckError instead of ending if the bytes do not match. */
+    stream: Readable;
+}
 type EngineResolver = (userId: string) => Promise<StorageEngine>;
 interface FileUploadInput {
     folderId: string | null;
     name: string;
-    data: Buffer;
+    /** In-memory content. Use `spooled` for anything large. */
+    data?: Buffer;
+    /** A file already written to disk by `spoolToFile`, with its checksum. */
+    spooled?: {
+        path: string;
+        size: number;
+        sha256: string;
+    };
     /** When set, uploads a new version of this file instead of creating one. */
     replaceFileId?: string;
+    /** Client-supplied id that makes the upload idempotent across retries. */
+    operationId?: string;
     /** Progress callback forwarded from the transport layer. */
     onProgress?: (progress: TransferProgress) => void;
     signal?: AbortSignal;
@@ -1090,8 +1251,28 @@ declare class FileService {
     private readonly folders;
     private readonly engineFor;
     private readonly activity;
-    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver, activity?: ActivityRecorder);
+    private readonly operations;
+    private readonly log;
+    constructor(files: FileRepository, folders: FolderRepository, engineFor: EngineResolver, activity?: ActivityRecorder, operations?: UploadOperationRepository | null, log?: OperationSink | null);
     upload(userId: string, input: FileUploadInput): Promise<FileRecord>;
+    /**
+     * Idempotent upload keyed by a client-supplied operation id. A retry never
+     * writes a second Telegram object: a completed operation returns its file, and
+     * an operation whose object was already stored is committed without uploading.
+     */
+    private uploadOnce;
+    /**
+     * Follows an operation another request is driving, for a bounded time. Returns
+     * the finished file if the winner completes, or the stored object's commit if
+     * it has stored one. Returns null when the winner is still in progress after the
+     * budget, so the caller can report a conflict instead of waiting forever.
+     */
+    private followWinner;
+    /** Commits metadata for an object that is already in Telegram. */
+    private commitStoredObject;
+    private performUpload;
+    /** Persists the file (or the new version of a file) for an object already stored. */
+    private commitRecord;
     /** Uploads a new version of an existing file and makes it current. */
     private replaceVersion;
     list(userId: string, folderId: string | null): Promise<FileRecord[]>;
@@ -1116,12 +1297,20 @@ declare class FileService {
      * retry, rather than silently orphaning the storage object.
      */
     deletePermanently(userId: string, id: string): Promise<void>;
+    private performPermanentDelete;
     /**
      * v0.1-compatible hard delete used by the current API: permanently removes
      * the file. Retained so existing clients keep working.
      */
     delete(userId: string, id: string): Promise<void>;
     download(userId: string, id: string, control?: TransferControl): Promise<FileDownload>;
+    /**
+     * Streaming download for large files. The caller must consume `stream` to
+     * the end and then await `verified` to learn whether the bytes match the
+     * stored checksum. The download activity is recorded when the stream opens.
+     */
+    downloadStreamed(userId: string, id: string, control?: TransferControl): Promise<FileStreamDownload>;
+    private performStreamedDownload;
     /** Records an "open" event (the UI opening the details panel, say). */
     touch(userId: string, id: string, action?: "open"): Promise<void>;
     /**
@@ -1130,7 +1319,9 @@ declare class FileService {
      */
     batch(userId: string, ids: string[], operation: "trash" | "restore" | "delete" | "star" | "unstar" | "move", options?: {
         folderId?: string | null;
+        operationId?: string;
     }): Promise<{
+        operationId?: string;
         requested: number;
         succeeded: number;
         failed: number;
@@ -1287,6 +1478,7 @@ declare class IntegrityService {
     constructor(files: FileRepository, engineFor: EngineResolver);
     check(userId: string, options?: IntegrityCheckOptions): Promise<IntegrityReportDTO>;
     private inspect;
+    private inspectObject;
 }
 
 /**
@@ -1385,9 +1577,20 @@ declare class TelegramStorageProvider implements StorageProvider {
     constructor(client: TelegramClient, options: TelegramStorageOptions);
     put(input: StorageUploadInput, control?: TransferControl): Promise<StoredObject>;
     get(ref: StoredRef, control?: TransferControl): Promise<Buffer>;
+    /**
+     * Streams the object in Telegram-sized chunks, so memory use stays bounded
+     * by one chunk regardless of file size. The first request happens here so
+     * that a missing message fails before the caller starts consuming bytes.
+     */
     getStream(ref: StoredRef, control?: TransferControl): Promise<Readable>;
     delete(ref: StoredRef): Promise<void>;
     exists(ref: StoredRef): Promise<boolean>;
+    /**
+     * Read-only listing of stored documents in the channel, newest first, up to
+     * `limit`. Only messages that carry a document are returned; text messages and
+     * service messages are skipped. Nothing is modified.
+     */
+    listObjects(limit: number): Promise<StoredObject[]>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     /**
      * Validates that the client is connected and the storage channel is
@@ -1395,7 +1598,6 @@ declare class TelegramStorageProvider implements StorageProvider {
      */
     healthCheck(): Promise<StorageHealth>;
     private throwIfAborted;
-    private materialize;
     private documentSize;
     private requireMessage;
     private getMessage;
@@ -1439,4 +1641,4 @@ declare class TelegramConnectionService {
     private disconnectQuietly;
 }
 
-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 };
+export { type ActivityEventDTO, type ActivityEventRecord, type ActivityPageDTO, type ActivityRecorder, ActivityService, type ApiErrorBody, type BatchResultDTO, type ConnectionState, type ConnectionStatus, DomainError, type DownloadProgress, type DownloadResult, ERROR_CODES$1 as ERROR_CODES, type EmptyTrashResultDTO, type EngineResolver, type EngineRetryPolicy, type EngineUploadResult, type ErrorCode$1 as ErrorCode, type FileCategory, type FileDTO$1 as FileDTO, type FileDownload, type FileRecord, FileService, type FileTypeBucket, type FileVersionDTO, type FileVersionRecord, type FilesPageDTO, type FolderDTO$1 as FolderDTO, type FolderMutationResult, type FolderMutationResultDTO, type FolderRecord, FolderService, type FoldersPageDTO, type HealthDTO, type HealthStatus, type IntegrityCheckOptions, type IntegrityIssueDTO$1 as IntegrityIssueDTO, type IntegrityReportDTO$1 as IntegrityReportDTO, IntegrityService, type ItemQuery, type ItemStatus, type ListQuery, OmniCloudClient, type OmniCloudClientOptions, OmniCloudError, type PageRequest, type Paged, type PaginationDTO$1 as PaginationDTO, type RecentItemDTO$1 as RecentItemDTO, type RecentPageDTO$1 as RecentPageDTO, RecentService, type Repos, type RetryOptions, type SearchResultDTO$1 as SearchResultDTO, SearchService, type SessionInfo, type SortField, type SortOrder, StatsService, type StorageDTO, StorageEngine, type StorageHealth, type StorageHealthDTO, type StorageProvider, type StorageRecord, type StorageStats, type StorageStatsDTO, type StorageTypeBreakdownDTO, type StorageUploadInput, type StoredObject, type StoredRef, type StreamedDownload, TELEGRAM_PROVIDER, TelegramClientManager, TelegramConnectionService, type TelegramCredentials, type TelegramStorageOptions, TelegramStorageProvider, type TelegramVerifyResponse, type TransferControl, type TransferProgress, type TrashPageDTO, TrashService, type UploadInput, type UploadOptions, type UploadProgress, type UserDTO, type UserRecord, fileCategory, isFileCategory, mapProviderError, mapTelegramError, mimeFromFilename, mimeMatchersForType, noopActivityRecorder, paginationMeta, parseSearchQuery, parseSize, sanitizeFileName, sha256Hex };