@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.153

package/node_modules/@mdbase-dev/connect-protocol/dist/files.d.ts

@@ -0,0 +1,288 @@
+/** Frozen predecessor file declaration; never translate this into v2 intent. */
+export interface LegacyApplicationFileRequirement {
+    actions: FileAction[];
+    scope: FileScope;
+}
+export declare const FILE_PROTOCOL_VERSION: 1;
+export declare const FILE_TRANSFER_PROTOCOL_VERSION: 1;
+export declare const DEFAULT_FILE_CHUNK_BYTES: number;
+export declare const MAX_FILE_CHUNK_BYTES: number;
+export declare const MAX_FILE_FRAME_HEADER_BYTES: number;
+export declare const FILE_FRAME_PREFIX_BYTES = 16;
+export declare const FILE_FRAME_MAGIC: "MDBF";
+export declare const MAX_FILE_FRAME_BYTES: number;
+export declare const RELAY_FILE_PROTOCOL_VERSION: 1;
+export declare const RELAY_FILE_PREFIX_BYTES = 16;
+export declare const MAX_RELAY_FILE_HEADER_BYTES = 1024;
+export declare const MAX_RELAY_FILE_PAYLOAD_BYTES: number;
+export declare const RELAY_FILE_MAGIC: "MDBR";
+export type FileMediaClass = "image" | "audio" | "video" | "pdf" | "other";
+/** Device-local projection. Folder exclusions apply to Markdown and files. */
+export interface SelectiveSyncPolicy {
+    file_classes: FileMediaClass[];
+    excluded_folders: string[];
+}
+export type FileAction = "list" | "read" | "add" | "replace" | "move" | "delete";
+export type FileTransferDirection = "upload" | "download";
+export type FileTransferProtection = "grant_aead_v1" | "transport_tls";
+export type FileTransferState = "open" | "committed" | "aborted" | "expired";
+export type FileTransferStrategy = {
+    kind: "framed_chunks";
+    chunk_size: number;
+} | {
+    kind: "object_put";
+} | {
+    kind: "object_multipart";
+    part_size: number;
+} | {
+    kind: "object_ranges";
+    part_size: number;
+};
+export type FileFrameKind = "upload_chunk" | "download_chunk";
+export type RelayFileKind = "upload_chunk" | "upload_acknowledged" | "download_request" | "download_chunk" | "rejected";
+export type FileScope = {
+    kind: "selected_folders";
+    folders: string[];
+} | {
+    kind: "collection";
+};
+/** File intent declared by an application before an authority is selected. */
+export interface ApplicationFileRequirement {
+    required: FileAction[];
+    optional?: FileAction[];
+    scope: FileScope;
+}
+/** Exact file actions signed into an authorization request. */
+export interface ApplicationFileRequest {
+    actions: FileAction[];
+    scope: FileScope;
+}
+export declare function applicationFileRequest(requirement: ApplicationFileRequirement, options?: {
+    includeOptional?: boolean;
+}): ApplicationFileRequest;
+export interface FileCapability {
+    kind: "files";
+    protocol_version: 1;
+    actions: FileAction[];
+    scope: FileScope;
+}
+export interface CollectionFileDescriptor {
+    file_id: string;
+    path: string;
+    revision: string;
+    content_digest: `sha256:${string}`;
+    size: number;
+    media_type?: string;
+    media_class: FileMediaClass;
+    modified_at: string;
+}
+export interface ListFilesRequest {
+    protocol_version: 1;
+    type: "list_files";
+    folder?: string;
+    /** Opaque authority-issued continuation cursor. */
+    after?: string;
+    limit?: number;
+}
+export type StatFileRequest = {
+    protocol_version: 1;
+    type: "stat_file";
+} & ({
+    path: string;
+    file_id?: never;
+} | {
+    path?: never;
+    file_id: string;
+});
+export interface FileStat {
+    protocol_version: 1;
+    type: "file_stat";
+    file: CollectionFileDescriptor | null;
+}
+export interface ListFilesPage {
+    /** Authority-local file implementation features, not granted actions. */
+    authority_capabilities?: string[];
+    protocol_version: 1;
+    type: "files_page";
+    files: CollectionFileDescriptor[];
+    /** Opaque continuation cursor; pass it back unchanged as `after`. */
+    next?: string;
+}
+export interface OpenFileUploadRequest {
+    protocol_version: 1;
+    type: "open_file_upload";
+    transfer_id: string;
+    path: string;
+    size: number;
+    content_digest: `sha256:${string}`;
+    media_type?: string;
+    if_revision?: string;
+}
+export interface OpenAuthorityImportFileUploadRequest {
+    protocol_version: 1;
+    type: "open_authority_import_file_upload";
+    transfer_id: string;
+    file_id: string;
+}
+export interface OpenFileDownloadRequest {
+    protocol_version: 1;
+    type: "open_file_download";
+    transfer_id: string;
+    file_id: string;
+    revision?: string;
+}
+export interface MoveFileRequest {
+    protocol_version: 1;
+    type: "move_file";
+    mutation_id: string;
+    file_id: string;
+    if_revision: string;
+    from_path: string;
+    path: string;
+    update_references: boolean;
+}
+export interface MoveFileReceipt {
+    protocol_version: 1;
+    type: "file_moved";
+    mutation_id: string;
+    file: CollectionFileDescriptor;
+}
+export interface DeleteFileRequest {
+    protocol_version: 1;
+    type: "delete_file";
+    mutation_id: string;
+    file_id: string;
+    if_revision: string;
+    path: string;
+}
+export interface DeleteFileReceipt {
+    protocol_version: 1;
+    type: "file_deleted";
+    mutation_id: string;
+    file_id: string;
+    previous_path: string;
+    revision: string;
+}
+export interface FileTransferSession {
+    protocol_version: 1;
+    type: "file_transfer";
+    transfer_id: string;
+    direction: FileTransferDirection;
+    protection: FileTransferProtection;
+    strategy: FileTransferStrategy;
+    total_size: number;
+    expires_at: string;
+    received: number[];
+    /** R2/S3 part receipts for bandwidth-efficient multipart resume. */
+    uploaded_parts?: UploadedFilePart[];
+    /** Create-only single PUT; replay preserves its original URL and expiry, not fresh progress. */
+    prepared_upload_part?: PreparedFilePart;
+}
+export interface FileTransferStatus {
+    protocol_version: 1;
+    type: "file_transfer_status";
+    transfer_id: string;
+    state: FileTransferState;
+    received: number[];
+    received_bytes: number;
+    /** Object-store receipts for the currently durable multipart parts. */
+    uploaded_parts: UploadedFilePart[];
+}
+export interface PrepareFileUploadPartRequest {
+    protocol_version: 1;
+    type: "prepare_file_upload_part";
+    transfer_id: string;
+    part_number: number;
+    content_length: number;
+}
+export interface PreparedFilePart {
+    protocol_version: 1;
+    type: "file_part";
+    transfer_id: string;
+    part_index: number;
+    offset: number;
+    content_length: number;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    expires_at: string;
+}
+export interface UploadedFilePart {
+    part_number: number;
+    etag: string;
+}
+export interface CommitFileUploadRequest {
+    protocol_version: 1;
+    type: "commit_file_upload";
+    transfer_id: string;
+    parts?: UploadedFilePart[];
+}
+export interface CommitFileUploadReceipt {
+    protocol_version: 1;
+    type: "file_upload_committed";
+    transfer_id: string;
+    file: CollectionFileDescriptor;
+}
+export interface AbortFileTransferRequest {
+    protocol_version: 1;
+    type: "abort_file_transfer";
+    transfer_id: string;
+}
+export interface GetFileTransferStatusRequest {
+    protocol_version: 1;
+    type: "get_file_transfer_status";
+    transfer_id: string;
+}
+export interface FileFrameHeader {
+    protocol_version: 1;
+    protection: FileTransferProtection;
+    grant_id: string;
+    authority_id: string;
+    collection_id: string;
+    transfer_id: string;
+    direction: FileTransferDirection;
+    chunk_size: number;
+    chunk_index: number;
+    offset: number;
+    plaintext_length: number;
+    total_size: number;
+    scope_epoch: number;
+    key_id?: string;
+}
+export interface FileFrame {
+    kind: FileFrameKind;
+    header: FileFrameHeader;
+    payload: Uint8Array;
+}
+export interface RelayFileHeader {
+    protocol_version: 1;
+    type: RelayFileKind;
+    request_id: string;
+    grant_id: string;
+    transfer_id: string;
+    chunk_index: number;
+}
+export interface RelayFileFrame {
+    kind: RelayFileKind;
+    header: RelayFileHeader;
+    payload: Uint8Array;
+}
+export interface FileFrameDecodeLimits {
+    maxHeaderBytes?: number;
+    maxPayloadBytes?: number;
+}
+export type FileFrameErrorCode = "invalid_magic" | "unsupported_version" | "invalid_kind" | "unsupported_flags" | "invalid_length" | "invalid_header" | "limit_exceeded";
+export declare class FileFrameError extends Error {
+    readonly code: FileFrameErrorCode;
+    constructor(code: FileFrameErrorCode, message: string);
+}
+export declare class RelayFileFrameError extends Error {
+    readonly code: FileFrameErrorCode;
+    constructor(code: FileFrameErrorCode, message: string);
+}
+/** Prefix and canonical header authenticated by the file chunk AEAD profile. */
+export declare function fileFrameAuthenticatedData(kind: FileFrameKind, input: FileFrameHeader): Uint8Array;
+export declare function encodeFileFrame(frame: FileFrame): Uint8Array;
+export declare function decodeFileFrame(bytes: Uint8Array, limits?: FileFrameDecodeLimits): FileFrame;
+export declare function encodeRelayFileFrame(frame: RelayFileFrame): Uint8Array;
+export declare function decodeRelayFileFrame(bytes: Uint8Array): RelayFileFrame;