mindoodb-app-sdk 0.0.20 → 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1565 @@
1
+ import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition } from 'mindoodb-view-language';
2
+
3
+ /** Launch target used by the Haven when opening an app. */
4
+ type MindooDBAppRuntime = "iframe" | "window";
5
+ /** Theme mode currently active in the Haven host UI. */
6
+ type MindooDBAppThemeMode = "light" | "dark";
7
+ /** Host theme snapshot exposed to running apps. */
8
+ interface MindooDBAppHostTheme {
9
+ mode: MindooDBAppThemeMode;
10
+ preset: string;
11
+ }
12
+ /** Iframe viewport dimensions reported by the Haven host. */
13
+ interface MindooDBAppViewport {
14
+ width: number;
15
+ height: number;
16
+ }
17
+ /** Host-controlled UI preferences exposed to embedded apps. */
18
+ interface MindooDBAppUiPreferences {
19
+ iosMultitaskingOptimized: boolean;
20
+ }
21
+ /** Saved categorization mode for Haven-managed view mappings delivered at launch time. */
22
+ type MindooDBAppConfiguredViewCategorizationStyle = "document_then_category" | "category_then_document";
23
+ /** Preferred preview layout for a Haven-managed view mapping. */
24
+ type MindooDBAppConfiguredViewPreviewMode = "tree" | "table";
25
+ /** Column role used by Haven-managed view mappings. */
26
+ type MindooDBAppConfiguredViewColumnRole = "category" | "sort" | "display" | "total";
27
+ /** Filter authoring mode used by Haven-managed view mappings. */
28
+ type MindooDBAppConfiguredViewFilterMode = "rules" | "formula";
29
+ /** Rule match mode used by visual-rule filters. */
30
+ type MindooDBAppConfiguredViewRuleMatchMode = "all" | "any";
31
+ /** Visual-rule operator supported by Haven-managed view mappings. */
32
+ type MindooDBAppConfiguredViewRuleOperator = "eq" | "neq" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "exists" | "notExists";
33
+ /** Field/formula authoring modes for Haven-managed view columns. */
34
+ type MindooDBAppConfiguredViewExpressionMode = "field" | "formula";
35
+ /** One visual filter rule inside a Haven-managed view mapping. */
36
+ interface MindooDBAppConfiguredViewFilterRule {
37
+ id: string;
38
+ field: string;
39
+ operator: MindooDBAppConfiguredViewRuleOperator;
40
+ value?: string;
41
+ }
42
+ /** Field-based value expression used by Haven-managed view mappings. */
43
+ interface MindooDBAppConfiguredViewFieldExpression {
44
+ mode: "field";
45
+ field: string;
46
+ }
47
+ /** Formula-based value expression used by Haven-managed view mappings. */
48
+ interface MindooDBAppConfiguredViewFormulaExpression {
49
+ mode: "formula";
50
+ expression: MindooDBAppExpression;
51
+ }
52
+ /** Column expression authoring shape used by Haven-managed view mappings. */
53
+ type MindooDBAppConfiguredViewValueExpression = MindooDBAppConfiguredViewFieldExpression | MindooDBAppConfiguredViewFormulaExpression;
54
+ /** Rule-based filter stored by Haven for app-owned view mappings. */
55
+ interface MindooDBAppConfiguredViewRuleFilterDefinition {
56
+ mode: "rules";
57
+ match: MindooDBAppConfiguredViewRuleMatchMode;
58
+ rules: MindooDBAppConfiguredViewFilterRule[];
59
+ }
60
+ /** Formula-based filter stored by Haven for app-owned view mappings. */
61
+ interface MindooDBAppConfiguredViewFormulaFilterDefinition {
62
+ mode: "formula";
63
+ expression: MindooDBAppBooleanExpression;
64
+ }
65
+ /** Full filter authoring shape stored for Haven-managed app view mappings. */
66
+ type MindooDBAppConfiguredViewFilterDefinition = MindooDBAppConfiguredViewRuleFilterDefinition | MindooDBAppConfiguredViewFormulaFilterDefinition;
67
+ /** Column definition stored for a Haven-managed app view mapping. */
68
+ interface MindooDBAppConfiguredViewColumn {
69
+ id: string;
70
+ title: string;
71
+ name: string;
72
+ role: MindooDBAppConfiguredViewColumnRole;
73
+ expression: MindooDBAppConfiguredViewValueExpression;
74
+ sorting: MindooDBAppViewSortDirection;
75
+ totalMode: MindooDBAppViewTotalMode;
76
+ hidden: boolean;
77
+ }
78
+ /** One resolved source binding for an app-owned Haven view mapping. */
79
+ interface MindooDBAppResolvedViewSource {
80
+ origin: string;
81
+ databaseId: string;
82
+ title: string;
83
+ targetMode: "local" | "server";
84
+ connectionId?: string;
85
+ tenantId: string;
86
+ databaseName: string;
87
+ }
88
+ /** Full Haven-managed view mapping delivered to the running application at launch time. */
89
+ interface MindooDBAppResolvedViewDefinition {
90
+ id: string;
91
+ description?: string;
92
+ categorizationStyle: MindooDBAppConfiguredViewCategorizationStyle;
93
+ previewMode: MindooDBAppConfiguredViewPreviewMode;
94
+ sources: MindooDBAppResolvedViewSource[];
95
+ filter: MindooDBAppConfiguredViewFilterDefinition;
96
+ columns: MindooDBAppConfiguredViewColumn[];
97
+ }
98
+ /** Permission/capability flags exposed for a database binding inside the app session. */
99
+ type MindooDBAppCapability = "read" | "create" | "update" | "delete" | "history" | "attachments" | "views";
100
+ /** Metadata about the current app launch supplied by the Haven host. */
101
+ interface MindooDBAppLaunchContext {
102
+ appId: string;
103
+ appInstanceId: string;
104
+ appVersion?: string;
105
+ launchId: string;
106
+ runtime: MindooDBAppRuntime;
107
+ theme: MindooDBAppHostTheme;
108
+ viewport: MindooDBAppViewport | null;
109
+ uiPreferences: MindooDBAppUiPreferences;
110
+ /**
111
+ * The host's currently selected UI language as a BCP-47 language tag (e.g.
112
+ * `"en"`, `"de"`). Apps should map this to their own set of supported
113
+ * locales and fall back to their default when the tag is unknown. Subscribe
114
+ * to {@link MindooDBAppSession.onLocaleChange} to react to live changes.
115
+ */
116
+ locale: string;
117
+ tenantId?: string;
118
+ preferredDatabaseId?: string;
119
+ /**
120
+ * Epoch-millisecond cutoff when the host opened app databases in time travel
121
+ * read-only mode. Absent/null means the app is looking at live data.
122
+ */
123
+ timeTravelDate?: number | null;
124
+ user: {
125
+ id: string;
126
+ username: string;
127
+ };
128
+ licensedProducts?: string[];
129
+ launchParameters: Record<string, string>;
130
+ databases: MindooDBAppDatabaseInfo[];
131
+ views: MindooDBAppResolvedViewDefinition[];
132
+ }
133
+ /** Attachment metadata returned by the attachment APIs. */
134
+ interface MindooDBAppAttachmentInfo {
135
+ attachmentId: string;
136
+ fileName: string;
137
+ mimeType: string;
138
+ size: number;
139
+ }
140
+ /** Preview modes supported by the Haven-hosted attachment preview dialog. */
141
+ type MindooDBAppAttachmentPreviewMode = "image" | "pdf" | "text" | "markdown" | "docx" | "pptx" | "spreadsheet" | "video" | "audio";
142
+ /** Optional parameters for opening an attachment preview in Haven. */
143
+ interface MindooDBAppAttachmentPreviewOptions {
144
+ /** Historical snapshot timestamp previously obtained from `documents.history.getAtTimestamp()`. */
145
+ timestamp?: number;
146
+ /** Stable revision id previously obtained from `documents.listHistory()`. */
147
+ revisionId?: MindooDBAppDocumentRevisionId;
148
+ }
149
+ type MindooDBAppDocumentScanPreset = "auto" | "a4-portrait" | "a4-landscape" | "letter-portrait" | "letter-landscape";
150
+ interface MindooDBAppScanAttachmentOptions {
151
+ defaultFileName?: string;
152
+ preset?: MindooDBAppDocumentScanPreset;
153
+ mimeType?: "image/jpeg" | "image/png" | "application/pdf";
154
+ }
155
+ interface MindooDBAppScanAttachmentResult {
156
+ ok: boolean;
157
+ attachment?: MindooDBAppAttachmentInfo | null;
158
+ }
159
+ /** Resolved Haven preview session prepared for opening in a separate tab or window. */
160
+ interface MindooDBAppAttachmentPreviewSession {
161
+ sessionId: string;
162
+ previewUrl: string;
163
+ }
164
+ /** Database entry visible to the app during launch and database listing. */
165
+ interface MindooDBAppDatabaseInfo {
166
+ id: string;
167
+ title: string;
168
+ role?: string;
169
+ capabilities: MindooDBAppCapability[];
170
+ }
171
+ /** Lightweight document row returned by list operations. */
172
+ interface MindooDBAppDocumentSummary {
173
+ id: string;
174
+ data?: Record<string, unknown>;
175
+ attachmentCount?: number;
176
+ createdAt?: string;
177
+ updatedAt?: string;
178
+ identityLabel?: string;
179
+ publicKeyFingerprint?: string;
180
+ isDeleted?: boolean;
181
+ }
182
+ /** Fully loaded document returned by `get()`, `create()`, or `update()`. */
183
+ interface MindooDBAppDocument {
184
+ id: string;
185
+ data: Record<string, unknown>;
186
+ /** Current Automerge heads for causal text edit reconciliation. */
187
+ heads?: string[];
188
+ attachments?: MindooDBAppAttachmentInfo[];
189
+ createdAt?: string;
190
+ updatedAt?: string;
191
+ }
192
+ /** Opaque persisted id for a document revision in the MindooDB DAG. */
193
+ type MindooDBAppDocumentRevisionId = string;
194
+ /** One entry in the document history timeline. */
195
+ interface MindooDBAppDocumentHistoryEntry {
196
+ revisionId: MindooDBAppDocumentRevisionId;
197
+ timestamp: number;
198
+ heads?: string[];
199
+ publicKey: string;
200
+ publicKeyFingerprint?: string;
201
+ identityLabel?: string;
202
+ isDeleted: boolean;
203
+ isCurrent: boolean;
204
+ summary?: string;
205
+ }
206
+ /** Historical snapshot returned for a document at a specific timestamp. */
207
+ interface MindooDBAppHistoricalDocument {
208
+ id: string;
209
+ revisionId?: MindooDBAppDocumentRevisionId;
210
+ timestamp: number;
211
+ heads?: string[];
212
+ state: "missing" | "deleted" | "exists";
213
+ data: Record<string, unknown> | null;
214
+ attachments?: MindooDBAppAttachmentInfo[];
215
+ attachmentSnapshotRevisionId?: MindooDBAppDocumentRevisionId | null;
216
+ }
217
+ /** Query options for paging through changefeed-backed document listings in a database. */
218
+ interface MindooDBAppDocumentListQuery {
219
+ /**
220
+ * Opaque changefeed checkpoint previously returned as `nextCursor`.
221
+ * Omit or pass `null` to start from the beginning of the changefeed.
222
+ */
223
+ cursor?: string | null;
224
+ /** Maximum number of matches to return (host default: 50). */
225
+ limit?: number;
226
+ /** Skip this many matching entries after the cursor without loading their bodies. */
227
+ skip?: number;
228
+ /**
229
+ * Deletion-state filter (default `"existing"`). Use `"all"` for derived
230
+ * indexes so deletions become visible and can be removed downstream.
231
+ */
232
+ status?: "all" | "existing" | "deleted";
233
+ /** Return only `{ id, isDeleted }` per row — the fastest listing mode. */
234
+ metadataOnly?: boolean;
235
+ /** Project specific top-level JSON fields into `data` instead of the full document. */
236
+ fields?: string[];
237
+ /** Simple equality filter on top-level document data fields. */
238
+ filter?: Record<string, unknown>;
239
+ }
240
+ /** Paged result returned by `documents.list()`. */
241
+ interface MindooDBAppDocumentListResult {
242
+ items: MindooDBAppDocumentSummary[];
243
+ /**
244
+ * Checkpoint reached by this page — persist it and pass it back as
245
+ * `cursor` to resume. `null` when there were no changes after the
246
+ * supplied cursor.
247
+ */
248
+ nextCursor: string | null;
249
+ }
250
+ /** Latest known changefeed cursor for a database. */
251
+ interface MindooDBAppDocumentHeadCursorResult {
252
+ cursor: string | null;
253
+ }
254
+ /** Opaque cursor representing the DB state reflected in a bridge-built view snapshot. */
255
+ interface MindooDBAppViewCursorResult {
256
+ viewCursor: string | null;
257
+ }
258
+ /** Lightweight document row returned by multi-source view-cursor delta queries. */
259
+ interface MindooDBAppScopedDocumentSummary extends MindooDBAppDocumentSummary {
260
+ origin: string;
261
+ databaseId: string;
262
+ }
263
+ /** Result returned when querying document changes since a view snapshot cursor. */
264
+ interface MindooDBAppViewCursorDocumentListResult {
265
+ items: MindooDBAppScopedDocumentSummary[];
266
+ nextCursor: string | null;
267
+ }
268
+ /**
269
+ * Tier of an access-control decision. `tier1` decisions are fully determined by
270
+ * the signer/policy; `tier2` decisions depend on document content rules.
271
+ */
272
+ type MindooDBAppAccessTier = "tier1" | "tier2";
273
+ /**
274
+ * Result of a non-throwing write-access prediction (`documents.canCreate`,
275
+ * `canChange`, `canDelete`, `canUndelete`). `allowed === true` means the host
276
+ * predicts the operation would succeed for the current app and identity,
277
+ * accounting for the app's granted capabilities, time-travel read-only mode,
278
+ * and the database's MindooDB write access policy. `reason` is a human-readable
279
+ * explanation suitable for tooltips/audit logs.
280
+ */
281
+ interface MindooDBAppAccessDecision {
282
+ allowed: boolean;
283
+ reason: string;
284
+ tier: MindooDBAppAccessTier;
285
+ matchedRuleId?: string;
286
+ }
287
+ /**
288
+ * Payload used when creating a new document.
289
+ *
290
+ * `set` becomes the initial top-level document state, mirroring the update
291
+ * API's field-assignment language while still creating a brand-new document.
292
+ */
293
+ interface MindooDBAppCreateDocumentInput {
294
+ set: Record<string, unknown>;
295
+ /** Optional named document key. Defaults to `"default"` when omitted. */
296
+ decryptionKeyId?: string;
297
+ /**
298
+ * Optional caller-provided document id. When omitted, MindooDB generates a
299
+ * UUID7. When provided, the id must match `^[A-Za-z][A-Za-z0-9_]*$`: the
300
+ * first character is an ASCII letter and subsequent characters may be ASCII
301
+ * letters, ASCII digits, or `_`.
302
+ *
303
+ * If a document with this id already exists locally, MindooDB returns the
304
+ * existing document instead of creating a new one (idempotent create), and
305
+ * the values in `set` are NOT applied. Caller-provided ids are useful for
306
+ * loading a known well-known document directly without first building a
307
+ * view, and for migrations that want to preserve external ids.
308
+ *
309
+ * Documents created with the same caller-provided id on independent replicas
310
+ * share Automerge ancestry, so subsequent edits on either replica still
311
+ * merge correctly when the replicas sync.
312
+ */
313
+ id?: string;
314
+ }
315
+ interface MindooDBAppTextEdit {
316
+ index: number;
317
+ deleteCount: number;
318
+ insert?: string;
319
+ }
320
+ interface MindooDBAppTextPatch {
321
+ path: Array<string | number>;
322
+ baseHeads?: string[];
323
+ edits: MindooDBAppTextEdit[];
324
+ }
325
+ type MindooDBAppRichTextScalar = string | number | boolean | null;
326
+ interface MindooDBAppRichTextImmutableString {
327
+ type: "immutableString";
328
+ value: string;
329
+ }
330
+ type MindooDBAppRichTextMaterializeValue = MindooDBAppRichTextScalar | MindooDBAppRichTextImmutableString | MindooDBAppRichTextMaterializeValue[] | {
331
+ [key: string]: MindooDBAppRichTextMaterializeValue;
332
+ };
333
+ interface MindooDBAppRichTextTextSpan {
334
+ type: "text";
335
+ value: string;
336
+ marks?: Record<string, MindooDBAppRichTextMaterializeValue>;
337
+ }
338
+ interface MindooDBAppRichTextBlockSpan {
339
+ type: "block";
340
+ value: Record<string, MindooDBAppRichTextMaterializeValue>;
341
+ }
342
+ type MindooDBAppRichTextSpan = MindooDBAppRichTextTextSpan | MindooDBAppRichTextBlockSpan;
343
+ interface MindooDBAppRichTextMarkRange {
344
+ index: number;
345
+ length: number;
346
+ marks: Record<string, MindooDBAppRichTextMaterializeValue>;
347
+ }
348
+ interface MindooDBAppRichTextSpliceStep {
349
+ type: "splice";
350
+ index: number;
351
+ deleteCount: number;
352
+ insert?: string;
353
+ marks?: MindooDBAppRichTextMarkRange[];
354
+ }
355
+ type MindooDBAppRichTextStep = MindooDBAppRichTextSpliceStep;
356
+ interface MindooDBAppRichTextStepPatch {
357
+ /** Path to the Automerge rich-text field inside the document payload. */
358
+ path: Array<string | number>;
359
+ /** Automerge heads of the document state these positional steps were based on. */
360
+ baseHeads?: string[];
361
+ /** Ordered rich-text positional operations to apply with Automerge splice/mark. */
362
+ steps: MindooDBAppRichTextStep[];
363
+ }
364
+ interface MindooDBAppRichTextPatch {
365
+ /** Path to the Automerge rich-text field inside the document payload. */
366
+ path: Array<string | number>;
367
+ /** Automerge heads of the document state this rich-text snapshot was based on. */
368
+ baseHeads?: string[];
369
+ /** Full JSON-safe span snapshot to apply with Automerge `updateSpans`. */
370
+ spans?: MindooDBAppRichTextSpan[];
371
+ /** Ordered snapshots to apply one-by-one so each `updateSpans` diff stays transaction-sized. */
372
+ spansSequence?: MindooDBAppRichTextSpan[][];
373
+ /** Optional Automerge `updateSpans` configuration, kept JSON-safe over the bridge. */
374
+ updateSpansConfig?: Record<string, unknown>;
375
+ }
376
+ interface MindooDBAppRichTextSnapshot {
377
+ path: Array<string | number>;
378
+ heads?: string[];
379
+ spans: MindooDBAppRichTextSpan[];
380
+ }
381
+ interface MindooDBAppRichTextGetOptions {
382
+ /** Stable revision id previously obtained from `documents.listHistory()`. */
383
+ revisionId?: MindooDBAppDocumentRevisionId;
384
+ }
385
+ /** Binary Automerge snapshot of the full internal document. */
386
+ interface MindooDBAppAutomergeSnapshot {
387
+ binary: Uint8Array;
388
+ heads: string[];
389
+ }
390
+ interface MindooDBAppAutomergeGetOptions {
391
+ /** Stable revision id previously obtained from `documents.listHistory()`. */
392
+ revisionId?: MindooDBAppDocumentRevisionId;
393
+ }
394
+ /** Raw Automerge change bytes produced by a local replica. */
395
+ interface MindooDBAppAutomergeChangesPatch {
396
+ /** Heads the client had when authoring `changes`; optional, for correlation only. */
397
+ baseHeads?: string[];
398
+ /**
399
+ * Heads of the local replica after authoring `changes`. When provided, the
400
+ * apply response includes `changesSince` for incremental reconciliation.
401
+ */
402
+ replicaHeads?: string[];
403
+ /** Change bytes from `Automerge.getChangesSince`; merged into Haven's current doc. */
404
+ changes: Uint8Array[];
405
+ }
406
+ /** Incremental catch-up bytes for a local replica after an apply merge. */
407
+ interface MindooDBAppAutomergeChangesSince {
408
+ /** Echo of `replicaHeads` from the request. */
409
+ sinceHeads: string[];
410
+ /** Changes on the merged canonical doc that the replica is missing. */
411
+ changes: Uint8Array[];
412
+ }
413
+ interface MindooDBAppAutomergePatchResult {
414
+ document: MindooDBAppDocument;
415
+ heads: string[];
416
+ /**
417
+ * Present when the request included `replicaHeads`. Apply locally with
418
+ * `Automerge.applyChanges` instead of reloading a full snapshot.
419
+ */
420
+ changesSince?: MindooDBAppAutomergeChangesSince;
421
+ }
422
+ /**
423
+ * Sets the value at `path` inside the document payload.
424
+ *
425
+ * Creates the field if it does not exist, or replaces the existing value.
426
+ * `path` addresses a property using object keys and list indices, for example
427
+ * `["workbook", "worksheetsById", "ws-1", "title"]`.
428
+ */
429
+ interface MindooDBAppJsonSetPatch {
430
+ path: Array<string | number>;
431
+ value: unknown;
432
+ }
433
+ /**
434
+ * Removes the value at `path` from the document payload.
435
+ *
436
+ * For object properties this deletes the key; for list entries the host
437
+ * decides whether unset is supported and may reject the patch.
438
+ */
439
+ interface MindooDBAppJsonUnsetPatch {
440
+ path: Array<string | number>;
441
+ }
442
+ /**
443
+ * Inserts one or more values into the list located at `path`.
444
+ *
445
+ * `index` is the insertion point within the current list, where `0` prepends
446
+ * and `list.length` appends. Existing entries at or after `index` shift right.
447
+ */
448
+ interface MindooDBAppJsonListInsertPatch {
449
+ path: Array<string | number>;
450
+ index: number;
451
+ values: unknown[];
452
+ }
453
+ /**
454
+ * Deletes a contiguous run of entries from the list located at `path`.
455
+ *
456
+ * Removes `deleteCount` entries starting at `index`. Subsequent entries shift
457
+ * left to fill the gap.
458
+ */
459
+ interface MindooDBAppJsonListDeletePatch {
460
+ path: Array<string | number>;
461
+ index: number;
462
+ deleteCount: number;
463
+ }
464
+ /**
465
+ * Splices text at `path` using Automerge text semantics.
466
+ */
467
+ interface MindooDBAppJsonTextSplicePatch {
468
+ path: Array<string | number>;
469
+ index: number;
470
+ deleteCount: number;
471
+ insert?: string;
472
+ }
473
+ /**
474
+ * Applies one or more marks to a text range at `path`.
475
+ */
476
+ interface MindooDBAppJsonTextMarkPatch {
477
+ path: Array<string | number>;
478
+ index: number;
479
+ length: number;
480
+ marks: Record<string, MindooDBAppRichTextMaterializeValue>;
481
+ }
482
+ /**
483
+ * Removes marks from a text range at `path`.
484
+ */
485
+ interface MindooDBAppJsonTextUnmarkPatch {
486
+ path: Array<string | number>;
487
+ index: number;
488
+ length: number;
489
+ names: string[];
490
+ }
491
+ interface MindooDBAppJsonPatch {
492
+ /**
493
+ * Automerge heads of the document snapshot this JSON patch was authored
494
+ * against. Hosts can use this to apply order-sensitive edits at the original
495
+ * causal version and merge them with concurrent changes.
496
+ */
497
+ baseHeads?: string[];
498
+ set?: MindooDBAppJsonSetPatch[];
499
+ unset?: MindooDBAppJsonUnsetPatch[];
500
+ listInsert?: MindooDBAppJsonListInsertPatch[];
501
+ listDelete?: MindooDBAppJsonListDeletePatch[];
502
+ textSplice?: MindooDBAppJsonTextSplicePatch[];
503
+ textMark?: MindooDBAppJsonTextMarkPatch[];
504
+ textUnmark?: MindooDBAppJsonTextUnmarkPatch[];
505
+ }
506
+ /**
507
+ * Sparse patch payload used when updating an existing document.
508
+ *
509
+ * Prefer targeted `set` / `unset` operations over whole-document rewrites so
510
+ * MindooDB can preserve more meaningful change history and Automerge can merge
511
+ * smaller, more intentional updates.
512
+ */
513
+ interface MindooDBAppUpdateDocumentInput {
514
+ /** Top-level fields to assign on the document. */
515
+ set?: Record<string, unknown>;
516
+ /** Top-level fields to remove from the document entirely. */
517
+ unset?: string[];
518
+ /** Granular JSON operations to apply at document paths. */
519
+ json?: MindooDBAppJsonPatch;
520
+ /** Granular text edits to apply at document paths. */
521
+ text?: MindooDBAppTextPatch[];
522
+ /** Rich-text span snapshots to apply at document paths. */
523
+ richText?: MindooDBAppRichTextPatch[];
524
+ /** Rich-text positional steps to apply at document paths. */
525
+ richTextSteps?: MindooDBAppRichTextStepPatch[];
526
+ }
527
+ /** Query used for history lookups at a specific timestamp. */
528
+ interface MindooDBAppHistoryQuery {
529
+ timestamp: number;
530
+ }
531
+ /** Optional parameters for establishing the app bridge connection. */
532
+ interface MindooDBAppBridgeConnectOptions {
533
+ /**
534
+ * Launch id issued by Haven. Defaults to the `mindoodbAppLaunchId` query
535
+ * parameter that Haven appends to the app URL.
536
+ */
537
+ launchId?: string;
538
+ /**
539
+ * Origin the handshake `postMessage` is sent to (default `"*"`). Pin this
540
+ * to the Haven origin when it is known.
541
+ */
542
+ targetOrigin?: string;
543
+ /** How long to wait for the host to answer the handshake before rejecting (default 10000 ms). */
544
+ connectTimeoutMs?: number;
545
+ }
546
+ /** Initial postMessage handshake sent from the app to the Haven. */
547
+ interface MindooDBAppBridgeConnectMessage {
548
+ protocol: "mindoodb-app-bridge";
549
+ type: "mindoodb-app:connect";
550
+ launchId: string;
551
+ }
552
+ /** Handshake acknowledgement returned by the Haven host. */
553
+ interface MindooDBAppBridgeConnectedMessage {
554
+ protocol: "mindoodb-app-bridge";
555
+ type: "mindoodb-app:connected";
556
+ }
557
+ /** Handshake error returned when the Haven host rejects a launch. */
558
+ interface MindooDBAppBridgeHandshakeErrorMessage {
559
+ protocol: "mindoodb-app-bridge";
560
+ type: "mindoodb-app:error";
561
+ error: string;
562
+ }
563
+ /** Structured error payload transported over bridge RPC or stream messages. */
564
+ interface MindooDBAppBridgeErrorPayload {
565
+ code: string;
566
+ message: string;
567
+ }
568
+ /** Request envelope used by the port-based RPC transport. */
569
+ interface MindooDBAppBridgeRpcRequest<TParams = unknown> {
570
+ protocol: "mindoodb-app-bridge";
571
+ kind: "request";
572
+ id: string;
573
+ method: string;
574
+ params: TParams;
575
+ }
576
+ /** Successful RPC response envelope. */
577
+ interface MindooDBAppBridgeRpcSuccess<TResult = unknown> {
578
+ protocol: "mindoodb-app-bridge";
579
+ kind: "success";
580
+ id: string;
581
+ result: TResult;
582
+ }
583
+ /** Failed RPC response envelope. */
584
+ interface MindooDBAppBridgeRpcError {
585
+ protocol: "mindoodb-app-bridge";
586
+ kind: "error";
587
+ id: string;
588
+ error: MindooDBAppBridgeErrorPayload;
589
+ }
590
+ /** Union of all RPC-level bridge messages. */
591
+ type MindooDBAppBridgeRpcMessage = MindooDBAppBridgeRpcRequest | MindooDBAppBridgeRpcSuccess | MindooDBAppBridgeRpcError;
592
+ /** Result returned when the host opens a streamed attachment channel. */
593
+ interface MindooDBAppBridgeStreamOpenResult {
594
+ streamId: string;
595
+ }
596
+ /** Request asking the host for the next chunk on a read stream. */
597
+ interface MindooDBAppBridgeStreamReadRequest {
598
+ protocol: "mindoodb-app-bridge";
599
+ kind: "stream-read";
600
+ streamId: string;
601
+ }
602
+ /** Request sending one chunk over a write stream. */
603
+ interface MindooDBAppBridgeStreamWriteRequest {
604
+ protocol: "mindoodb-app-bridge";
605
+ kind: "stream-write";
606
+ streamId: string;
607
+ chunk: ArrayBuffer;
608
+ }
609
+ /** Request closing a stream gracefully. */
610
+ interface MindooDBAppBridgeStreamCloseRequest {
611
+ protocol: "mindoodb-app-bridge";
612
+ kind: "stream-close";
613
+ streamId: string;
614
+ }
615
+ /** Request aborting a stream due to cancellation or failure. */
616
+ interface MindooDBAppBridgeStreamAbortRequest {
617
+ protocol: "mindoodb-app-bridge";
618
+ kind: "stream-abort";
619
+ streamId: string;
620
+ }
621
+ /** Streamed attachment payload delivered over the message port. */
622
+ interface MindooDBAppAttachmentChunk {
623
+ protocol: "mindoodb-app-bridge";
624
+ kind: "stream-chunk";
625
+ streamId: string;
626
+ chunk?: ArrayBuffer;
627
+ done: boolean;
628
+ }
629
+ /** Host acknowledgement for a write/close/abort stream request. */
630
+ interface MindooDBAppBridgeStreamAck {
631
+ protocol: "mindoodb-app-bridge";
632
+ kind: "stream-ack";
633
+ streamId: string;
634
+ }
635
+ /** Stream-level error message. */
636
+ interface MindooDBAppBridgeStreamError {
637
+ protocol: "mindoodb-app-bridge";
638
+ kind: "stream-error";
639
+ streamId: string;
640
+ error: MindooDBAppBridgeErrorPayload;
641
+ }
642
+ /** Union of all non-RPC stream transport messages. */
643
+ type MindooDBAppBridgeStreamMessage = MindooDBAppBridgeStreamReadRequest | MindooDBAppBridgeStreamWriteRequest | MindooDBAppBridgeStreamCloseRequest | MindooDBAppBridgeStreamAbortRequest | MindooDBAppAttachmentChunk | MindooDBAppBridgeStreamAck | MindooDBAppBridgeStreamError;
644
+ /** Host-pushed event emitted when the Haven theme changes. */
645
+ interface MindooDBAppBridgeThemeChangedMessage {
646
+ protocol: "mindoodb-app-bridge";
647
+ kind: "theme-changed";
648
+ theme: MindooDBAppHostTheme;
649
+ }
650
+ /** Host-pushed event emitted when the Haven iframe viewport changes. */
651
+ interface MindooDBAppBridgeViewportChangedMessage {
652
+ protocol: "mindoodb-app-bridge";
653
+ kind: "viewport-changed";
654
+ viewport: MindooDBAppViewport;
655
+ }
656
+ /** Host-pushed event emitted when host-controlled UI preferences change. */
657
+ interface MindooDBAppBridgeUiPreferencesChangedMessage {
658
+ protocol: "mindoodb-app-bridge";
659
+ kind: "ui-preferences-changed";
660
+ uiPreferences: MindooDBAppUiPreferences;
661
+ }
662
+ /** Host-pushed event emitted when the Haven UI language changes. */
663
+ interface MindooDBAppBridgeLocaleChangedMessage {
664
+ protocol: "mindoodb-app-bridge";
665
+ kind: "locale-changed";
666
+ /** BCP-47 language tag of the newly selected host locale (e.g. `"de"`). */
667
+ locale: string;
668
+ }
669
+ /**
670
+ * Host-pushed event carrying a changed live-query result.
671
+ *
672
+ * The host only sends this when the result fingerprint actually changed
673
+ * (or after an explicit `refresh()`), so bursts of writes produce at most
674
+ * one coalesced push per re-evaluation.
675
+ */
676
+ interface MindooDBAppBridgeQueryResultMessage {
677
+ protocol: "mindoodb-app-bridge";
678
+ kind: "query-result";
679
+ subscriptionId: string;
680
+ result: MindooDBAppQueryResult;
681
+ }
682
+ /**
683
+ * Host-pushed event fired after the view behind a navigator applied a
684
+ * change batch. The navigator surface (entries, counts, positions) may
685
+ * have changed; apps typically re-read the visible page.
686
+ */
687
+ interface MindooDBAppBridgeViewChangedMessage {
688
+ protocol: "mindoodb-app-bridge";
689
+ kind: "view-changed";
690
+ navigatorId: string;
691
+ stats: MindooDBAppViewUpdateStats;
692
+ }
693
+ /** Any message that can travel across the dedicated bridge MessagePort. */
694
+ type MindooDBAppBridgePortMessage = MindooDBAppBridgeRpcMessage | MindooDBAppBridgeStreamMessage | MindooDBAppBridgeThemeChangedMessage | MindooDBAppBridgeViewportChangedMessage | MindooDBAppBridgeUiPreferencesChangedMessage | MindooDBAppBridgeLocaleChangedMessage | MindooDBAppBridgeQueryResultMessage | MindooDBAppBridgeViewChangedMessage;
695
+ /** Placement hint for a host-rendered overlay menu. */
696
+ type MindooDBAppMenuPlacement = "auto" | "bottom-start" | "bottom-end" | "top-start" | "top-end" | "right-start" | "left-start";
697
+ /** Semantic hint allowing Haven to tune menu behavior or styling. */
698
+ type MindooDBAppMenuKind = "context" | "dropdown" | "picker";
699
+ /** Rectangle expressed in app-viewport coordinates. */
700
+ interface MindooDBAppMenuRect {
701
+ left: number;
702
+ top: number;
703
+ width: number;
704
+ height: number;
705
+ }
706
+ /** Point anchor used for context menus or other click-triggered overlays. */
707
+ interface MindooDBAppMenuPointAnchor {
708
+ type: "point";
709
+ x: number;
710
+ y: number;
711
+ }
712
+ /** Rectangle anchor used for toolbar menus or picker buttons. */
713
+ interface MindooDBAppMenuRectAnchor {
714
+ type: "rect";
715
+ rect: MindooDBAppMenuRect;
716
+ }
717
+ /** Anchor describing where the host should position the rendered menu. */
718
+ type MindooDBAppMenuAnchor = MindooDBAppMenuPointAnchor | MindooDBAppMenuRectAnchor;
719
+ /** Visual separator between menu groups. */
720
+ interface MindooDBAppMenuSeparatorItem {
721
+ separator: true;
722
+ }
723
+ /** One actionable entry in a structured host-rendered menu. */
724
+ interface MindooDBAppMenuCommandItem {
725
+ id: string;
726
+ label: string;
727
+ enabled?: boolean;
728
+ destructive?: boolean;
729
+ checked?: boolean;
730
+ items?: MindooDBAppMenuItem[];
731
+ }
732
+ /** Structured menu item transported over the app bridge. */
733
+ type MindooDBAppMenuItem = MindooDBAppMenuSeparatorItem | MindooDBAppMenuCommandItem;
734
+ /** Request payload for a host-rendered overlay menu. */
735
+ interface MindooDBAppShowMenuInput {
736
+ /** Where to position the menu, in app-viewport (iframe-relative) coordinates. */
737
+ anchor: MindooDBAppMenuAnchor;
738
+ placement?: MindooDBAppMenuPlacement;
739
+ kind?: MindooDBAppMenuKind;
740
+ items: MindooDBAppMenuItem[];
741
+ /** Dismiss when the user clicks outside the menu (default `true`). */
742
+ dismissOnOutsideClick?: boolean;
743
+ /** Dismiss when the user presses Escape (default `true`). */
744
+ dismissOnEscape?: boolean;
745
+ /** Dismiss when the app viewport is resized (default `true`). */
746
+ dismissOnViewportChange?: boolean;
747
+ }
748
+ /** Reason why a host-rendered menu was dismissed without a selection. */
749
+ type MindooDBAppMenuDismissReason = "outside_click" | "escape" | "app_blur" | "viewport_change" | "hide" | "replaced";
750
+ /** Successful selection result returned from a host-rendered menu. */
751
+ interface MindooDBAppMenuSelectionResult {
752
+ action: "selected";
753
+ itemId: string;
754
+ }
755
+ /** Dismissal result returned from a host-rendered menu. */
756
+ interface MindooDBAppMenuDismissedResult {
757
+ action: "dismissed";
758
+ reason: MindooDBAppMenuDismissReason;
759
+ }
760
+ /** Result returned when Haven closes or resolves a host-rendered menu. */
761
+ type MindooDBAppShowMenuResult = MindooDBAppMenuSelectionResult | MindooDBAppMenuDismissedResult;
762
+ /**
763
+ * Overlay menu operations exposed by the host session. Haven renders the
764
+ * menu above the app iframe so it can escape the iframe clip rect —
765
+ * data-only (no HTML/CSS/script crosses the bridge). Intended for
766
+ * `runtime === "iframe"`; window-mode apps can usually render local menus.
767
+ */
768
+ interface MindooDBAppMenuApi {
769
+ /**
770
+ * Show a host-rendered menu at the given anchor (iframe-relative
771
+ * coordinates) and resolve once the user selects an item
772
+ * (`{ action: "selected", itemId }`) or the menu is dismissed
773
+ * (`{ action: "dismissed", reason }`). Showing a new menu replaces a
774
+ * pending one.
775
+ */
776
+ show(input: MindooDBAppShowMenuInput): Promise<MindooDBAppShowMenuResult>;
777
+ /** Dismiss a pending host-rendered menu (its `show()` resolves with reason `"hide"`). */
778
+ hide(): Promise<void>;
779
+ }
780
+ /** Pull-based read stream for document attachments. */
781
+ interface MindooDBAppReadableAttachmentStream {
782
+ /** Next chunk, or `null` when the attachment is fully consumed. */
783
+ read(): Promise<Uint8Array | null>;
784
+ /** Release the host-side stream; safe to call after `read()` returned `null`. */
785
+ close(): Promise<void>;
786
+ }
787
+ /** Push-based write stream for document attachments. */
788
+ interface MindooDBAppWritableAttachmentStream {
789
+ /** Send one chunk; resolves once the host acknowledged it (backpressure). */
790
+ write(chunk: Uint8Array): Promise<void>;
791
+ /** Finalize the upload and attach the file to the document. */
792
+ close(): Promise<void>;
793
+ /** Cancel the upload and discard all chunks written so far. */
794
+ abort(): Promise<void>;
795
+ }
796
+ /**
797
+ * One sort key of a {@link MindooDBAppDocumentQuery}: a plain summary
798
+ * field path, a computed expression (evaluated per row before comparison),
799
+ * or the special `textScore` pseudo-key (relevance of the query's `text`
800
+ * clause). Mirrors mindoodb's `MindooQuerySortKey`.
801
+ */
802
+ interface MindooDBAppQuerySortKey {
803
+ field?: string;
804
+ expression?: MindooDBAppExpression;
805
+ /**
806
+ * `"textScore"`: sort by the relevance score of the query's `text`
807
+ * clause (only meaningful together with one). For "best match first"
808
+ * use `direction: "descending"` — which is also the implicit default
809
+ * ordering when a `text` clause is present and no `sortBy` was given.
810
+ */
811
+ special?: "textScore";
812
+ direction?: "ascending" | "descending";
813
+ }
814
+ /**
815
+ * Full-text clause of a {@link MindooDBAppDocumentQuery}: matches
816
+ * documents through the database's full-text index and adds a relevance
817
+ * score per row. Requires full-text indexing to be enabled for the
818
+ * database (`fulltextSetup` in its `dbsetup` document) — otherwise the
819
+ * query is rejected with a `fulltext-not-enabled` error.
820
+ *
821
+ * Search results are device-specific under end-to-end encryption: the
822
+ * index is built from content the current device can decrypt.
823
+ */
824
+ interface MindooDBAppQueryTextClause {
825
+ /** The search string (tokenized like indexed content). */
826
+ query: string;
827
+ /**
828
+ * Restrict matching to these index fields (document field paths, plus
829
+ * the synthetic `_attachments` field for extracted attachment text).
830
+ * Default: all indexed fields.
831
+ */
832
+ fields?: string[];
833
+ /** Match term prefixes (`"drag"` matches `"dragon"`). Default: `true`. */
834
+ prefix?: boolean;
835
+ /**
836
+ * Fuzzy matching tolerance: `true`, an edit-distance fraction (0..1) of
837
+ * the term length, or an absolute edit distance (> 1). Default: `false`.
838
+ */
839
+ fuzzy?: boolean | number;
840
+ /** How multiple terms combine: `"AND"` (default) or `"OR"`. */
841
+ combineWith?: "AND" | "OR";
842
+ }
843
+ /**
844
+ * Full-text index configuration of a database, stored in the synced
845
+ * `dbsetup` document (`fulltextSetup` field) — the app-SDK mirror of
846
+ * MindooDB's `FulltextConfig`. Read/write it via
847
+ * {@link MindooDBAppDatabase.getFulltextSetup} /
848
+ * {@link MindooDBAppDatabase.setFulltextSetup}.
849
+ */
850
+ interface MindooDBAppFulltextSetup {
851
+ /** Master switch — full-text indexing is opt-in (default `false`). */
852
+ enabled?: boolean;
853
+ /**
854
+ * Dot-separated document field paths to index. Empty/omitted = auto
855
+ * mode: every non-underscore top-level field with non-empty extracted
856
+ * plain text.
857
+ */
858
+ include?: string[];
859
+ /**
860
+ * Extract and index attachment text through the host's registered
861
+ * extractors (Haven ships PDF/Office/plain-text extractors), indexed
862
+ * under the synthetic `_attachments` field. Default: `false`.
863
+ */
864
+ attachments?: boolean;
865
+ /**
866
+ * BCP-47 language tag steering tokenization (`Intl.Segmenter` locale).
867
+ * Changing it rebuilds the index. Default: `"und"`.
868
+ */
869
+ language?: string;
870
+ /** Per-field cap (approximate bytes) for extracted text. */
871
+ maxFieldBytes?: number;
872
+ }
873
+ /**
874
+ * Attachment text extraction configuration of a database, stored in the
875
+ * synced `dbsetup` document (`extractionSetup` field) — the app-SDK
876
+ * mirror of MindooDB's `ExtractionConfig`. Enables host-side extraction
877
+ * services (e.g. Haven's OCR) that extract text from attachment content
878
+ * once and persist it at the attachment entry, where the full-text index
879
+ * picks it up on every replica. Read/write it via
880
+ * {@link MindooDBAppDatabase.getExtractionSetup} /
881
+ * {@link MindooDBAppDatabase.setExtractionSetup}.
882
+ */
883
+ interface MindooDBAppExtractionSetup {
884
+ /** Master switch — extraction services stay idle without it (default `false`). */
885
+ enabled?: boolean;
886
+ /**
887
+ * Tesseract-style OCR language codes (e.g. `["deu", "eng"]`). Default is
888
+ * host-defined.
889
+ */
890
+ languages?: string[];
891
+ /**
892
+ * Restrict extraction to these MIME types (prefix match allowed, e.g.
893
+ * `"image/"`). Default is host-defined (typically images + PDFs).
894
+ */
895
+ mimeTypes?: string[];
896
+ /** Cap on persisted text per attachment in characters. */
897
+ maxCharsPerAttachment?: number;
898
+ }
899
+ /**
900
+ * An ad-hoc query answered from the database's document summary buffer —
901
+ * no documents are materialized on the host, which makes this the fastest
902
+ * way to filter and sort documents from an app.
903
+ *
904
+ * The `filter` accepts either a prebuilt boolean expression (from
905
+ * `createViewLanguage()`) or formula source text (e.g.
906
+ * `'v.and(v.eq(v.field("type"), "invoice"), v.gt(v.field("total"), 100))'`),
907
+ * which the SDK parses locally; only JSON travels across the bridge.
908
+ */
909
+ interface MindooDBAppDocumentQuery {
910
+ filter?: MindooDBAppBooleanExpression | string;
911
+ /**
912
+ * Full-text clause: additionally require documents to match this
913
+ * full-text search (combined with `filter` as a logical AND). Adds a
914
+ * relevance score per row ({@link MindooDBAppQueryRow.textScore});
915
+ * without an explicit `sortBy`, results are ordered best score first.
916
+ * Requires full-text indexing to be enabled for the database.
917
+ */
918
+ text?: MindooDBAppQueryTextClause;
919
+ sortBy?: MindooDBAppQuerySortKey[];
920
+ /**
921
+ * Maximum number of rows returned. The host enforces a cap; omitting the
922
+ * limit yields the host default page size.
923
+ */
924
+ limit?: number;
925
+ offset?: number;
926
+ /**
927
+ * Projection: restrict the fields returned per row. Defaults to all
928
+ * summary fields of the matching document.
929
+ */
930
+ fields?: string[];
931
+ }
932
+ /** One result row of a summary-backed document query. */
933
+ interface MindooDBAppQueryRow {
934
+ docId: string;
935
+ fields: Record<string, unknown>;
936
+ lastModified: number;
937
+ /**
938
+ * Relevance score of the query's `text` clause (higher = better match).
939
+ * Only present when the query had a `text` clause.
940
+ */
941
+ textScore?: number;
942
+ }
943
+ /**
944
+ * Which data answered the query: `"full"` when the summary buffer is
945
+ * complete, `"rebuilding"` while a backfill is still running (results may
946
+ * be incomplete), `"full-scan"` when documents were materialized.
947
+ */
948
+ type MindooDBAppQueryCoverage = "full" | "rebuilding" | "full-scan";
949
+ /** Result of a summary-backed document query. */
950
+ interface MindooDBAppQueryResult {
951
+ rows: MindooDBAppQueryRow[];
952
+ /** Number of matching documents before `offset`/`limit` were applied. */
953
+ total: number;
954
+ coverage: MindooDBAppQueryCoverage;
955
+ }
956
+ /**
957
+ * Handle returned by `documents.liveQuery()`. Dispose it when the UI that
958
+ * consumes the results goes away — live subscriptions otherwise stay
959
+ * active until the app disconnects.
960
+ */
961
+ interface MindooDBAppLiveQuerySubscription {
962
+ /**
963
+ * Force a re-evaluation now. The new result is delivered through the
964
+ * subscription's `onResult` callback even when nothing changed.
965
+ */
966
+ refresh(): Promise<void>;
967
+ /** Stop the subscription; no further `onResult` calls occur afterwards. */
968
+ dispose(): Promise<void>;
969
+ }
970
+ /** Document operations exposed by an opened database handle. */
971
+ interface MindooDBAppDocumentApi {
972
+ /**
973
+ * Run an ad-hoc query against the database's document summary buffer:
974
+ * declarative filter, full-text `text` clause, dynamic sorting, paging,
975
+ * and field projection — without materializing documents on the host.
976
+ *
977
+ * Requires the summary buffer to cover all referenced fields; queries
978
+ * that need encrypted or uncovered fields are rejected with a
979
+ * `query-not-supported` error. A `text` clause requires full-text
980
+ * indexing to be enabled for the database, otherwise the query is
981
+ * rejected with `fulltext-not-enabled`.
982
+ */
983
+ query(query?: MindooDBAppDocumentQuery): Promise<MindooDBAppQueryResult>;
984
+ /**
985
+ * Live variant of {@link query}: delivers the initial result, then keeps
986
+ * watching the database and calls `onResult` again whenever the result
987
+ * actually changed (membership, order, or row content). Updates are
988
+ * coalesced on the host, so bursts of writes produce a single push.
989
+ */
990
+ liveQuery(query: MindooDBAppDocumentQuery, onResult: (result: MindooDBAppQueryResult) => void): Promise<MindooDBAppLiveQuerySubscription>;
991
+ /**
992
+ * Page through the database's changefeed. Pass the returned `nextCursor`
993
+ * back in to resume — this is the primitive for incremental sync and
994
+ * app-side derived indexes (use `status: "all"` there so deletions are
995
+ * visible). For plain "find matching documents" use cases prefer
996
+ * {@link query}. Requires the `read` capability.
997
+ */
998
+ list(query?: MindooDBAppDocumentListQuery): Promise<MindooDBAppDocumentListResult>;
999
+ /**
1000
+ * The database's latest changefeed cursor without loading any documents.
1001
+ * Useful as a baseline checkpoint before starting an incremental
1002
+ * {@link list} loop. Requires the `read` capability.
1003
+ */
1004
+ getHeadCursor(): Promise<MindooDBAppDocumentHeadCursorResult>;
1005
+ /**
1006
+ * Load a single document by id, including its current Automerge `heads`
1007
+ * (needed as `baseHeads` for granular text/rich-text/JSON patches) and
1008
+ * attachment metadata. Resolves to `null` when the document does not
1009
+ * exist or is deleted. Requires the `read` capability.
1010
+ */
1011
+ get(docId: string): Promise<MindooDBAppDocument | null>;
1012
+ /**
1013
+ * Read the rich-text spans of an Automerge rich-text field at `path`,
1014
+ * plus the heads they were read at. Pass `options.revisionId` (from
1015
+ * {@link listHistory}) for a read-only historical snapshot. Feed the
1016
+ * result into `createMindooDBRichTextHandle` or diff against it before
1017
+ * writing back via `update({ richText: [...] })`.
1018
+ */
1019
+ getRichText(docId: string, path: Array<string | number>, options?: MindooDBAppRichTextGetOptions): Promise<MindooDBAppRichTextSnapshot>;
1020
+ /**
1021
+ * Export the full internal Automerge document as binary.
1022
+ *
1023
+ * **Discouraged** — prefer `getRichText`, `get`, and `documents.update` (`set`,
1024
+ * `unset`, `text`, `richText`, `json`) unless those APIs cannot express your
1025
+ * edits. Added for TeamEdit Word/.docx (local Automerge replica + binary flush).
1026
+ */
1027
+ getAutomergeSnapshot(docId: string, options?: MindooDBAppAutomergeGetOptions): Promise<MindooDBAppAutomergeSnapshot>;
1028
+ /**
1029
+ * Merge raw Automerge change bytes into the canonical document on Haven.
1030
+ *
1031
+ * **Discouraged** — prefer `documents.update` patch operations. Escape hatch
1032
+ * for apps that host a local Automerge replica when JSON patches are insufficient.
1033
+ * Include `replicaHeads` to receive incremental `changesSince` in the response.
1034
+ */
1035
+ applyAutomergeChanges(docId: string, patch: MindooDBAppAutomergeChangesPatch): Promise<MindooDBAppAutomergePatchResult>;
1036
+ /**
1037
+ * Create a new document from `input.set` (or return the existing one
1038
+ * when a caller-provided `input.id` already exists — idempotent create,
1039
+ * see {@link MindooDBAppCreateDocumentInput}). Requires the `create`
1040
+ * capability; the database's write access policy is enforced on the host
1041
+ * and violations reject with an access error. Use {@link canCreate} to
1042
+ * predict the outcome without writing.
1043
+ */
1044
+ create(input: MindooDBAppCreateDocumentInput): Promise<MindooDBAppDocument>;
1045
+ /**
1046
+ * Bulk-create documents in one host round trip.
1047
+ *
1048
+ * The host persists the whole batch in a single append-only store write and
1049
+ * runs one sync pass, which is dramatically faster than per-document
1050
+ * `create()` calls for large imports. The response is deliberately lean —
1051
+ * only the created document ids, in input order — so no per-document
1052
+ * projection work is performed. Use `get()` afterwards when full documents
1053
+ * are needed.
1054
+ *
1055
+ * On hosts that do not support the bulk RPC yet, the client transparently
1056
+ * falls back to sequential `create()` calls.
1057
+ */
1058
+ createMany(inputs: MindooDBAppCreateDocumentInput[]): Promise<{
1059
+ ids: string[];
1060
+ }>;
1061
+ /**
1062
+ * Apply a sparse patch to an existing document and return the updated
1063
+ * state. `set`/`unset` address top-level fields; `json`, `text`,
1064
+ * `richText`, and `richTextSteps` apply granular collaborative edits at
1065
+ * any path and are merged on the host using the patch's `baseHeads`, so
1066
+ * concurrent edits from other replicas converge instead of overwriting
1067
+ * each other. Requires the `update` capability.
1068
+ */
1069
+ update(docId: string, patch: MindooDBAppUpdateDocumentInput): Promise<MindooDBAppDocument>;
1070
+ /**
1071
+ * Mark a document as deleted by writing a lifecycle tombstone. The
1072
+ * append-only history keeps the document body, so {@link undelete} can
1073
+ * restore it and {@link listHistory} still shows past revisions. To
1074
+ * record a deletion reason, `update` a reason field first, then delete.
1075
+ * Requires the `delete` capability.
1076
+ */
1077
+ delete(docId: string): Promise<{
1078
+ ok: true;
1079
+ }>;
1080
+ /**
1081
+ * Bulk-delete documents in one host round trip.
1082
+ *
1083
+ * The host persists all delete markers in a single append-only store write
1084
+ * and runs one sync pass. Missing or already-deleted documents are skipped
1085
+ * (idempotent bulk semantics for destructive re-imports).
1086
+ *
1087
+ * On hosts that do not support the bulk RPC yet, the client transparently
1088
+ * falls back to sequential `delete()` calls.
1089
+ */
1090
+ deleteMany(docIds: string[]): Promise<{
1091
+ ok: true;
1092
+ }>;
1093
+ /**
1094
+ * Make the latest state of a deleted document live again (the inverse of
1095
+ * {@link delete}). Requires the `delete` capability.
1096
+ */
1097
+ undelete(docId: string): Promise<{
1098
+ ok: true;
1099
+ }>;
1100
+ /**
1101
+ * Predict whether `create` would be allowed, without writing anything. Useful
1102
+ * for disabling a "New" action and surfacing `decision.reason` up front.
1103
+ */
1104
+ canCreate(input?: {
1105
+ decryptionKeyId?: string;
1106
+ }): Promise<MindooDBAppAccessDecision>;
1107
+ /**
1108
+ * Predict whether `update` would be allowed for the given document, without
1109
+ * writing. The current document state is used as the candidate edit, so this
1110
+ * gates baseline (Tier 1) policy; content-dependent (Tier 2) rules are still
1111
+ * enforced on the actual `update`.
1112
+ */
1113
+ canChange(docId: string): Promise<MindooDBAppAccessDecision>;
1114
+ /** Predict whether `delete` would be allowed for the given document. */
1115
+ canDelete(docId: string): Promise<MindooDBAppAccessDecision>;
1116
+ /** Predict whether `undelete` would be allowed for the given document. */
1117
+ canUndelete(docId: string): Promise<MindooDBAppAccessDecision>;
1118
+ /**
1119
+ * The effective default document key id used when `create` is called without
1120
+ * an explicit `decryptionKeyId`. Resolves the database/tenant policy default
1121
+ * and falls back to `"default"`.
1122
+ */
1123
+ getDefaultCreateKeyId(): Promise<string>;
1124
+ /**
1125
+ * List the document's revision timeline (newest first), including author
1126
+ * identity metadata and the stable `revisionId` per entry. Requires the
1127
+ * `history` capability.
1128
+ */
1129
+ listHistory(docId: string): Promise<MindooDBAppDocumentHistoryEntry[]>;
1130
+ /**
1131
+ * Read-only snapshot of the document as it existed at an epoch-millisecond
1132
+ * timestamp. Prefer {@link getAtRevision} with a `revisionId` from
1133
+ * {@link listHistory} when you need an exact revision — timestamps can be
1134
+ * ambiguous around concurrent edits. Requires the `history` capability.
1135
+ */
1136
+ getAtTimestamp(docId: string, timestamp: number): Promise<MindooDBAppHistoricalDocument>;
1137
+ /**
1138
+ * Read-only snapshot of the document at an exact revision. `revisionId`
1139
+ * values come from {@link listHistory} and are stable, DAG-backed
1140
+ * identifiers — the preferred way to load historical states and the value
1141
+ * to pass to historical attachment APIs. Requires the `history`
1142
+ * capability.
1143
+ */
1144
+ getAtRevision(docId: string, revisionId: MindooDBAppDocumentRevisionId): Promise<MindooDBAppHistoricalDocument>;
1145
+ }
1146
+ type MindooDBAppViewEntryKind = "category" | "document";
1147
+ /** Unique document identity within a multi-source view. */
1148
+ interface MindooDBAppScopedDocId {
1149
+ origin: string;
1150
+ docId: string;
1151
+ }
1152
+ /** Serialized view entry returned by the navigator APIs. */
1153
+ interface MindooDBAppViewEntry {
1154
+ /** Unique occurrence key within the current navigator session. */
1155
+ key: string;
1156
+ kind: MindooDBAppViewEntryKind;
1157
+ origin: string;
1158
+ docId: string | null;
1159
+ level: number;
1160
+ parentKey: string | null;
1161
+ categoryPath: unknown[];
1162
+ categoryValue: unknown | null;
1163
+ columnValues: Record<string, unknown>;
1164
+ childCount?: number;
1165
+ descendantDocumentCount?: number;
1166
+ descendantCount?: number;
1167
+ descendantCategoryCount?: number;
1168
+ childCategoryCount?: number;
1169
+ childDocumentCount?: number;
1170
+ siblingCount?: number;
1171
+ /** Stable continuation token for the current occurrence. */
1172
+ position: string | null;
1173
+ expanded: boolean;
1174
+ selected: boolean;
1175
+ isVisible: boolean;
1176
+ }
1177
+ /** Options that shape which subtree and entry kinds a navigator exposes. */
1178
+ interface MindooDBAppViewNavigatorOpenOptions {
1179
+ /** Emit category entries (default `true`). */
1180
+ includeCategories?: boolean;
1181
+ /** Emit document entries (default `true`). */
1182
+ includeDocuments?: boolean;
1183
+ /** Skip categories whose subtree contains no visible documents. */
1184
+ hideEmptyCategories?: boolean;
1185
+ /** Restrict the navigator to the subtree below this category-value path. */
1186
+ rootCategoryPath?: unknown[];
1187
+ /** Restrict the navigator to the subtree below this entry key (alternative to `rootCategoryPath`). */
1188
+ rootEntryKey?: string;
1189
+ }
1190
+ /** Input used when creating a dynamic view and immediately opening a navigator. */
1191
+ interface MindooDBAppCreateViewNavigatorInput {
1192
+ databaseIds: string[];
1193
+ definition: MindooDBAppViewDefinition;
1194
+ categorizationStyle?: MindooDBAppConfiguredViewCategorizationStyle;
1195
+ options?: MindooDBAppViewNavigatorOpenOptions;
1196
+ /**
1197
+ * Force the host to index from fully materialized documents instead of
1198
+ * the document summary buffer. Expensive by design — without it the host
1199
+ * picks the summary buffer whenever the view definition allows it and
1200
+ * only falls back to documents when it must (e.g. decrypt expressions or
1201
+ * fields not covered by the summary configuration).
1202
+ */
1203
+ useFullDocuments?: boolean;
1204
+ }
1205
+ /** @deprecated Use `MindooDBAppCreateViewNavigatorInput`. */
1206
+ type MindooDBAppCreateViewInput = MindooDBAppCreateViewNavigatorInput;
1207
+ /** Range query options for key and key-range lookups within a category. */
1208
+ interface MindooDBAppViewNavigatorRangeQuery {
1209
+ /** Inclusive lower bound on the sort key; omit for an open start. */
1210
+ startKey?: unknown;
1211
+ /** Inclusive upper bound on the sort key; omit for an open end. */
1212
+ endKey?: unknown;
1213
+ /** Return matches in reverse view order. */
1214
+ descending?: boolean;
1215
+ /** Require exact key matches at the bounds instead of prefix matching for strings. */
1216
+ exact?: boolean;
1217
+ }
1218
+ /** Options for batched navigator reads. */
1219
+ interface MindooDBAppViewNavigatorPageOptions {
1220
+ /** Maximum entries per page. */
1221
+ limit?: number;
1222
+ /** Only return entries that are currently selected. */
1223
+ selectedOnly?: boolean;
1224
+ /**
1225
+ * Continuation token from a previous page's `nextPosition` (or an entry's
1226
+ * `position`). Omit to start at the navigator's current cursor.
1227
+ */
1228
+ startPosition?: string | null;
1229
+ }
1230
+ /** Paged batch of navigator entries. */
1231
+ interface MindooDBAppViewNavigatorPageResult {
1232
+ entries: MindooDBAppViewEntry[];
1233
+ /** Pass back as `startPosition` to fetch the next page; `null` at the end. */
1234
+ nextPosition: string | null;
1235
+ hasMore: boolean;
1236
+ }
1237
+ /** Serializable selection state for restoring a navigator session. */
1238
+ interface MindooDBAppViewNavigatorSelectionState {
1239
+ selectAllByDefault: boolean;
1240
+ entryKeys: string[];
1241
+ }
1242
+ /** Serializable expansion state for restoring a navigator session. */
1243
+ interface MindooDBAppViewNavigatorExpansionState {
1244
+ expandAllByDefault: boolean;
1245
+ expandLevel: number;
1246
+ entryKeys: string[];
1247
+ }
1248
+ /** Change statistics delivered with a `view-changed` push event. */
1249
+ interface MindooDBAppViewUpdateStats {
1250
+ addedCount: number;
1251
+ removedCount: number;
1252
+ }
1253
+ /**
1254
+ * Stateful view navigator that closely mirrors the core VirtualViewNavigator.
1255
+ *
1256
+ * All navigation state (current position, selection, expansion) lives on the
1257
+ * host per navigator session. `goto*()` calls are cheap but cost one bridge
1258
+ * round trip each — prefer {@link entriesForward} / {@link entriesBackward}
1259
+ * when rendering lists. Always call {@link dispose} when the consuming UI
1260
+ * goes away so the host can release the session.
1261
+ */
1262
+ interface MindooDBAppViewNavigator {
1263
+ /** The effective view definition this navigator was opened with. */
1264
+ getDefinition(): Promise<MindooDBAppViewDefinition>;
1265
+ /**
1266
+ * Opaque cursor describing the database state currently reflected in the
1267
+ * view. Pass it to `session.listDocumentsSinceViewCursor()` for
1268
+ * delta-sync use cases (legacy polling path — prefer
1269
+ * {@link onDidUpdate}).
1270
+ */
1271
+ getViewCursor(): Promise<string | null>;
1272
+ /**
1273
+ * Force an incremental catch-up of the underlying view and return the new
1274
+ * view cursor. Rarely needed when {@link onDidUpdate} is used — the host
1275
+ * keeps live views current on its own.
1276
+ */
1277
+ refresh(): Promise<string | null>;
1278
+ /**
1279
+ * Subscribe to host-pushed view updates: the host keeps the underlying
1280
+ * view bound to its databases' change feeds and fires this listener
1281
+ * after every applied change batch. Apps no longer need to poll or call
1282
+ * {@link refresh} — just re-read the visible page when the listener
1283
+ * fires. Returns an unsubscribe function.
1284
+ */
1285
+ onDidUpdate(listener: (stats: MindooDBAppViewUpdateStats) => void): () => void;
1286
+ /** The entry at the navigator's current cursor position, if any. */
1287
+ getCurrentEntry(): Promise<MindooDBAppViewEntry | null>;
1288
+ /**
1289
+ * Cursor movement. Each method moves the host-side cursor and resolves to
1290
+ * `true` when a matching entry exists (read it with
1291
+ * {@link getCurrentEntry}), `false` when the move was not possible.
1292
+ */
1293
+ gotoFirst(): Promise<boolean>;
1294
+ gotoLast(): Promise<boolean>;
1295
+ gotoNext(): Promise<boolean>;
1296
+ gotoPrev(): Promise<boolean>;
1297
+ gotoNextSibling(): Promise<boolean>;
1298
+ gotoPrevSibling(): Promise<boolean>;
1299
+ gotoParent(): Promise<boolean>;
1300
+ gotoFirstChild(): Promise<boolean>;
1301
+ gotoLastChild(): Promise<boolean>;
1302
+ /** Move the cursor to a `position` token taken from a previously read entry or page result. */
1303
+ gotoPos(position: string): Promise<boolean>;
1304
+ /** Read the entry at a `position` token without moving the cursor. */
1305
+ getPos(position: string): Promise<MindooDBAppViewEntry | null>;
1306
+ /**
1307
+ * Look up a category entry by its category-value path, e.g.
1308
+ * `["Sales", "2026"]` for a two-level categorization.
1309
+ */
1310
+ findCategoryEntryByParts(parts: unknown[]): Promise<MindooDBAppViewEntry | null>;
1311
+ /**
1312
+ * Read a batch of entries starting at the cursor (or at
1313
+ * `options.startPosition`) — the preferred call for rendering lists, since
1314
+ * it replaces many `goto*()` round trips with one. Page onwards by passing
1315
+ * the result's `nextPosition` back as `startPosition`.
1316
+ */
1317
+ entriesForward(options?: MindooDBAppViewNavigatorPageOptions): Promise<MindooDBAppViewNavigatorPageResult>;
1318
+ /** Like {@link entriesForward}, but walking backwards. */
1319
+ entriesBackward(options?: MindooDBAppViewNavigatorPageOptions): Promise<MindooDBAppViewNavigatorPageResult>;
1320
+ /** Move the cursor to the next/previous selected entry. */
1321
+ gotoNextSelected(): Promise<boolean>;
1322
+ gotoPrevSelected(): Promise<boolean>;
1323
+ /**
1324
+ * Selection state lives on the host per navigator session. `origin` is the
1325
+ * source binding name of the entry (see `MindooDBAppViewEntry.origin`);
1326
+ * `selectParentCategories` also marks the ancestor categories as selected.
1327
+ */
1328
+ select(origin: string, docId: string, selectParentCategories?: boolean): Promise<void>;
1329
+ deselect(origin: string, docId: string): Promise<void>;
1330
+ selectAllEntries(): Promise<void>;
1331
+ deselectAllEntries(): Promise<void>;
1332
+ isSelected(origin: string, docId: string): Promise<boolean>;
1333
+ /** Snapshot the selection for persistence; restore it with {@link setSelectionState}. */
1334
+ getSelectionState(): Promise<MindooDBAppViewNavigatorSelectionState>;
1335
+ setSelectionState(state: MindooDBAppViewNavigatorSelectionState): Promise<void>;
1336
+ /**
1337
+ * Expansion state controls which category subtrees are visible to cursor
1338
+ * movement and paging. Like selection, it lives on the host per session.
1339
+ */
1340
+ expand(origin: string, docId: string): Promise<void>;
1341
+ collapse(origin: string, docId: string): Promise<void>;
1342
+ expandAll(): Promise<void>;
1343
+ collapseAll(): Promise<void>;
1344
+ /** Expand categories down to `level` (0 = top-level) and collapse deeper ones. */
1345
+ expandToLevel(level: number): Promise<void>;
1346
+ isExpanded(entryKey: string): Promise<boolean>;
1347
+ /** Snapshot the expansion state for persistence; restore it with {@link setExpansionState}. */
1348
+ getExpansionState(): Promise<MindooDBAppViewNavigatorExpansionState>;
1349
+ setExpansionState(state: MindooDBAppViewNavigatorExpansionState): Promise<void>;
1350
+ /**
1351
+ * Direct children of a category entry (`entryKey` from a previously read
1352
+ * entry): all entries, categories only, or documents only. These helpers
1353
+ * ignore expansion state and read the full child list in one round trip.
1354
+ */
1355
+ childEntries(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
1356
+ childCategories(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
1357
+ childDocuments(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
1358
+ /**
1359
+ * Children of a category whose sort key matches `key`. With
1360
+ * `exact: false`, prefix matching is used for string keys.
1361
+ */
1362
+ childCategoriesByKey(entryKey: string, key: unknown, exact?: boolean, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
1363
+ childDocumentsByKey(entryKey: string, key: unknown, exact?: boolean, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
1364
+ /** Children of a category whose sort key falls inside `range` (`startKey`..`endKey`). */
1365
+ childCategoriesBetween(entryKey: string, range: MindooDBAppViewNavigatorRangeQuery): Promise<MindooDBAppViewEntry[]>;
1366
+ childDocumentsBetween(entryKey: string, range: MindooDBAppViewNavigatorRangeQuery): Promise<MindooDBAppViewEntry[]>;
1367
+ /** All document ids in view order, across every category. */
1368
+ getSortedDocIds(descending?: boolean): Promise<MindooDBAppScopedDocId[]>;
1369
+ /** Document ids in view order below one category subtree. */
1370
+ getSortedDocIdsScoped(entryKey: string, descending?: boolean): Promise<MindooDBAppScopedDocId[]>;
1371
+ /**
1372
+ * Release the host-side navigator session (view binding, selection and
1373
+ * expansion state, update listeners). Always call this when the consuming
1374
+ * UI unmounts.
1375
+ */
1376
+ dispose(): Promise<void>;
1377
+ }
1378
+ /**
1379
+ * Attachment operations exposed by an opened database handle. All methods
1380
+ * require the `attachments` capability; historical reads (passing
1381
+ * `timestamp`/`revisionId` options) additionally require `history`, and
1382
+ * mutations (`openWriteStream`, `remove`, `scan`) require `update`.
1383
+ */
1384
+ interface MindooDBAppAttachmentApi {
1385
+ /**
1386
+ * Attachment metadata of a document. Pass `options.revisionId` (preferred
1387
+ * over `timestamp`) to read the attachment list of an exact historical
1388
+ * revision.
1389
+ */
1390
+ list(docId: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentInfo[]>;
1391
+ /** Remove an attachment from the current document state. */
1392
+ remove(docId: string, attachmentName: string): Promise<{
1393
+ ok: true;
1394
+ }>;
1395
+ /**
1396
+ * Download via a pull-based chunk stream: call `read()` until it resolves
1397
+ * to `null`, then `close()`. Chunks travel as transferable binary over the
1398
+ * bridge port, so large files never materialize as one buffer. Accepts
1399
+ * historical `options` like {@link list}.
1400
+ */
1401
+ openReadStream(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppReadableAttachmentStream>;
1402
+ /**
1403
+ * Upload via a push-based chunk stream: `write()` chunks, then `close()`
1404
+ * to finalize — or `abort()` to discard the partial upload. Always targets
1405
+ * the current document state.
1406
+ */
1407
+ openWriteStream(docId: string, attachmentName: string, contentType?: string): Promise<MindooDBAppWritableAttachmentStream>;
1408
+ /**
1409
+ * Open Haven's document-scanner dialog (camera capture with perspective
1410
+ * correction) and attach the scan to the document. Resolves with the new
1411
+ * attachment, or `ok: false` when the user cancelled.
1412
+ */
1413
+ scan(docId: string, options?: MindooDBAppScanAttachmentOptions): Promise<MindooDBAppScanAttachmentResult>;
1414
+ /**
1415
+ * Resolve a preview session (`previewUrl`) that the app can open itself
1416
+ * in a separate tab or window — the low-level variant of
1417
+ * {@link openPreview} for window-mode apps or custom link handling.
1418
+ */
1419
+ preparePreviewSession(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentPreviewSession>;
1420
+ /**
1421
+ * Open Haven's built-in attachment viewer (images, PDF, Markdown, text,
1422
+ * Office formats, streaming audio/video). Use `canPreviewAttachment()`
1423
+ * to gate preview buttons in the app UI. Accepts historical `options`
1424
+ * like {@link list}.
1425
+ */
1426
+ openPreview(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<{
1427
+ ok: true;
1428
+ }>;
1429
+ }
1430
+ /** Database handle returned from `session.openDatabase()`. */
1431
+ interface MindooDBAppDatabase {
1432
+ /** Metadata (id, title, role, granted capabilities) of this database binding. */
1433
+ info(): Promise<MindooDBAppDatabaseInfo>;
1434
+ documents: MindooDBAppDocumentApi;
1435
+ attachments: MindooDBAppAttachmentApi;
1436
+ /**
1437
+ * Read the database's full-text index configuration from the synced
1438
+ * `dbsetup` document. Resolves to `null` when full-text indexing has
1439
+ * never been configured. Requires the `read` capability.
1440
+ */
1441
+ getFulltextSetup(): Promise<MindooDBAppFulltextSetup | null>;
1442
+ /**
1443
+ * Write the database's full-text index configuration (persisted in the
1444
+ * synced `dbsetup` document, so it applies on every replica; each device
1445
+ * builds its own local index). Pass `null` to remove the configuration
1446
+ * (disables indexing). Typically called once during app setup, e.g.
1447
+ * `setFulltextSetup({ enabled: true, attachments: true })`.
1448
+ *
1449
+ * Requires the `update` capability; the change is idempotent, so calling
1450
+ * it on every app start with the same config is fine (no-op write when
1451
+ * nothing changed).
1452
+ */
1453
+ setFulltextSetup(config: MindooDBAppFulltextSetup | null): Promise<void>;
1454
+ /**
1455
+ * Read the database's attachment extraction configuration from the
1456
+ * synced `dbsetup` document. Resolves to `null` when extraction has
1457
+ * never been configured. Requires the `read` capability.
1458
+ */
1459
+ getExtractionSetup(): Promise<MindooDBAppExtractionSetup | null>;
1460
+ /**
1461
+ * Write the database's attachment extraction configuration (persisted
1462
+ * in the synced `dbsetup` document). Enables host-side extraction
1463
+ * services (e.g. Haven's OCR): extracted text is persisted at the
1464
+ * attachment entry and syncs with the document, so every replica can
1465
+ * search it without re-extracting. Pass `null` to remove the
1466
+ * configuration.
1467
+ *
1468
+ * Requires the `update` capability; idempotent like
1469
+ * {@link setFulltextSetup}.
1470
+ */
1471
+ setExtractionSetup(config: MindooDBAppExtractionSetup | null): Promise<void>;
1472
+ }
1473
+ /** Connected session between the running app and the Haven host. */
1474
+ interface MindooDBAppSession {
1475
+ /**
1476
+ * The full launch context supplied by Haven: runtime, theme, viewport,
1477
+ * locale, user, tenant, launch parameters, plus the databases and views
1478
+ * mapped to this app. Cached — repeated calls do not hit the host again.
1479
+ */
1480
+ getLaunchContext(): Promise<MindooDBAppLaunchContext>;
1481
+ /**
1482
+ * Product license identifiers active for the current Haven user, for apps
1483
+ * that gate features on licensing.
1484
+ */
1485
+ getLicensedProducts(): Promise<string[]>;
1486
+ /**
1487
+ * The databases visible to this app together with their granted
1488
+ * capabilities. Same data as `launchContext.databases`, re-fetched from
1489
+ * the host.
1490
+ */
1491
+ listDatabases(): Promise<MindooDBAppDatabaseInfo[]>;
1492
+ /**
1493
+ * Open one of the granted databases by its binding id (from
1494
+ * {@link listDatabases} / the launch context) and get the `documents` and
1495
+ * `attachments` APIs for it.
1496
+ */
1497
+ openDatabase(databaseId: string): Promise<MindooDBAppDatabase>;
1498
+ /**
1499
+ * Legacy polling/delta-sync path: list documents that changed across all
1500
+ * granted databases since a view cursor previously obtained from
1501
+ * `navigator.getViewCursor()` / `refresh()`. Prefer the push-based
1502
+ * `navigator.onDidUpdate()` and `documents.liveQuery()` for keeping UI
1503
+ * current; this remains useful for app-side derived state that needs an
1504
+ * explicit multi-database checkpoint.
1505
+ */
1506
+ listDocumentsSinceViewCursor(cursor: string | null): Promise<MindooDBAppViewCursorDocumentListResult>;
1507
+ /**
1508
+ * Create an app-defined (multi-database) view from a
1509
+ * `MindooDBAppViewDefinition` and immediately open a navigator on it.
1510
+ * The host builds the view summary-first (see
1511
+ * {@link MindooDBAppCreateViewNavigatorInput.useFullDocuments}) and keeps
1512
+ * it live-bound to the source databases. Requires the `views` capability
1513
+ * on every referenced database. Dispose the navigator when done.
1514
+ */
1515
+ createViewNavigator(input: MindooDBAppCreateViewNavigatorInput): Promise<MindooDBAppViewNavigator>;
1516
+ /**
1517
+ * Open a navigator on a Haven-configured view mapping (from
1518
+ * `launchContext.views`, referenced by its `id`). Requires the `read`
1519
+ * capability on the view's source databases. Dispose the navigator when
1520
+ * done.
1521
+ */
1522
+ openViewNavigator(viewId: string, options?: MindooDBAppViewNavigatorOpenOptions): Promise<MindooDBAppViewNavigator>;
1523
+ menus: MindooDBAppMenuApi;
1524
+ /**
1525
+ * Subscribe to host-pushed theme changes (light/dark mode and preset).
1526
+ * The initial theme is in `launchContext.theme`. Returns an unsubscribe
1527
+ * function.
1528
+ */
1529
+ onThemeChange(listener: (theme: MindooDBAppHostTheme) => void): () => void;
1530
+ /**
1531
+ * Subscribe to host-pushed iframe viewport size changes. Only fires for
1532
+ * `runtime === "iframe"` (window-mode apps observe their own window).
1533
+ * Returns an unsubscribe function.
1534
+ */
1535
+ onViewportChange(listener: (viewport: MindooDBAppViewport) => void): () => void;
1536
+ /**
1537
+ * Subscribe to host-pushed UI preference changes (e.g. iOS multitasking
1538
+ * optimizations). The initial value is in `launchContext.uiPreferences`.
1539
+ * Returns an unsubscribe function.
1540
+ */
1541
+ onUiPreferencesChange(listener: (uiPreferences: MindooDBAppUiPreferences) => void): () => void;
1542
+ /**
1543
+ * Subscribe to host-pushed UI language changes. The listener receives the
1544
+ * new BCP-47 language tag (e.g. `"de"`). Returns an unsubscribe function.
1545
+ */
1546
+ onLocaleChange(listener: (locale: string) => void): () => void;
1547
+ /**
1548
+ * Tear down the session: close the bridge port and release all host-side
1549
+ * resources of this launch (navigators, live queries, streams). The
1550
+ * session object is unusable afterwards.
1551
+ */
1552
+ disconnect(): Promise<void>;
1553
+ }
1554
+ /** Root SDK bridge object used to establish a session. */
1555
+ interface MindooDBAppBridge {
1556
+ /**
1557
+ * Perform the `postMessage` handshake with the Haven host and resolve
1558
+ * with a connected session. Reads the `mindoodbAppLaunchId` query
1559
+ * parameter injected by Haven when `options.launchId` is omitted; rejects
1560
+ * when no host answers within `connectTimeoutMs`.
1561
+ */
1562
+ connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
1563
+ }
1564
+
1565
+ export type { MindooDBAppConfiguredViewPreviewMode as $, MindooDBAppBridgeRpcMessage as A, MindooDBAppBridgeRpcRequest as B, MindooDBAppBridgeRpcSuccess as C, MindooDBAppBridgeStreamAbortRequest as D, MindooDBAppBridgeStreamAck as E, MindooDBAppBridgeStreamCloseRequest as F, MindooDBAppBridgeStreamError as G, MindooDBAppBridgeStreamMessage as H, MindooDBAppBridgeStreamOpenResult as I, MindooDBAppBridgeStreamReadRequest as J, MindooDBAppBridgeStreamWriteRequest as K, MindooDBAppBridgeThemeChangedMessage as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppBridgeUiPreferencesChangedMessage as N, MindooDBAppBridgeViewChangedMessage as O, MindooDBAppBridgeViewportChangedMessage as P, MindooDBAppCapability as Q, MindooDBAppConfiguredViewCategorizationStyle as R, MindooDBAppConfiguredViewColumn as S, MindooDBAppConfiguredViewColumnRole as T, MindooDBAppConfiguredViewExpressionMode as U, MindooDBAppConfiguredViewFieldExpression as V, MindooDBAppConfiguredViewFilterDefinition as W, MindooDBAppConfiguredViewFilterMode as X, MindooDBAppConfiguredViewFilterRule as Y, MindooDBAppConfiguredViewFormulaExpression as Z, MindooDBAppConfiguredViewFormulaFilterDefinition as _, MindooDBAppBridge as a, MindooDBAppRichTextTextSpan as a$, MindooDBAppConfiguredViewRuleFilterDefinition as a0, MindooDBAppConfiguredViewRuleMatchMode as a1, MindooDBAppConfiguredViewRuleOperator as a2, MindooDBAppConfiguredViewValueExpression as a3, MindooDBAppCreateDocumentInput as a4, MindooDBAppCreateViewInput as a5, MindooDBAppCreateViewNavigatorInput as a6, MindooDBAppDatabaseInfo as a7, MindooDBAppDocumentApi as a8, MindooDBAppDocumentHeadCursorResult as a9, MindooDBAppMenuDismissedResult as aA, MindooDBAppMenuItem as aB, MindooDBAppMenuKind as aC, MindooDBAppMenuPlacement as aD, MindooDBAppMenuPointAnchor as aE, MindooDBAppMenuRect as aF, MindooDBAppMenuRectAnchor as aG, MindooDBAppMenuSelectionResult as aH, MindooDBAppMenuSeparatorItem as aI, MindooDBAppQueryCoverage as aJ, MindooDBAppQueryResult as aK, MindooDBAppQueryRow as aL, MindooDBAppQuerySortKey as aM, MindooDBAppQueryTextClause as aN, MindooDBAppReadableAttachmentStream as aO, MindooDBAppResolvedViewDefinition as aP, MindooDBAppResolvedViewSource as aQ, MindooDBAppRichTextBlockSpan as aR, MindooDBAppRichTextGetOptions as aS, MindooDBAppRichTextImmutableString as aT, MindooDBAppRichTextMarkRange as aU, MindooDBAppRichTextMaterializeValue as aV, MindooDBAppRichTextPatch as aW, MindooDBAppRichTextScalar as aX, MindooDBAppRichTextSpliceStep as aY, MindooDBAppRichTextStep as aZ, MindooDBAppRichTextStepPatch as a_, MindooDBAppDocumentHistoryEntry as aa, MindooDBAppDocumentListQuery as ab, MindooDBAppDocumentListResult as ac, MindooDBAppDocumentQuery as ad, MindooDBAppDocumentRevisionId as ae, MindooDBAppDocumentScanPreset as af, MindooDBAppDocumentSummary as ag, MindooDBAppExtractionSetup as ah, MindooDBAppFulltextSetup as ai, MindooDBAppHistoricalDocument as aj, MindooDBAppHistoryQuery as ak, MindooDBAppHostTheme as al, MindooDBAppJsonListDeletePatch as am, MindooDBAppJsonListInsertPatch as an, MindooDBAppJsonPatch as ao, MindooDBAppJsonSetPatch as ap, MindooDBAppJsonTextMarkPatch as aq, MindooDBAppJsonTextSplicePatch as ar, MindooDBAppJsonTextUnmarkPatch as as, MindooDBAppJsonUnsetPatch as at, MindooDBAppLaunchContext as au, MindooDBAppLiveQuerySubscription as av, MindooDBAppMenuAnchor as aw, MindooDBAppMenuApi as ax, MindooDBAppMenuCommandItem as ay, MindooDBAppMenuDismissReason as az, MindooDBAppDatabase as b, MindooDBAppRuntime as b0, MindooDBAppScanAttachmentOptions as b1, MindooDBAppScanAttachmentResult as b2, MindooDBAppScopedDocId as b3, MindooDBAppScopedDocumentSummary as b4, MindooDBAppSession as b5, MindooDBAppShowMenuInput as b6, MindooDBAppShowMenuResult as b7, MindooDBAppTextEdit as b8, MindooDBAppTextPatch as b9, MindooDBAppThemeMode as ba, MindooDBAppUiPreferences as bb, MindooDBAppUpdateDocumentInput as bc, MindooDBAppViewCursorDocumentListResult as bd, MindooDBAppViewCursorResult as be, MindooDBAppViewEntry as bf, MindooDBAppViewEntryKind as bg, MindooDBAppViewNavigator as bh, MindooDBAppViewNavigatorExpansionState as bi, MindooDBAppViewNavigatorOpenOptions as bj, MindooDBAppViewNavigatorPageOptions as bk, MindooDBAppViewNavigatorPageResult as bl, MindooDBAppViewNavigatorRangeQuery as bm, MindooDBAppViewNavigatorSelectionState as bn, MindooDBAppViewUpdateStats as bo, MindooDBAppViewport as bp, MindooDBAppWritableAttachmentStream as bq, MindooDBAppDocument as c, MindooDBAppRichTextSpan as d, MindooDBAppRichTextSnapshot as e, MindooDBAppAccessDecision as f, MindooDBAppAccessTier as g, MindooDBAppAttachmentApi as h, MindooDBAppAttachmentChunk as i, MindooDBAppAttachmentInfo as j, MindooDBAppAttachmentPreviewOptions as k, MindooDBAppAttachmentPreviewSession as l, MindooDBAppAutomergeChangesPatch as m, MindooDBAppAutomergeChangesSince as n, MindooDBAppAutomergeGetOptions as o, MindooDBAppAutomergePatchResult as p, MindooDBAppAutomergeSnapshot as q, MindooDBAppBridgeConnectMessage as r, MindooDBAppBridgeConnectOptions as s, MindooDBAppBridgeConnectedMessage as t, MindooDBAppBridgeErrorPayload as u, MindooDBAppBridgeHandshakeErrorMessage as v, MindooDBAppBridgeLocaleChangedMessage as w, MindooDBAppBridgePortMessage as x, MindooDBAppBridgeQueryResultMessage as y, MindooDBAppBridgeRpcError as z };