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

package/dist/errors.js

@@ -0,0 +1,94 @@
+export const ERROR_CODES = {
+    invalid_request: "fix_request",
+    invalid_record: "fix_request",
+    not_found: "refresh",
+    conflict: "resolve_conflict",
+    unauthenticated: "reauthorize",
+    forbidden: "reauthorize",
+    collection_invalid: "repair_collection",
+    unavailable: "retry",
+    rate_limited: "retry",
+    quota_exceeded: "free_space",
+    too_large: "fix_request",
+    upgrade_required: "upgrade",
+    outcome_unknown: "resolve_outcome",
+    cancelled: "none",
+    internal: "contact_support",
+};
+export function isErrorCode(code) {
+    return Object.prototype.hasOwnProperty.call(ERROR_CODES, code);
+}
+/** The recovery action for a code, or `contact_support` for a code this SDK doesn't know. */
+export function recoveryFor(code) {
+    return isErrorCode(code) ? ERROR_CODES[code] : "contact_support";
+}
+/**
+ * An error from a replica or from the SDK itself. Apps branch on `code` (and
+ * optionally `reason`) and show their own text; `message` is for developers.
+ */
+export class MdbaseError extends Error {
+    code;
+    recovery;
+    reason;
+    details;
+    retryAfterMs;
+    issues;
+    traceId;
+    /**
+     * The original mutation of a failed or unsettled write. Its outcome may still be
+     * unknown: resolve it with `receipt` / `awaitReceipt` / `pendingWrites` under this
+     * same ID. The SDK never resubmits it under a new identity. Absent for reads and
+     * dry runs, which capture nothing. Not part of {@link toProblem}.
+     */
+    mutationId;
+    /** Every original mutation of a failed partial batch, in op order. */
+    mutationIds;
+    constructor(problem, context = {}) {
+        super(problem.message, context.cause === undefined ? undefined : { cause: context.cause });
+        this.name = "MdbaseError";
+        // A code outside the 15 is a replica bug or a newer API; never invent recovery.
+        this.code = isErrorCode(problem.code) ? problem.code : "internal";
+        this.recovery = isErrorCode(problem.code) ? problem.recovery : "contact_support";
+        if (problem.reason !== undefined)
+            this.reason = problem.reason;
+        if (problem.details !== undefined)
+            this.details = problem.details;
+        if (problem.retryAfterMs !== undefined)
+            this.retryAfterMs = problem.retryAfterMs;
+        if (problem.issues !== undefined)
+            this.issues = problem.issues;
+        if (problem.traceId !== undefined)
+            this.traceId = problem.traceId;
+        const ids = context.mutationIds ? Object.freeze([...context.mutationIds]) : undefined;
+        const id = context.mutationId ?? ids?.[0];
+        if (id !== undefined)
+            this.mutationId = id;
+        if (ids !== undefined)
+            this.mutationIds = ids;
+    }
+    toProblem() {
+        const p = { code: this.code, recovery: this.recovery, message: this.message };
+        if (this.reason !== undefined)
+            p.reason = this.reason;
+        if (this.details !== undefined)
+            p.details = this.details;
+        if (this.retryAfterMs !== undefined)
+            p.retryAfterMs = this.retryAfterMs;
+        if (this.issues !== undefined)
+            p.issues = this.issues;
+        if (this.traceId !== undefined)
+            p.traceId = this.traceId;
+        return p;
+    }
+}
+/** Build an error locally (transport failures, cancellation, schema mismatches). */
+export function mdbaseError(code, message, 
+/** A `reason` string, or more problem fields. */
+extra = {}) {
+    const more = typeof extra === "string" ? { reason: extra } : extra;
+    return new MdbaseError({ code, recovery: ERROR_CODES[code], message, ...more });
+}
+export function isMdbaseError(e, code) {
+    return e instanceof MdbaseError && (code === undefined || e.code === code);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -0,0 +1,147 @@
+import { list } from "./codec.js";
+import type { ChangesWatch, MdbaseClient, Write, WriteOptions } from "./client.js";
+import { ChangesResult, HelloResult, FileView, ListFilesResult, Materialization, MediaClass, TransferProgress, Uuid } from "./wire.js";
+/** Convenience reads that return whole bytes are capped, as today (§10.2). */
+export declare const MAX_CONVENIENCE_BYTES: number;
+export type FileRef = Uuid | {
+    path: string;
+} | FileView;
+/** What a session may do with files. Same vocabulary as Connect's file capability. */
+export type FileAction = "list" | "read" | "add" | "replace" | "move" | "delete";
+/** Where file actions apply: the whole file namespace, or only these folders
+ * (compared by the replica's path key; records are never folder-scoped). */
+export type FileScope = {
+    readonly kind: "collection";
+} | {
+    readonly kind: "selected_folders";
+    readonly folders: readonly string[];
+};
+export interface FileGrant {
+    readonly actions: readonly FileAction[];
+    readonly scope: FileScope;
+}
+/**
+ * The file actions and folder scope of a session, mapped from its native grant.
+ * `null` when the scope is unknown: a grant session on a producer before API 1.2,
+ * which does not report `file_folders`. The replica still checks every call.
+ */
+export declare function fileGrant(hello: HelloResult): FileGrant | null;
+/** SDK-internal: the app's declared file actions joined with the person's
+ * recorded choices. Not exported from the package index. */
+export interface FileAccessGate {
+    /** Throws a typed `forbidden` error (`access_required` / `access_undeclared`). */
+    check(action: FileAction): void;
+    allows(action: FileAction): boolean;
+}
+export declare function bindFileAccess(files: FilesApi, gate: FileAccessGate): void;
+export interface UploadOptions {
+    signal?: AbortSignal;
+    onProgress?: (p: TransferProgress) => void;
+    /** Reuse to resume an interrupted upload (retry-safe). Default: a new UUIDv7. */
+    transferId?: Uuid;
+    /** Replace this file (absent = a new file). */
+    fileId?: Uuid;
+    /** CAS on replace: the digest the caller last saw. */
+    ifRevision?: string;
+    mutationId?: Uuid;
+}
+/** Anything the SDK can upload from. */
+export type UploadSource = Uint8Array | Blob | ArrayBuffer;
+/** A tracked upload receipt with its original, replica-owned file identity. */
+export interface FileWrite extends Write {
+    readonly fileId: Uuid;
+}
+export declare class FilesApi {
+    private client;
+    private uploading;
+    private progress;
+    private streams;
+    private wired;
+    private opening;
+    private early;
+    constructor(client: MdbaseClient);
+    /** The current session's file actions and folder scope ({@link fileGrant}). */
+    get grant(): FileGrant | null;
+    /**
+     * Follow non-record file changes: uploads and replacements are puts, a move is
+     * a removal at the old path then a put at the new one, deletions are removals.
+     * It is {@link MdbaseClient.watchChanges} narrowed to files, with the same
+     * lifecycle, reconnect and `reset` (re-read your file cache) semantics; batches
+     * with no file change are skipped. A removal the replica could not classify
+     * is passed on (dropping an unknown ID is harmless); an unclassified put turns
+     * the batch into a reset. Requires API 1.2, else `upgrade_required`.
+     */
+    watch(onChanges: (batch: ChangesResult) => void, options?: {
+        cursor?: string;
+    }): ChangesWatch;
+    private wire;
+    private session;
+    /** One page of the files in a folder. */
+    listPage(o?: {
+        folder?: string;
+        media?: MediaClass[];
+        cursor?: string;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<ListFilesResult>;
+    /** Every file in a folder (all pages). */
+    list(o?: {
+        folder?: string;
+        media?: MediaClass[];
+        pageSize?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<FileView>;
+    get(f: FileRef, signal?: AbortSignal): Promise<FileView>;
+    /**
+     * Upload a file. Resumable: on a dropped link it reconnects and sends only the chunks
+     * the replica lacks. Returns the `file_put` write: `confirmed` means the bytes are
+     * durable in the collection. Concurrent calls run in FIFO order on the
+     * session's single upload lane; confirmation does not hold up the next upload.
+     */
+    upload(path: string, source: UploadSource, o?: UploadOptions): Promise<FileWrite>;
+    private uploadQueued;
+    private uploadOnce;
+    /** Abort an upload; the replica discards its chunks. */
+    abortUpload(transferId: Uuid): Promise<void>;
+    /**
+     * Stream a file's bytes, pinned to one revision. Chunks arrive in order; the stream
+     * closes only after the replica verified the whole-file digest. For canonical
+     * unindexed Markdown Blob sources, only a full read is supported: partial ranges
+     * refuse `unindexed_full_read_required`, and successful close additionally gates
+     * exact source count and UTF-8. Earlier chunks are provisional; `.file` resolves
+     * metadata, not final source verification. Cancellation rejects pending metadata
+     * and requests cleanup of the original pending request or returned stream, even
+     * when it wins before the stream ID is installed. AttachmentV1 ranges stay unchanged.
+     */
+    downloadStream(f: FileRef, o?: {
+        signal?: AbortSignal;
+        onProgress?: (p: TransferProgress) => void;
+        range?: [offset: number, length: number];
+        revision?: string;
+    }): ReadableStream<Uint8Array> & {
+        file: Promise<FileView>;
+    };
+    /** The fully verified source as bytes (at most 64 MiB; larger files use
+     * `downloadStream`). Includes canonical unindexed Markdown Blob sources;
+     * ordinary Blob support and AttachmentV1 behavior are unchanged. */
+    download(f: FileRef, o?: {
+        signal?: AbortSignal;
+        onProgress?: (p: TransferProgress) => void;
+    }): Promise<Uint8Array>;
+    /** Materialize a remote file on this device. */
+    fetch(f: FileRef, signal?: AbortSignal): Promise<void>;
+    /** Drop the local copy of a confirmed, unheld file (hosting app only). */
+    evict(f: FileRef): Promise<void>;
+    getMaterialization(): Promise<Materialization>;
+    setMaterialization(v: Materialization): Promise<void>;
+    /** Move a file; `updateRefs` rewrites links to it. */
+    move(f: FileView, to: string, o?: WriteOptions & {
+        updateRefs?: boolean;
+        ifRevision?: string;
+    }): Promise<Write>;
+    /** Delete a file. With a FileView, a concurrent replacement supersedes the delete. */
+    delete(f: FileRef, o?: WriteOptions & {
+        ifRevision?: string;
+    }): Promise<Write>;
+}
+export { list };