@mountra/mountra-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+type ChunkMethod = "none" | "fix";
+type WorkspaceId = number | string;
+declare const JUMBO_CHUNK_THRESHOLD_BYTES: number;
+declare const MIN_S3_MULTIPART_PART_SIZE_BYTES: number;
+declare const DEFAULT_S3_MULTIPART_PART_SIZE_BYTES: number;
+declare const MAX_S3_MULTIPART_PARTS = 10000;
+interface WorkspaceSelector {
+    workspaceCuid?: string;
+    workspaceId?: WorkspaceId;
+}
+type AccessToken = string | null | undefined | (() => string | null | undefined | Promise<string | null | undefined>);
+interface MountraClientOptions extends WorkspaceSelector {
+    /** Mountra server origin, for example `https://mountra.example.com`. */
+    baseUrl: string;
+    /** API prefix. Set to an empty string when `baseUrl` already includes `/api`. */
+    apiPrefix?: string;
+    token?: AccessToken;
+    /** Additional headers for Mountra API requests. They are never sent to signed URLs. */
+    headers?: HeadersInit;
+    fetch?: typeof globalThis.fetch;
+    /** Adapter for S3 Multipart uploads used by chunks larger than 128 MiB. */
+    jumboChunkUploader?: JumboChunkUploader;
+    /** Durable local checkpoint store for jumbo Multipart uploads. */
+    jumboChunkCheckpointStore?: JumboChunkCheckpointStore;
+    /** S3 Multipart part size. Defaults to 16 MiB. */
+    jumboPartSize?: number;
+}
+interface UploadFileOptions extends WorkspaceSelector {
+    path: string;
+    /** Number of logical chunks. Defaults to 1. */
+    chunkCount?: number;
+    contentType?: string;
+    nameConflictStrategy?: "overwrite" | "keep_both";
+    signal?: AbortSignal;
+    onProgress?: (progress: MountraProgress) => void;
+    /** Persist this serializable context before the first chunk is uploaded. */
+    onSessionPrepared?: (context: UploadSessionContext) => void | Promise<void>;
+}
+interface UploadResumeOptions extends WorkspaceSelector {
+    signal?: AbortSignal;
+    onProgress?: (progress: MountraProgress) => void;
+}
+interface MountraProgress {
+    phase: "uploading" | "finishing";
+    uploadedBytes: number;
+    totalBytes: number;
+    uploadedChunks: number;
+    totalChunks: number;
+    uploadedParts?: number;
+    totalParts?: number;
+}
+interface FileChunk {
+    index: number;
+    offset: number;
+    size: number;
+    blob: Blob;
+}
+interface UploadTarget {
+    chunk_index: number;
+    storage_key: string;
+    put_method?: string;
+    put_url?: string;
+    put_headers: Record<string, string>;
+    size: number;
+    upload_required: boolean;
+}
+interface UploadSessionChunkContext {
+    index: number;
+    offset: number;
+    size: number;
+    sha256: string;
+}
+interface S3MultipartPart {
+    partNumber: number;
+    etag: string;
+    size: number;
+    sha256: string;
+}
+interface JumboChunkCreateInput {
+    storageKey: string;
+    contentType?: string;
+    signal?: AbortSignal;
+}
+interface JumboChunkUploadPartInput {
+    storageKey: string;
+    uploadId: string;
+    partNumber: number;
+    body: Blob;
+    signal?: AbortSignal;
+}
+interface JumboChunkCompleteInput {
+    storageKey: string;
+    uploadId: string;
+    parts: Array<Pick<S3MultipartPart, "partNumber" | "etag">>;
+    signal?: AbortSignal;
+}
+/**
+ * Small S3 Multipart adapter. Implement these methods with the S3 SDK used by
+ * the host application. Reusing a part number is intentional: S3 replaces
+ * the previous part, which makes retries idempotent.
+ */
+interface JumboChunkUploader {
+    createMultipartUpload(input: JumboChunkCreateInput): Promise<{
+        uploadId: string;
+    }>;
+    uploadPart(input: JumboChunkUploadPartInput): Promise<{
+        etag: string;
+    }>;
+    completeMultipartUpload(input: JumboChunkCompleteInput): Promise<void>;
+    abortMultipartUpload?(input: {
+        storageKey: string;
+        uploadId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+interface JumboChunkCheckpoint {
+    version: 1;
+    storageKey: string;
+    chunkIndex: number;
+    chunkSize: number;
+    chunkSha256: string;
+    partSize: number;
+    uploadId: string;
+    completed: boolean;
+    completing: boolean;
+    parts: S3MultipartPart[];
+}
+interface JumboChunkCheckpointStore {
+    load(key: string): Promise<JumboChunkCheckpoint | null>;
+    save(key: string, checkpoint: JumboChunkCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+interface S3MultipartClient {
+    createMultipartUpload(input: {
+        bucket: string;
+        key: string;
+        contentType?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        uploadId: string;
+    }>;
+    uploadPart(input: {
+        bucket: string;
+        key: string;
+        uploadId: string;
+        partNumber: number;
+        body: Blob;
+        signal?: AbortSignal;
+    }): Promise<{
+        etag: string;
+    }>;
+    completeMultipartUpload(input: {
+        bucket: string;
+        key: string;
+        uploadId: string;
+        parts: Array<Pick<S3MultipartPart, "partNumber" | "etag">>;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    abortMultipartUpload?(input: {
+        bucket: string;
+        key: string;
+        uploadId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Serializable metadata a client must persist alongside its file/blob handle. */
+interface UploadSessionContext {
+    uploadId: string;
+    path: string;
+    fileSize: number;
+    contentHash: string;
+    chunkMethod: "none" | "fix" | "cdc";
+    chunks: UploadSessionChunkContext[];
+    contentType?: string;
+}
+interface PrepareUploadResponse {
+    upload_id: string;
+    path: string;
+    expires_in_seconds: number;
+    chunk_method: "none" | "fix" | "cdc";
+    session_status: "prepared" | "uploaded" | "finished" | "aborted" | "expired";
+    upload_targets: UploadTarget[];
+}
+interface UploadStatusChunk {
+    chunk_index: number;
+    offset: number;
+    size: number;
+    sha256: string;
+    storage_key: string;
+    status: "pending" | "uploaded";
+    upload_required: boolean;
+    put_method?: string;
+    put_url?: string;
+    put_headers: Record<string, string>;
+}
+interface UploadStatusResponse {
+    upload_id: string;
+    path: string;
+    storage_key: string;
+    size: number;
+    chunk_method: "none" | "fix" | "cdc";
+    session_status: "prepared" | "uploaded" | "finished" | "aborted" | "expired";
+    finish_status: "awaiting_upload" | "awaiting_finish" | "awaiting_chunks" | "completed" | "aborted" | "expired";
+    total_chunks: number;
+    uploaded_chunks: number;
+    uploaded_bytes: number;
+    chunks: UploadStatusChunk[];
+    ino?: number;
+}
+interface FinishUploadResponse {
+    upload_id: string;
+    path: string;
+    storage_key: string;
+    size: number;
+    chunk_method: "none" | "fix" | "cdc";
+    session_status: "prepared" | "uploaded" | "finished" | "aborted" | "expired";
+    finish_status: "awaiting_upload" | "awaiting_finish" | "awaiting_chunks" | "completed" | "aborted" | "expired";
+    ino?: number;
+}
+type UploadResult = FinishUploadResponse;
+interface PreparedUpload {
+    response: PrepareUploadResponse;
+    chunks: FileChunk[];
+    chunkHashes: string[];
+    contentHash: string;
+    context: UploadSessionContext;
+}
+declare class MountraApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, input: {
+        status: number;
+        code?: string;
+        body?: unknown;
+    });
+}
+declare class InMemoryJumboChunkCheckpointStore implements JumboChunkCheckpointStore {
+    private readonly records;
+    load(key: string): Promise<JumboChunkCheckpoint | null>;
+    save(key: string, checkpoint: JumboChunkCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+declare class LocalStorageJumboChunkCheckpointStore implements JumboChunkCheckpointStore {
+    private readonly prefix;
+    constructor(prefix?: string);
+    load(key: string): Promise<JumboChunkCheckpoint | null>;
+    save(key: string, checkpoint: JumboChunkCheckpoint): Promise<void>;
+    remove(key: string): Promise<void>;
+    private storageKey;
+    private getStorage;
+}
+declare class S3MultipartUploader implements JumboChunkUploader {
+    private readonly bucket;
+    private readonly client;
+    constructor(input: {
+        bucket: string;
+        client: S3MultipartClient;
+    });
+    createMultipartUpload(input: JumboChunkCreateInput): Promise<{
+        uploadId: string;
+    }>;
+    uploadPart(input: JumboChunkUploadPartInput): Promise<{
+        etag: string;
+    }>;
+    completeMultipartUpload(input: JumboChunkCompleteInput): Promise<void>;
+    abortMultipartUpload(input: {
+        storageKey: string;
+        uploadId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+declare function splitFileIntoChunks(file: Blob, chunkCount?: number): FileChunk[];
+declare function isJumboChunk(size: number): boolean;
+declare function sha256Hex(blob: Blob): Promise<string>;
+declare class MountraClient {
+    private readonly baseUrl;
+    private readonly apiPrefix;
+    private readonly clientSelector;
+    private readonly token?;
+    private readonly headers?;
+    private readonly fetchImpl;
+    private readonly jumboChunkUploader?;
+    private readonly jumboChunkCheckpointStore;
+    private readonly jumboPartSize;
+    constructor(options: MountraClientOptions);
+    prepareUpload(file: Blob, options: UploadFileOptions): Promise<PreparedUpload>;
+    uploadFile(file: Blob, options: UploadFileOptions): Promise<UploadResult>;
+    /** Generic upload entry point. It selects PUT or S3 Multipart per chunk. */
+    upload(file: Blob, options: UploadFileOptions): Promise<UploadResult>;
+    getUploadStatus(uploadId: string, selector?: WorkspaceSelector, signal?: AbortSignal): Promise<UploadStatusResponse>;
+    /**
+     * Resume a previously prepared session. The caller must restore the same
+     * file/blob separately; this context only describes how that file was cut.
+     */
+    resumeUpload(file: Blob, context: UploadSessionContext, options?: UploadResumeOptions): Promise<UploadResult>;
+    private uploadPreparedChunks;
+    private buildJumboCheckpointKey;
+    private uploadJumboChunk;
+    private uploadJumboPart;
+    private isCompatibleJumboCheckpoint;
+    private assertUploadContext;
+    finishUpload(uploadId: string, selector?: WorkspaceSelector): Promise<UploadResult>;
+    private endpoint;
+    private requestJson;
+}
+declare function createMountraClient(options: MountraClientOptions): MountraClient;
+
+export { type AccessToken, type ChunkMethod, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type FileChunk, type FinishUploadResponse, InMemoryJumboChunkCheckpointStore, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, MountraApiError, MountraClient, type MountraClientOptions, type MountraProgress, MountraClient as MountraSDK, type PrepareUploadResponse, type PreparedUpload, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };