mindoodb-app-sdk 0.0.14 → 0.0.17

package/dist/{types-B1iKRIuy.d.ts → types-Dw6YRApH.d.ts}

@@ -1,8 +1,8 @@
 import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition } from 'mindoodb-view-language';
 
-/** Launch target used by the Administrator when opening an app. */
+/** Launch target used by the Haven when opening an app. */
 type MindooDBAppRuntime = "iframe" | "window";
-/** Theme mode currently active in the Administrator host UI. */
+/** Theme mode currently active in the Haven host UI. */
 type MindooDBAppThemeMode = "light" | "dark";
 /** Host theme snapshot exposed to running apps. */
 interface MindooDBAppHostTheme {
@@ -109,6 +109,11 @@ interface MindooDBAppLaunchContext {
     uiPreferences: MindooDBAppUiPreferences;
     tenantId?: string;
     preferredDatabaseId?: string;
+    /**
+     * Epoch-millisecond cutoff when the host opened app databases in time travel
+     * read-only mode. Absent/null means the app is looking at live data.
+     */
+    timeTravelDate?: number | null;
     user: {
         id: string;
         username: string;
@@ -130,6 +135,18 @@ type MindooDBAppAttachmentPreviewMode = "image" | "pdf" | "text" | "markdown" |
 interface MindooDBAppAttachmentPreviewOptions {
     /** Historical snapshot timestamp previously obtained from `documents.history.getAtTimestamp()`. */
     timestamp?: number;
+    /** Stable revision id previously obtained from `documents.listHistory()`. */
+    revisionId?: MindooDBAppDocumentRevisionId;
+}
+type MindooDBAppDocumentScanPreset = "auto" | "a4-portrait" | "a4-landscape" | "letter-portrait" | "letter-landscape";
+interface MindooDBAppScanAttachmentOptions {
+    defaultFileName?: string;
+    preset?: MindooDBAppDocumentScanPreset;
+    mimeType?: "image/jpeg" | "image/png" | "application/pdf";
+}
+interface MindooDBAppScanAttachmentResult {
+    ok: boolean;
+    attachment?: MindooDBAppAttachmentInfo | null;
 }
 /** Resolved Haven preview session prepared for opening in a separate tab or window. */
 interface MindooDBAppAttachmentPreviewSession {
@@ -148,6 +165,7 @@ interface MindooDBAppDocumentSummary {
     id: string;
     data?: Record<string, unknown>;
     attachmentCount?: number;
+    createdAt?: string;
     updatedAt?: string;
     identityLabel?: string;
     publicKeyFingerprint?: string;
@@ -157,12 +175,19 @@ interface MindooDBAppDocumentSummary {
 interface MindooDBAppDocument {
     id: string;
     data: Record<string, unknown>;
+    /** Current Automerge heads for causal text edit reconciliation. */
+    heads?: string[];
     attachments?: MindooDBAppAttachmentInfo[];
+    createdAt?: string;
     updatedAt?: string;
 }
+/** Opaque persisted id for a document revision in the MindooDB DAG. */
+type MindooDBAppDocumentRevisionId = string;
 /** One entry in the document history timeline. */
 interface MindooDBAppDocumentHistoryEntry {
+    revisionId: MindooDBAppDocumentRevisionId;
     timestamp: number;
+    heads?: string[];
     publicKey: string;
     publicKeyFingerprint?: string;
     identityLabel?: string;
@@ -173,9 +198,13 @@ interface MindooDBAppDocumentHistoryEntry {
 /** Historical snapshot returned for a document at a specific timestamp. */
 interface MindooDBAppHistoricalDocument {
     id: string;
+    revisionId?: MindooDBAppDocumentRevisionId;
     timestamp: number;
+    heads?: string[];
     state: "missing" | "deleted" | "exists";
     data: Record<string, unknown> | null;
+    attachments?: MindooDBAppAttachmentInfo[];
+    attachmentSnapshotRevisionId?: MindooDBAppDocumentRevisionId | null;
 }
 /** Query options for paging through changefeed-backed document listings in a database. */
 interface MindooDBAppDocumentListQuery {
@@ -220,6 +249,87 @@ interface MindooDBAppCreateDocumentInput {
     set: Record<string, unknown>;
     /** Optional named document key. Defaults to `"default"` when omitted. */
     decryptionKeyId?: string;
+    /**
+     * Optional caller-provided document id. When omitted, MindooDB generates a
+     * UUID7. When provided, the id must match `^[A-Za-z][A-Za-z0-9_]*$`: the
+     * first character is an ASCII letter and subsequent characters may be ASCII
+     * letters, ASCII digits, or `_`.
+     *
+     * If a document with this id already exists locally, MindooDB returns the
+     * existing document instead of creating a new one (idempotent create), and
+     * the values in `set` are NOT applied. Caller-provided ids are useful for
+     * loading a known well-known document directly without first building a
+     * view, and for migrations that want to preserve external ids.
+     *
+     * Documents created with the same caller-provided id on independent replicas
+     * share Automerge ancestry, so subsequent edits on either replica still
+     * merge correctly when the replicas sync.
+     */
+    id?: string;
+}
+interface MindooDBAppTextEdit {
+    index: number;
+    deleteCount: number;
+    insert?: string;
+}
+interface MindooDBAppTextPatch {
+    path: Array<string | number>;
+    baseHeads?: string[];
+    edits: MindooDBAppTextEdit[];
+}
+/**
+ * Sets the value at `path` inside the document payload.
+ *
+ * Creates the field if it does not exist, or replaces the existing value.
+ * `path` addresses a property using object keys and list indices, for example
+ * `["workbook", "worksheetsById", "ws-1", "title"]`.
+ */
+interface MindooDBAppJsonSetPatch {
+    path: Array<string | number>;
+    value: unknown;
+}
+/**
+ * Removes the value at `path` from the document payload.
+ *
+ * For object properties this deletes the key; for list entries the host
+ * decides whether unset is supported and may reject the patch.
+ */
+interface MindooDBAppJsonUnsetPatch {
+    path: Array<string | number>;
+}
+/**
+ * Inserts one or more values into the list located at `path`.
+ *
+ * `index` is the insertion point within the current list, where `0` prepends
+ * and `list.length` appends. Existing entries at or after `index` shift right.
+ */
+interface MindooDBAppJsonListInsertPatch {
+    path: Array<string | number>;
+    index: number;
+    values: unknown[];
+}
+/**
+ * Deletes a contiguous run of entries from the list located at `path`.
+ *
+ * Removes `deleteCount` entries starting at `index`. Subsequent entries shift
+ * left to fill the gap.
+ */
+interface MindooDBAppJsonListDeletePatch {
+    path: Array<string | number>;
+    index: number;
+    deleteCount: number;
+}
+interface MindooDBAppJsonPatch {
+    /**
+     * Automerge heads of the document snapshot this JSON patch was authored
+     * against. Hosts can use this to apply order-sensitive edits at the original
+     * causal version and merge them with concurrent changes.
+     */
+    baseHeads?: string[];
+    set?: MindooDBAppJsonSetPatch[];
+    unset?: MindooDBAppJsonUnsetPatch[];
+    listInsert?: MindooDBAppJsonListInsertPatch[];
+    listDelete?: MindooDBAppJsonListDeletePatch[];
 }
 /**
  * Sparse patch payload used when updating an existing document.
@@ -233,6 +343,10 @@ interface MindooDBAppUpdateDocumentInput {
     set?: Record<string, unknown>;
     /** Top-level fields to remove from the document entirely. */
     unset?: string[];
+    /** Granular JSON operations to apply at document paths. */
+    json?: MindooDBAppJsonPatch;
+    /** Granular text edits to apply at document paths. */
+    text?: MindooDBAppTextPatch[];
 }
 /** Query used for history lookups at a specific timestamp. */
 interface MindooDBAppHistoryQuery {
@@ -244,17 +358,23 @@ interface MindooDBAppBridgeConnectOptions {
     targetOrigin?: string;
     connectTimeoutMs?: number;
 }
-/** Initial postMessage handshake sent from the app to the Administrator. */
+/** Initial postMessage handshake sent from the app to the Haven. */
 interface MindooDBAppBridgeConnectMessage {
     protocol: "mindoodb-app-bridge";
     type: "mindoodb-app:connect";
     launchId: string;
 }
-/** Handshake acknowledgement returned by the Administrator host. */
+/** Handshake acknowledgement returned by the Haven host. */
 interface MindooDBAppBridgeConnectedMessage {
     protocol: "mindoodb-app-bridge";
     type: "mindoodb-app:connected";
 }
+/** Handshake error returned when the Haven host rejects a launch. */
+interface MindooDBAppBridgeHandshakeErrorMessage {
+    protocol: "mindoodb-app-bridge";
+    type: "mindoodb-app:error";
+    error: string;
+}
 /** Structured error payload transported over bridge RPC or stream messages. */
 interface MindooDBAppBridgeErrorPayload {
     code: string;
@@ -336,7 +456,7 @@ interface MindooDBAppBridgeStreamError {
 }
 /** Union of all non-RPC stream transport messages. */
 type MindooDBAppBridgeStreamMessage = MindooDBAppBridgeStreamReadRequest | MindooDBAppBridgeStreamWriteRequest | MindooDBAppBridgeStreamCloseRequest | MindooDBAppBridgeStreamAbortRequest | MindooDBAppAttachmentChunk | MindooDBAppBridgeStreamAck | MindooDBAppBridgeStreamError;
-/** Host-pushed event emitted when the Administrator theme changes. */
+/** Host-pushed event emitted when the Haven theme changes. */
 interface MindooDBAppBridgeThemeChangedMessage {
     protocol: "mindoodb-app-bridge";
     kind: "theme-changed";
@@ -445,8 +565,12 @@ interface MindooDBAppDocumentApi {
     delete(docId: string): Promise<{
         ok: true;
     }>;
+    undelete(docId: string): Promise<{
+        ok: true;
+    }>;
     listHistory(docId: string): Promise<MindooDBAppDocumentHistoryEntry[]>;
     getAtTimestamp(docId: string, timestamp: number): Promise<MindooDBAppHistoricalDocument>;
+    getAtRevision(docId: string, revisionId: MindooDBAppDocumentRevisionId): Promise<MindooDBAppHistoricalDocument>;
 }
 type MindooDBAppViewEntryKind = "category" | "document";
 /** Unique document identity within a multi-source view. */
@@ -486,6 +610,7 @@ interface MindooDBAppViewNavigatorOpenOptions {
 interface MindooDBAppCreateViewNavigatorInput {
     databaseIds: string[];
     definition: MindooDBAppViewDefinition;
+    categorizationStyle?: MindooDBAppConfiguredViewCategorizationStyle;
     options?: MindooDBAppViewNavigatorOpenOptions;
 }
 /** @deprecated Use `MindooDBAppCreateViewNavigatorInput`. */
@@ -570,12 +695,13 @@ interface MindooDBAppViewNavigator {
 }
 /** Attachment operations exposed by an opened database handle. */
 interface MindooDBAppAttachmentApi {
-    list(docId: string): Promise<MindooDBAppAttachmentInfo[]>;
+    list(docId: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentInfo[]>;
     remove(docId: string, attachmentName: string): Promise<{
         ok: true;
     }>;
-    openReadStream(docId: string, attachmentName: string): Promise<MindooDBAppReadableAttachmentStream>;
+    openReadStream(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppReadableAttachmentStream>;
     openWriteStream(docId: string, attachmentName: string, contentType?: string): Promise<MindooDBAppWritableAttachmentStream>;
+    scan(docId: string, options?: MindooDBAppScanAttachmentOptions): Promise<MindooDBAppScanAttachmentResult>;
     preparePreviewSession(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentPreviewSession>;
     openPreview(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<{
         ok: true;
@@ -587,7 +713,7 @@ interface MindooDBAppDatabase {
     documents: MindooDBAppDocumentApi;
     attachments: MindooDBAppAttachmentApi;
 }
-/** Connected session between the running app and the Administrator host. */
+/** Connected session between the running app and the Haven host. */
 interface MindooDBAppSession {
     getLaunchContext(): Promise<MindooDBAppLaunchContext>;
     listDatabases(): Promise<MindooDBAppDatabaseInfo[]>;
@@ -606,4 +732,4 @@ interface MindooDBAppBridge {
     connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
 }
 
-export type { MindooDBAppDocumentListResult as $, MindooDBAppCapability as A, MindooDBAppConfiguredViewCategorizationStyle as B, MindooDBAppConfiguredViewColumn as C, MindooDBAppConfiguredViewColumnRole as D, MindooDBAppConfiguredViewExpressionMode as E, MindooDBAppConfiguredViewFieldExpression as F, MindooDBAppConfiguredViewFilterDefinition as G, MindooDBAppConfiguredViewFilterMode as H, MindooDBAppConfiguredViewFilterRule as I, MindooDBAppConfiguredViewFormulaExpression as J, MindooDBAppConfiguredViewFormulaFilterDefinition as K, MindooDBAppConfiguredViewPreviewMode as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewRuleFilterDefinition as N, MindooDBAppConfiguredViewRuleMatchMode as O, MindooDBAppConfiguredViewRuleOperator as P, MindooDBAppConfiguredViewValueExpression as Q, MindooDBAppCreateDocumentInput as R, MindooDBAppCreateViewInput as S, MindooDBAppCreateViewNavigatorInput as T, MindooDBAppDatabase as U, MindooDBAppDatabaseInfo as V, MindooDBAppDocument as W, MindooDBAppDocumentApi as X, MindooDBAppDocumentHeadCursorResult as Y, MindooDBAppDocumentHistoryEntry as Z, MindooDBAppDocumentListQuery as _, MindooDBAppBridge as a, MindooDBAppDocumentSummary as a0, MindooDBAppHistoricalDocument as a1, MindooDBAppHistoryQuery as a2, MindooDBAppHostTheme as a3, MindooDBAppLaunchContext as a4, MindooDBAppMenuAnchor as a5, MindooDBAppMenuApi as a6, MindooDBAppMenuCommandItem as a7, MindooDBAppMenuDismissReason as a8, MindooDBAppMenuDismissedResult as a9, MindooDBAppViewNavigatorOpenOptions as aA, MindooDBAppViewNavigatorPageOptions as aB, MindooDBAppViewNavigatorPageResult as aC, MindooDBAppViewNavigatorRangeQuery as aD, MindooDBAppViewNavigatorSelectionState as aE, MindooDBAppViewport as aF, MindooDBAppWritableAttachmentStream as aG, MindooDBAppMenuItem as aa, MindooDBAppMenuKind as ab, MindooDBAppMenuPlacement as ac, MindooDBAppMenuPointAnchor as ad, MindooDBAppMenuRect as ae, MindooDBAppMenuRectAnchor as af, MindooDBAppMenuSelectionResult as ag, MindooDBAppMenuSeparatorItem as ah, MindooDBAppReadableAttachmentStream as ai, MindooDBAppResolvedViewDefinition as aj, MindooDBAppResolvedViewSource as ak, MindooDBAppRuntime as al, MindooDBAppScopedDocId as am, MindooDBAppScopedDocumentSummary as an, MindooDBAppSession as ao, MindooDBAppShowMenuInput as ap, MindooDBAppShowMenuResult as aq, MindooDBAppThemeMode as ar, MindooDBAppUiPreferences as as, MindooDBAppUpdateDocumentInput as at, MindooDBAppViewCursorDocumentListResult as au, MindooDBAppViewCursorResult as av, MindooDBAppViewEntry as aw, MindooDBAppViewEntryKind as ax, MindooDBAppViewNavigator as ay, MindooDBAppViewNavigatorExpansionState as az, MindooDBAppAttachmentApi as b, MindooDBAppAttachmentChunk as c, MindooDBAppAttachmentInfo as d, MindooDBAppAttachmentPreviewOptions as e, MindooDBAppAttachmentPreviewSession as f, MindooDBAppBridgeConnectMessage as g, MindooDBAppBridgeConnectOptions as h, MindooDBAppBridgeConnectedMessage as i, MindooDBAppBridgeErrorPayload as j, MindooDBAppBridgePortMessage as k, MindooDBAppBridgeRpcError as l, MindooDBAppBridgeRpcMessage as m, MindooDBAppBridgeRpcRequest as n, MindooDBAppBridgeRpcSuccess as o, MindooDBAppBridgeStreamAbortRequest as p, MindooDBAppBridgeStreamAck as q, MindooDBAppBridgeStreamCloseRequest as r, MindooDBAppBridgeStreamError as s, MindooDBAppBridgeStreamMessage as t, MindooDBAppBridgeStreamOpenResult as u, MindooDBAppBridgeStreamReadRequest as v, MindooDBAppBridgeStreamWriteRequest as w, MindooDBAppBridgeThemeChangedMessage as x, MindooDBAppBridgeUiPreferencesChangedMessage as y, MindooDBAppBridgeViewportChangedMessage as z };
+export type { MindooDBAppDocumentListQuery as $, MindooDBAppBridgeThemeChangedMessage as A, MindooDBAppBridgeUiPreferencesChangedMessage as B, MindooDBAppBridgeViewportChangedMessage as C, MindooDBAppCapability as D, MindooDBAppConfiguredViewCategorizationStyle as E, MindooDBAppConfiguredViewColumn as F, MindooDBAppConfiguredViewColumnRole as G, MindooDBAppConfiguredViewExpressionMode as H, MindooDBAppConfiguredViewFieldExpression as I, MindooDBAppConfiguredViewFilterDefinition as J, MindooDBAppConfiguredViewFilterMode as K, MindooDBAppConfiguredViewFilterRule as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewFormulaExpression as N, MindooDBAppConfiguredViewFormulaFilterDefinition as O, MindooDBAppConfiguredViewPreviewMode as P, MindooDBAppConfiguredViewRuleFilterDefinition as Q, MindooDBAppConfiguredViewRuleMatchMode as R, MindooDBAppConfiguredViewRuleOperator as S, MindooDBAppConfiguredViewValueExpression as T, MindooDBAppCreateDocumentInput as U, MindooDBAppCreateViewInput as V, MindooDBAppCreateViewNavigatorInput as W, MindooDBAppDatabaseInfo as X, MindooDBAppDocumentApi as Y, MindooDBAppDocumentHeadCursorResult as Z, MindooDBAppDocumentHistoryEntry as _, MindooDBAppBridge as a, MindooDBAppDocumentListResult as a0, MindooDBAppDocumentRevisionId as a1, MindooDBAppDocumentScanPreset as a2, MindooDBAppDocumentSummary as a3, MindooDBAppHistoricalDocument as a4, MindooDBAppHistoryQuery as a5, MindooDBAppHostTheme as a6, MindooDBAppJsonListDeletePatch as a7, MindooDBAppJsonListInsertPatch as a8, MindooDBAppJsonPatch as a9, MindooDBAppShowMenuResult as aA, MindooDBAppTextEdit as aB, MindooDBAppTextPatch as aC, MindooDBAppThemeMode as aD, MindooDBAppUiPreferences as aE, MindooDBAppUpdateDocumentInput as aF, MindooDBAppViewCursorDocumentListResult as aG, MindooDBAppViewCursorResult as aH, MindooDBAppViewEntry as aI, MindooDBAppViewEntryKind as aJ, MindooDBAppViewNavigator as aK, MindooDBAppViewNavigatorExpansionState as aL, MindooDBAppViewNavigatorOpenOptions as aM, MindooDBAppViewNavigatorPageOptions as aN, MindooDBAppViewNavigatorPageResult as aO, MindooDBAppViewNavigatorRangeQuery as aP, MindooDBAppViewNavigatorSelectionState as aQ, MindooDBAppViewport as aR, MindooDBAppWritableAttachmentStream as aS, MindooDBAppJsonSetPatch as aa, MindooDBAppJsonUnsetPatch as ab, MindooDBAppLaunchContext as ac, MindooDBAppMenuAnchor as ad, MindooDBAppMenuApi as ae, MindooDBAppMenuCommandItem as af, MindooDBAppMenuDismissReason as ag, MindooDBAppMenuDismissedResult as ah, MindooDBAppMenuItem as ai, MindooDBAppMenuKind as aj, MindooDBAppMenuPlacement as ak, MindooDBAppMenuPointAnchor as al, MindooDBAppMenuRect as am, MindooDBAppMenuRectAnchor as an, MindooDBAppMenuSelectionResult as ao, MindooDBAppMenuSeparatorItem as ap, MindooDBAppReadableAttachmentStream as aq, MindooDBAppResolvedViewDefinition as ar, MindooDBAppResolvedViewSource as as, MindooDBAppRuntime as at, MindooDBAppScanAttachmentOptions as au, MindooDBAppScanAttachmentResult as av, MindooDBAppScopedDocId as aw, MindooDBAppScopedDocumentSummary as ax, MindooDBAppSession as ay, MindooDBAppShowMenuInput as az, MindooDBAppDatabase as b, MindooDBAppDocument as c, MindooDBAppAttachmentApi as d, MindooDBAppAttachmentChunk as e, MindooDBAppAttachmentInfo as f, MindooDBAppAttachmentPreviewOptions as g, MindooDBAppAttachmentPreviewSession as h, MindooDBAppBridgeConnectMessage as i, MindooDBAppBridgeConnectOptions as j, MindooDBAppBridgeConnectedMessage as k, MindooDBAppBridgeErrorPayload as l, MindooDBAppBridgeHandshakeErrorMessage as m, MindooDBAppBridgePortMessage as n, MindooDBAppBridgeRpcError as o, MindooDBAppBridgeRpcMessage as p, MindooDBAppBridgeRpcRequest as q, MindooDBAppBridgeRpcSuccess as r, MindooDBAppBridgeStreamAbortRequest as s, MindooDBAppBridgeStreamAck as t, MindooDBAppBridgeStreamCloseRequest as u, MindooDBAppBridgeStreamError as v, MindooDBAppBridgeStreamMessage as w, MindooDBAppBridgeStreamOpenResult as x, MindooDBAppBridgeStreamReadRequest as y, MindooDBAppBridgeStreamWriteRequest as z };

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.14",
+  "version": "0.0.17",
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "description": "MindooDB app SDK for building apps that connect to the Haven host bridge",
   "license": "ISC",
   "author": "Mindoo GmbH",
@@ -32,20 +35,19 @@
       "default": "./dist/testing/index.js"
     }
   },
-  "scripts": {
-    "build": "tsup src/index.ts src/testing/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm run test"
-  },
   "dependencies": {
-    "mindoodb-view-language": "0.0.10"
+    "mindoodb-view-language": "0.0.12"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
+    "@types/node": "25.5.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/testing/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}