@mdbase-dev/connect-protocol 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/connect-problems.generated.js

@@ -0,0 +1,364 @@
+// Generated by scripts/generate-connect-problems.mjs. Do not edit directly.
+export const CONNECT_PROBLEM_VERSION = 1;
+export const CONNECT_PROBLEM_CATALOG = {
+    "access_denied": { category: "authorization", recovery: "reauthorize" },
+    "access_paused": { category: "availability", recovery: "resume_connector_access" },
+    "approval_window_blocked": { category: "authorization", recovery: "reauthorize" },
+    "authority_authorization_changed": { category: "authorization", recovery: "reauthorize" },
+    "authorization_cancelled": { category: "cancellation", recovery: "none" },
+    "authorization_expired": { category: "authorization", recovery: "reauthorize" },
+    "browser_required": { category: "compatibility", recovery: "none" },
+    "callback_url_required": { category: "validation", recovery: "fix_request" },
+    "change_cursor_reset": { category: "conflict", recovery: "refresh" },
+    "collection_access_denied": { category: "authorization", recovery: "reauthorize" },
+    "collection_configuration_invalid": { category: "validation", recovery: "repair_collection" },
+    "collection_contracts_missing": { category: "compatibility", recovery: "choose_collection" },
+    "collection_incompatible": { category: "compatibility", recovery: "choose_collection" },
+    "collection_invalid": { category: "validation", recovery: "repair_collection" },
+    "collection_kind_unsupported": { category: "compatibility", recovery: "choose_collection" },
+    "collection_mismatch": { category: "selection", recovery: "choose_collection" },
+    "collection_not_found": { category: "selection", recovery: "choose_collection" },
+    "collection_not_ready": { category: "selection", recovery: "choose_collection" },
+    "collection_not_selected": { category: "selection", recovery: "choose_collection" },
+    "collection_type_registry_invalid": { category: "validation", recovery: "repair_collection" },
+    "collection_version_unsupported": { category: "compatibility", recovery: "upgrade_collection" },
+    "concurrent_modification": { category: "conflict", recovery: "refresh" },
+    "connector_identity_changed": { category: "integrity", recovery: "reauthorize" },
+    "connector_offline": { category: "availability", recovery: "retry" },
+    "connector_upgrade_required": { category: "compatibility", recovery: "upgrade_connector" },
+    "device_authorization_failed": { category: "authorization", recovery: "reauthorize" },
+    "direct_operation_rejected": { category: "authorization", recovery: "reauthorize" },
+    "discovery_failed": { category: "availability", recovery: "retry" },
+    "encrypted_relay_rejected": { category: "authorization", recovery: "reauthorize" },
+    "encryption_required": { category: "authorization", recovery: "reauthorize" },
+    "expired_token": { category: "authorization", recovery: "reauthorize" },
+    "file_changed_during_move": { category: "conflict", recovery: "refresh" },
+    "file_changed_during_read": { category: "conflict", recovery: "refresh" },
+    "file_move_failed": { category: "internal", recovery: "contact_support" },
+    "file_mutation_conflict": { category: "conflict", recovery: "resolve_conflict" },
+    "file_not_found": { category: "conflict", recovery: "refresh" },
+    "file_source_mismatch": { category: "conflict", recovery: "refresh" },
+    "file_upload_incomplete": { category: "conflict", recovery: "retry" },
+    "hosted_provider_unavailable": { category: "availability", recovery: "retry" },
+    "insufficient_access": { category: "authorization", recovery: "reauthorize" },
+    "invalid_application_manifest": { category: "validation", recovery: "fix_request" },
+    "invalid_callback": { category: "validation", recovery: "fix_request" },
+    "invalid_device_authorization_response": { category: "integrity", recovery: "contact_support" },
+    "invalid_encrypted_response": { category: "integrity", recovery: "contact_support" },
+    "invalid_loopback_url": { category: "validation", recovery: "fix_request" },
+    "invalid_mutation_id": { category: "validation", recovery: "fix_request" },
+    "invalid_operation_response": { category: "integrity", recovery: "contact_support" },
+    "invalid_path": { category: "validation", recovery: "fix_request" },
+    "invalid_preflight": { category: "conflict", recovery: "refresh" },
+    "invalid_push_payload": { category: "validation", recovery: "fix_request" },
+    "invalid_push_subscription": { category: "validation", recovery: "fix_request" },
+    "invalid_request": { category: "validation", recovery: "fix_request" },
+    "invalid_token_response": { category: "integrity", recovery: "contact_support" },
+    "managed_fcm_not_declared": { category: "compatibility", recovery: "fix_request" },
+    "manifest_load_failed": { category: "availability", recovery: "retry" },
+    "manifest_required": { category: "validation", recovery: "fix_request" },
+    "missing_grant_key": { category: "authorization", recovery: "reauthorize" },
+    "no_pending_mutation": { category: "conflict", recovery: "refresh" },
+    "not_authorized": { category: "authorization", recovery: "reauthorize" },
+    "not_remote_authority": { category: "compatibility", recovery: "choose_collection" },
+    "notification_criterion_not_declared": { category: "validation", recovery: "fix_request" },
+    "notification_reauthorization_required": { category: "authorization", recovery: "reauthorize" },
+    "notification_registration_failed": { category: "availability", recovery: "retry" },
+    "notification_unregistration_failed": { category: "availability", recovery: "retry" },
+    "notifications_not_declared": { category: "compatibility", recovery: "fix_request" },
+    "notifications_unavailable": { category: "availability", recovery: "retry" },
+    "operation_cancelled": { category: "cancellation", recovery: "none" },
+    "operation_failed": { category: "internal", recovery: "contact_support" },
+    "operation_invalid": { category: "validation", recovery: "fix_request" },
+    "operation_outcome_unknown": { category: "conflict", recovery: "resolve_outcome" },
+    "path_occupied": { category: "conflict", recovery: "resolve_conflict" },
+    "pending_mutation_unresolved": { category: "conflict", recovery: "resolve_outcome" },
+    "query_snapshot_changed": { category: "conflict", recovery: "refresh" },
+    "rate_limited": { category: "availability", recovery: "retry" },
+    "redirect_uri_required": { category: "validation", recovery: "fix_request" },
+    "reference_updates_unsupported": { category: "compatibility", recovery: "fix_request" },
+    "relay_authorization_expired": { category: "authorization", recovery: "reauthorize" },
+    "relay_unavailable": { category: "availability", recovery: "retry" },
+    "sandbox_unsupported": { category: "compatibility", recovery: "fix_request" },
+    "scope_denied": { category: "authorization", recovery: "reauthorize" },
+    "stale_file_revision": { category: "conflict", recovery: "refresh" },
+    "storage_required": { category: "compatibility", recovery: "none" },
+    "sync_failed": { category: "availability", recovery: "retry" },
+    "temporarily_unavailable": { category: "availability", recovery: "retry" },
+    "timeout": { category: "availability", recovery: "retry" },
+    "token_exchange_failed": { category: "availability", recovery: "retry" },
+    "type_pack_provision_failed": { category: "validation", recovery: "repair_collection" },
+    "unknown_collection": { category: "selection", recovery: "choose_collection" },
+    "unsafe_file_path": { category: "validation", recovery: "fix_request" },
+    "unsupported_encryption": { category: "compatibility", recovery: "upgrade_application" },
+    "unsupported_operation": { category: "compatibility", recovery: "fix_request" }
+};
+const CONNECT_PROBLEM_DETAIL_SCHEMAS = {
+    "access_denied": {
+        "type": "object",
+        "required": [],
+        "properties": {
+            "return_to": {
+                "type": "string"
+            }
+        }
+    },
+    "approval_window_blocked": {
+        "type": "object",
+        "required": [
+            "user_code",
+            "verification_uri",
+            "verification_uri_complete",
+            "expires_at",
+            "interval_seconds"
+        ],
+        "properties": {
+            "user_code": {
+                "type": "string"
+            },
+            "verification_uri": {
+                "type": "string"
+            },
+            "verification_uri_complete": {
+                "type": "string"
+            },
+            "expires_at": {
+                "type": "integer"
+            },
+            "interval_seconds": {
+                "type": "integer"
+            }
+        }
+    },
+    "collection_configuration_invalid": {
+        "type": "object",
+        "required": [
+            "diagnostics"
+        ],
+        "properties": {
+            "diagnostics": {
+                "type": "array",
+                "items": {
+                    "type": "object"
+                }
+            }
+        }
+    },
+    "collection_contracts_missing": {
+        "type": "object",
+        "required": [
+            "contracts"
+        ],
+        "properties": {
+            "contracts": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": [
+                        "id",
+                        "version"
+                    ],
+                    "properties": {
+                        "id": {
+                            "type": "string"
+                        },
+                        "version": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "collection_invalid": {
+        "type": "object",
+        "required": [
+            "diagnostics"
+        ],
+        "properties": {
+            "diagnostics": {
+                "type": "array",
+                "items": {
+                    "type": "object"
+                }
+            }
+        }
+    },
+    "collection_type_registry_invalid": {
+        "type": "object",
+        "required": [
+            "diagnostics"
+        ],
+        "properties": {
+            "diagnostics": {
+                "type": "array",
+                "items": {
+                    "type": "object"
+                }
+            }
+        }
+    },
+    "collection_version_unsupported": {
+        "type": "object",
+        "required": [
+            "current_version",
+            "required_version"
+        ],
+        "properties": {
+            "current_version": {
+                "type": "string"
+            },
+            "required_version": {
+                "type": "string"
+            }
+        }
+    },
+    "connector_offline": {
+        "type": "object",
+        "required": [],
+        "properties": {
+            "connector_name": {
+                "type": "string"
+            }
+        }
+    },
+    "insufficient_access": {
+        "type": "object",
+        "required": [
+            "required_operations",
+            "granted_operations",
+            "missing_operations"
+        ],
+        "properties": {
+            "required_operations": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "granted_operations": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "missing_operations": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            }
+        }
+    },
+    "operation_invalid": {
+        "type": "object",
+        "required": [
+            "diagnostics"
+        ],
+        "properties": {
+            "diagnostics": {
+                "type": "array",
+                "items": {
+                    "type": "object"
+                }
+            },
+            "partial_result": {}
+        }
+    },
+    "rate_limited": {
+        "type": "object",
+        "required": [],
+        "properties": {
+            "retry_after_ms": {
+                "type": "integer"
+            }
+        }
+    }
+};
+export function isConnectProblemCode(code) {
+    return Object.hasOwn(CONNECT_PROBLEM_CATALOG, code);
+}
+export function isConnectProblem(value) {
+    if (!isPlainObject(value))
+        return false;
+    const candidate = value;
+    if (candidate.problem_version !== CONNECT_PROBLEM_VERSION || typeof candidate.message !== "string" || candidate.message.length === 0)
+        return false;
+    if (candidate.operation_outcome !== undefined && candidate.operation_outcome !== "not_sent" && candidate.operation_outcome !== "rejected" && candidate.operation_outcome !== "unknown")
+        return false;
+    if (candidate.trace_id !== undefined && (typeof candidate.trace_id !== "string" || candidate.trace_id.length === 0))
+        return false;
+    if (candidate.code === "unknown") {
+        return typeof candidate.server_code === "string"
+            && candidate.server_code.length > 0
+            && candidate.category === "unknown"
+            && candidate.recovery === "none";
+    }
+    if (typeof candidate.code !== "string" || !isConnectProblemCode(candidate.code) || candidate.server_code !== undefined)
+        return false;
+    const definition = CONNECT_PROBLEM_CATALOG[candidate.code];
+    const detailsSchema = CONNECT_PROBLEM_DETAIL_SCHEMAS[candidate.code];
+    const detailsMatch = detailsSchema === undefined
+        ? candidate.details === undefined
+        : candidate.details === undefined
+            ? (detailsSchema.required?.length ?? 0) === 0
+            : matchesDetailSchema(candidate.details, detailsSchema);
+    return candidate.category === definition.category
+        && candidate.recovery === definition.recovery
+        && detailsMatch;
+}
+function matchesDetailSchema(value, schema) {
+    if (schema.type === undefined)
+        return true;
+    if (schema.type === "string")
+        return typeof value === "string";
+    if (schema.type === "integer")
+        return typeof value === "number" && Number.isInteger(value);
+    if (schema.type === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    if (schema.type === "boolean")
+        return typeof value === "boolean";
+    if (schema.type === "array")
+        return Array.isArray(value) && value.every((item) => matchesDetailSchema(item, schema.items ?? {}));
+    if (!isPlainObject(value))
+        return false;
+    if (!schema.properties)
+        return true;
+    const candidate = value;
+    if (!Object.keys(candidate).every((key) => Object.hasOwn(schema.properties, key)))
+        return false;
+    if (!(schema.required ?? []).every((key) => Object.hasOwn(candidate, key)))
+        return false;
+    return Object.entries(candidate).every(([key, item]) => matchesDetailSchema(item, schema.properties[key]));
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function normalizeConnectProblem(serverCode, message, options = {}) {
+    if (isConnectProblemCode(serverCode)) {
+        const definition = CONNECT_PROBLEM_CATALOG[serverCode];
+        const candidate = {
+            problem_version: CONNECT_PROBLEM_VERSION,
+            code: serverCode,
+            category: definition.category,
+            recovery: definition.recovery,
+            message,
+            ...(options.details === undefined ? {} : { details: options.details }),
+            ...(options.operation_outcome === undefined ? {} : { operation_outcome: options.operation_outcome }),
+            ...(options.trace_id === undefined ? {} : { trace_id: options.trace_id })
+        };
+        if (isConnectProblem(candidate))
+            return candidate;
+    }
+    return {
+        problem_version: CONNECT_PROBLEM_VERSION,
+        code: "unknown",
+        server_code: serverCode,
+        category: "unknown",
+        recovery: "none",
+        message,
+        ...(options.details === undefined ? {} : { details: options.details }),
+        ...(options.operation_outcome === undefined ? {} : { operation_outcome: options.operation_outcome }),
+        ...(options.trace_id === undefined ? {} : { trace_id: options.trace_id })
+    };
+}

package/dist/files.d.ts

@@ -0,0 +1,253 @@
+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 {
+    actions: FileAction[];
+    scope: FileScope;
+}
+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 interface ListFilesPage {
+    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[];
+}
+export interface FileTransferStatus {
+    protocol_version: 1;
+    type: "file_transfer_status";
+    transfer_id: string;
+    state: FileTransferState;
+    received: number[];
+    received_bytes: number;
+}
+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;