mindoodb-app-sdk 0.0.46 → 0.0.48

package/README.md

@@ -1084,6 +1084,43 @@ if (handled) {
 }
 ```
 
+**Nested lookups (`include`)** fetch related documents alongside the matching rows — from the same database or from any other database the app is mapped to. The host resolves a slot with **one scan per slot**, not one query per row, so a list with its related records is a single round trip:
+
+```ts
+const result = await db.documents.query<{
+  customer: MindooDBAppQueryRow | null;
+  lines: MindooDBAppQueryRow[];
+}>({
+  filter: 'v.eq(v.field("type"), "invoice")',
+  fields: ["total", "customerId"],
+  include: {
+    customer: {
+      databaseId: "customers",     // another mapped database; omit for this one
+      cardinality: "one",          // → a row or null
+      localKey: "customerId",      // this row's field holds the customer's id
+      fields: ["name"],
+    },
+    lines: {
+      cardinality: "many",         // → an array (possibly empty, never null)
+      filter: 'v.eq(v.field("invoiceId"), v.parentDocId())',
+      sortBy: [{ field: "position", direction: "ascending" }],
+      limit: 50,
+    },
+  },
+});
+
+for (const row of result.rows) {
+  console.log(row.fields.total, row.includes?.customer?.fields.name);
+  console.log(row.includes?.lines.length);
+}
+```
+
+- Related documents live under `row.includes[slot]`, never as sibling keys, so a slot name can never collide with `docId` / `fields` / `lastModified`. Pass the slot types to `query<TIncludes>()` to have them typed.
+- The join condition relates the related document to the parent row: `v.parentDocId()` for the parent's id, `v.parent("<path>")` for one of its fields. `localKey` is shorthand for "this row's field holds the related document's id" (an array value joins every element). Exactly one such equality is allowed per slot — further conditions may narrow the related documents but must not mention the parent.
+- Slots nest (`row.includes.customer.includes.address`) up to three levels.
+- `databaseId` is checked like any other database parameter: the app must be mapped to it with the `read` capability, at every level. Unmapped or view-only ids are rejected with `database-not-found`, a missing capability with `forbidden`.
+- Hydration happens after sorting and paging, so only the returned rows are joined and `total` stays the unpaged match count. Per-slot `limit` is capped at 1000, and a query may carry at most 10 slots in total.
+
 **Live queries** keep a query result up to date. The callback receives the initial result and runs again whenever the result actually changed — the host coalesces bursts of writes and fingerprints results, so you only hear about real changes:
 
 ```ts
@@ -1101,7 +1138,7 @@ await subscription.refresh();
 await subscription.dispose();
 ```
 
-Live query results are pushed from the host over the bridge port — no polling. Subscriptions are cleaned up automatically when the app disconnects, but dispose them explicitly when the UI that consumes them unmounts.
+Live query results are pushed from the host over the bridge port — no polling. Subscriptions are cleaned up automatically when the app disconnects, but dispose them explicitly when the UI that consumes them unmounts. A live query with `include` also watches every related database, so a change to a joined document delivers a new result too.
 
 ### Incremental sync
 
@@ -1638,8 +1675,8 @@ Host-kept key/value state, the only durable storage a hosted app has. See [Stora
 
 | Method                             | Returns                                      |
 | ---------------------------------- | -------------------------------------------- |
-| `query(query?)`                    | `Promise<MindooDBAppQueryResult>`            |
-| `liveQuery(query, onResult)`       | `Promise<MindooDBAppLiveQuerySubscription>`  |
+| `query<TIncludes>(query?)`         | `Promise<MindooDBAppQueryResult<TIncludes>>` |
+| `liveQuery<TIncludes>(query, onResult)` | `Promise<MindooDBAppLiveQuerySubscription>` |
 | `list(query?)`                     | `Promise<MindooDBAppDocumentListResult>`     |
 | `listInaccessible(query?)`         | `Promise<MindooDBAppInaccessibleDocumentListResult>` |
 | `get(docId)`                       | `Promise<MindooDBAppDocument \| null>`       |

package/TESTING.md

@@ -183,6 +183,41 @@ await db.documents.create({ set: { type: "invoice", total: 50 } });
 await sub.dispose();
 ```
 
+Nested lookups (`include`) work too, including slots that name another mocked
+database by its id, and they mirror the host's rules — one parent equality per
+slot, `cardinality: "one"` failing loudly when several documents match, per-slot
+`sortBy`/`limit`, and nesting. A write to a joined database re-fires the live
+queries that join it, so cross-database joins can be tested end to end:
+
+```ts
+const mock = createMockMindooDBAppBridge({
+  databases: [
+    {
+      info: { id: "billing", title: "Billing", capabilities: ["read", "create"] },
+      documents: [{ id: "inv_1", data: { type: "invoice", customerId: "cust_1" } }],
+    },
+    {
+      info: { id: "customers", title: "Customers", capabilities: ["read"] },
+      documents: [{ id: "cust_1", data: { name: "Acme" } }],
+    },
+  ],
+});
+
+const session = await mock.bridge.connect();
+const billing = await session.openDatabase("billing");
+
+const result = await billing.documents.query<{ customer: MindooDBAppQueryRow | null }>({
+  filter: 'v.eq(v.field("type"), "invoice")',
+  include: {
+    customer: { databaseId: "customers", cardinality: "one", localKey: "customerId" },
+  },
+});
+expect(result.rows[0].includes?.customer?.fields.name).toBe("Acme");
+```
+
+An include slot naming a database that was not seeded fails, the same way Haven
+rejects a database the app is not mapped to.
+
 ## Level 2 example
 
 This pattern keeps the real `createMindooDBAppBridge()` code path and replaces only the host side.

package/dist/{chunk-XPPTUWW6.js → chunk-TPYDERAK.js}

@@ -658,14 +658,28 @@ function normalizeDocumentQuery(query) {
   if (!query) {
     return {};
   }
-  const { filter, ...rest } = query;
+  const { filter, include, ...rest } = query;
   return {
     ...rest,
-    ...filter !== void 0 ? {
-      filter: typeof filter === "string" ? parseMindooDBFormulaBooleanExpression(filter) : filter
-    } : {}
+    ...filter !== void 0 ? { filter: normalizeQueryFilter(filter) } : {},
+    ...include !== void 0 ? { include: normalizeQueryIncludes(include) } : {}
   };
 }
+function normalizeQueryFilter(filter) {
+  return typeof filter === "string" ? parseMindooDBFormulaBooleanExpression(filter) : filter;
+}
+function normalizeQueryIncludes(includes) {
+  const normalized = {};
+  for (const [slot, include] of Object.entries(includes)) {
+    const { filter, include: nested, ...rest } = include;
+    normalized[slot] = {
+      ...rest,
+      ...filter !== void 0 ? { filter: normalizeQueryFilter(filter) } : {},
+      ...nested !== void 0 ? { include: normalizeQueryIncludes(nested) } : {}
+    };
+  }
+  return normalized;
+}
 function isThemeChangedMessage(message) {
   return message.kind === "theme-changed";
 }
@@ -1766,6 +1780,13 @@ var MindooDBAppSessionImpl = class {
   async getLicensedProducts() {
     return await this.rpc.call("session.getLicensedProducts", {});
   }
+  /**
+   * Asks the host to install another app. Only a URL crosses the bridge: the host
+   * reads that origin's `haven-app.json` itself and asks the user.
+   */
+  async proposeApp(input) {
+    return await this.rpc.call("apps.propose", input);
+  }
   /** Lists the databases that the host has made available for this app session. */
   async listDatabases() {
     return await this.rpc.call("session.listDatabases", {});

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDatabase, j as MindooDBAppDocument, k as MindooDBAppRichTextSpan, l as MindooDBAppRichTextSnapshot } from './types-BaXvRKXY.js';
-export { m as MINDOODB_APP_SEAL_SIGNING_DOMAIN, n as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, o as MindooDBAppAccessDecision, p as MindooDBAppAccessTier, q as MindooDBAppAttachmentApi, r as MindooDBAppAttachmentChunk, s as MindooDBAppAttachmentInfo, t as MindooDBAppAttachmentPreviewOptions, u as MindooDBAppAttachmentPreviewSession, v as MindooDBAppAutomergeChangesPatch, w as MindooDBAppAutomergeChangesSince, x as MindooDBAppAutomergeGetOptions, y as MindooDBAppAutomergePatchResult, z as MindooDBAppAutomergeSnapshot, A as MindooDBAppBridgeBeforeCloseAck, B as MindooDBAppBridgeBeforeCloseMessage, C as MindooDBAppBridgeConnectMessage, D as MindooDBAppBridgeConnectOptions, E as MindooDBAppBridgeConnectedMessage, F as MindooDBAppBridgeDragDropMessage, G as MindooDBAppBridgeDragLeaveMessage, H as MindooDBAppBridgeDragOverMessage, I as MindooDBAppBridgeErrorPayload, J as MindooDBAppBridgeHandshakeErrorMessage, K as MindooDBAppBridgeLocaleChangedMessage, L as MindooDBAppBridgePortMessage, N as MindooDBAppBridgeQueryResultMessage, O as MindooDBAppBridgeRpcError, P as MindooDBAppBridgeRpcMessage, Q as MindooDBAppBridgeRpcRequest, R as MindooDBAppBridgeRpcSuccess, S as MindooDBAppBridgeShortcutInvokedMessage, T as MindooDBAppBridgeShortcutsChangedMessage, U as MindooDBAppBridgeStreamAbortRequest, V as MindooDBAppBridgeStreamAck, W as MindooDBAppBridgeStreamCloseRequest, X as MindooDBAppBridgeStreamError, Y as MindooDBAppBridgeStreamMessage, Z as MindooDBAppBridgeStreamOpenResult, _ as MindooDBAppBridgeStreamReadRequest, $ as MindooDBAppBridgeStreamWriteRequest, a0 as MindooDBAppBridgeThemeChangedMessage, a1 as MindooDBAppBridgeUiPreferencesChangedMessage, a2 as MindooDBAppBridgeViewChangedMessage, a3 as MindooDBAppBridgeViewportChangedMessage, a4 as MindooDBAppCapability, a5 as MindooDBAppConfiguredViewCategorizationStyle, a6 as MindooDBAppConfiguredViewColumn, a7 as MindooDBAppConfiguredViewColumnRole, a8 as MindooDBAppConfiguredViewExpressionMode, a9 as MindooDBAppConfiguredViewFieldExpression, aa as MindooDBAppConfiguredViewFilterDefinition, ab as MindooDBAppConfiguredViewFilterMode, ac as MindooDBAppConfiguredViewFilterRule, ad as MindooDBAppConfiguredViewFormulaExpression, ae as MindooDBAppConfiguredViewFormulaFilterDefinition, af as MindooDBAppConfiguredViewPreviewMode, ag as MindooDBAppConfiguredViewRuleFilterDefinition, ah as MindooDBAppConfiguredViewRuleMatchMode, ai as MindooDBAppConfiguredViewRuleOperator, aj as MindooDBAppConfiguredViewValueExpression, ak as MindooDBAppCreateDocumentInput, al as MindooDBAppCreateKeyInfo, am as MindooDBAppCreateViewInput, an as MindooDBAppCreateViewNavigatorInput, ao as MindooDBAppDatabaseInfo, ap as MindooDBAppDirectoryApi, aq as MindooDBAppDirectoryEntry, ar as MindooDBAppDocumentApi, as as MindooDBAppDocumentHeadCursorResult, at as MindooDBAppDocumentHistoryEntry, au as MindooDBAppDocumentListQuery, av as MindooDBAppDocumentListResult, aw as MindooDBAppDocumentQuery, ax as MindooDBAppDocumentRevisionId, ay as MindooDBAppDocumentScanPreset, az as MindooDBAppDocumentSummary, aA as MindooDBAppDragApi, aB as MindooDBAppDragCancelReason, aC as MindooDBAppDragDropEvent, aD as MindooDBAppDragEffect, aE as MindooDBAppDragHoverResult, aF as MindooDBAppDragOffer, aG as MindooDBAppDragOverEvent, aH as MindooDBAppDragPointer, aI as MindooDBAppDragProfile, aJ as MindooDBAppEntryAttachmentRef, aK as MindooDBAppEntryProvenance, aL as MindooDBAppExtractDocumentTextInput, aM as MindooDBAppExtractDocumentTextResult, aN as MindooDBAppExtractTextFormat, aO as MindooDBAppExtractionSetup, aP as MindooDBAppFulltextSetup, aQ as MindooDBAppHistoricalDocument, aR as MindooDBAppHistoryQuery, aS as MindooDBAppHostTheme, aT as MindooDBAppIdentityApi, aU as MindooDBAppInaccessibleDocument, aV as MindooDBAppInaccessibleDocumentListQuery, aW as MindooDBAppInaccessibleDocumentListResult, aX as MindooDBAppJsonListDeletePatch, aY as MindooDBAppJsonListInsertPatch, aZ as MindooDBAppJsonPatch, a_ as MindooDBAppJsonSetPatch, a$ as MindooDBAppJsonTextMarkPatch, b0 as MindooDBAppJsonTextSplicePatch, b1 as MindooDBAppJsonTextUnmarkPatch, b2 as MindooDBAppJsonUnsetPatch, b3 as MindooDBAppLaunchContext, b4 as MindooDBAppLiveQuerySubscription, b5 as MindooDBAppMenuAnchor, b6 as MindooDBAppMenuApi, b7 as MindooDBAppMenuCommandItem, b8 as MindooDBAppMenuDismissReason, b9 as MindooDBAppMenuDismissedResult, ba as MindooDBAppMenuItem, bb as MindooDBAppMenuKind, bc as MindooDBAppMenuPlacement, bd as MindooDBAppMenuPointAnchor, be as MindooDBAppMenuRect, bf as MindooDBAppMenuRectAnchor, bg as MindooDBAppMenuSelectionResult, bh as MindooDBAppMenuSeparatorItem, bi as MindooDBAppQueryCoverage, bj as MindooDBAppQueryResult, bk as MindooDBAppQueryRow, bl as MindooDBAppQuerySortKey, bm as MindooDBAppQueryTextClause, bn as MindooDBAppReadableAttachmentStream, bo as MindooDBAppRecipientOptions, bp as MindooDBAppResolvedViewDefinition, bq as MindooDBAppResolvedViewSource, br as MindooDBAppRevisionPhase, bs as MindooDBAppRevisionVerification, bt as MindooDBAppRichTextBlockSpan, bu as MindooDBAppRichTextGetOptions, bv as MindooDBAppRichTextImmutableString, bw as MindooDBAppRichTextMarkRange, bx as MindooDBAppRichTextMaterializeValue, by as MindooDBAppRichTextPatch, bz as MindooDBAppRichTextScalar, bA as MindooDBAppRichTextSpliceStep, bB as MindooDBAppRichTextStep, bC as MindooDBAppRichTextStepPatch, bD as MindooDBAppRichTextTextSpan, bE as MindooDBAppRuntime, bF as MindooDBAppScanAttachmentOptions, bG as MindooDBAppScanAttachmentResult, bH as MindooDBAppScopedDocId, bI as MindooDBAppScopedDocumentSummary, bJ as MindooDBAppSealIntent, bK as MindooDBAppSealedChannelOpenInput, bL as MindooDBAppSealedChannelOpenResult, bM as MindooDBAppSealedChannelRequestInput, bN as MindooDBAppSession, bO as MindooDBAppShowMenuInput, bP as MindooDBAppShowMenuResult, bQ as MindooDBAppSignPreview, bR as MindooDBAppSignPreviewScope, bS as MindooDBAppSignStatementInput, bT as MindooDBAppSignStatementResult, bU as MindooDBAppStorageApi, bV as MindooDBAppTextEdit, bW as MindooDBAppTextPatch, bX as MindooDBAppThemeMode, bY as MindooDBAppTimestampApi, bZ as MindooDBAppTimestampInput, b_ as MindooDBAppTimestampProvider, b$ as MindooDBAppTimestampResult, c0 as MindooDBAppUiPreferences, c1 as MindooDBAppUpdateDocumentInput, c2 as MindooDBAppViewCursorDocumentListResult, c3 as MindooDBAppViewCursorResult, c4 as MindooDBAppViewEntry, c5 as MindooDBAppViewEntryKind, c6 as MindooDBAppViewNavigator, c7 as MindooDBAppViewNavigatorExpansionState, c8 as MindooDBAppViewNavigatorOpenOptions, c9 as MindooDBAppViewNavigatorPageOptions, ca as MindooDBAppViewNavigatorPageResult, cb as MindooDBAppViewNavigatorRangeQuery, cc as MindooDBAppViewNavigatorSelectionState, cd as MindooDBAppViewUpdateStats, ce as MindooDBAppViewport, cf as MindooDBAppWellKnownDragType, cg as MindooDBAppWritableAttachmentStream } from './types-BaXvRKXY.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDatabase, j as MindooDBAppDocument, k as MindooDBAppRichTextSpan, l as MindooDBAppRichTextSnapshot } from './types-C-eyC839.js';
+export { m as MINDOODB_APP_DEFINITION_FILE_NAME, n as MINDOODB_APP_DEFINITION_FORMAT, o as MINDOODB_APP_DEFINITION_PERMISSIONS, p as MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS, q as MINDOODB_APP_DEFINITION_VERSION, r as MINDOODB_APP_SEAL_SIGNING_DOMAIN, s as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, t as MindooDBAppAccessDecision, u as MindooDBAppAccessTier, v as MindooDBAppAttachmentApi, w as MindooDBAppAttachmentChunk, x as MindooDBAppAttachmentInfo, y as MindooDBAppAttachmentPreviewOptions, z as MindooDBAppAttachmentPreviewSession, A as MindooDBAppAutomergeChangesPatch, B as MindooDBAppAutomergeChangesSince, C as MindooDBAppAutomergeGetOptions, D as MindooDBAppAutomergePatchResult, E as MindooDBAppAutomergeSnapshot, F as MindooDBAppBridgeBeforeCloseAck, G as MindooDBAppBridgeBeforeCloseMessage, H as MindooDBAppBridgeConnectMessage, I as MindooDBAppBridgeConnectOptions, J as MindooDBAppBridgeConnectedMessage, K as MindooDBAppBridgeDragDropMessage, L as MindooDBAppBridgeDragLeaveMessage, N as MindooDBAppBridgeDragOverMessage, O as MindooDBAppBridgeErrorPayload, P as MindooDBAppBridgeHandshakeErrorMessage, Q as MindooDBAppBridgeLocaleChangedMessage, R as MindooDBAppBridgePortMessage, S as MindooDBAppBridgeQueryResultMessage, T as MindooDBAppBridgeRpcError, U as MindooDBAppBridgeRpcMessage, V as MindooDBAppBridgeRpcRequest, W as MindooDBAppBridgeRpcSuccess, X as MindooDBAppBridgeShortcutInvokedMessage, Y as MindooDBAppBridgeShortcutsChangedMessage, Z as MindooDBAppBridgeStreamAbortRequest, _ as MindooDBAppBridgeStreamAck, $ as MindooDBAppBridgeStreamCloseRequest, a0 as MindooDBAppBridgeStreamError, a1 as MindooDBAppBridgeStreamMessage, a2 as MindooDBAppBridgeStreamOpenResult, a3 as MindooDBAppBridgeStreamReadRequest, a4 as MindooDBAppBridgeStreamWriteRequest, a5 as MindooDBAppBridgeThemeChangedMessage, a6 as MindooDBAppBridgeUiPreferencesChangedMessage, a7 as MindooDBAppBridgeViewChangedMessage, a8 as MindooDBAppBridgeViewportChangedMessage, a9 as MindooDBAppCapability, aa as MindooDBAppConfiguredViewCategorizationStyle, ab as MindooDBAppConfiguredViewColumn, ac as MindooDBAppConfiguredViewColumnRole, ad as MindooDBAppConfiguredViewExpressionMode, ae as MindooDBAppConfiguredViewFieldExpression, af as MindooDBAppConfiguredViewFilterDefinition, ag as MindooDBAppConfiguredViewFilterMode, ah as MindooDBAppConfiguredViewFilterRule, ai as MindooDBAppConfiguredViewFormulaExpression, aj as MindooDBAppConfiguredViewFormulaFilterDefinition, ak as MindooDBAppConfiguredViewPreviewMode, al as MindooDBAppConfiguredViewRuleFilterDefinition, am as MindooDBAppConfiguredViewRuleMatchMode, an as MindooDBAppConfiguredViewRuleOperator, ao as MindooDBAppConfiguredViewValueExpression, ap as MindooDBAppCreateDocumentInput, aq as MindooDBAppCreateKeyInfo, ar as MindooDBAppCreateViewInput, as as MindooDBAppCreateViewNavigatorInput, at as MindooDBAppDatabaseInfo, au as MindooDBAppDefinition, av as MindooDBAppDefinitionDatabase, aw as MindooDBAppDefinitionPermission, ax as MindooDBAppDefinitionRegistrationPermission, ay as MindooDBAppDefinitionValidation, az as MindooDBAppDirectoryApi, aA as MindooDBAppDirectoryEntry, aB as MindooDBAppDocumentApi, aC as MindooDBAppDocumentHeadCursorResult, aD as MindooDBAppDocumentHistoryEntry, aE as MindooDBAppDocumentListQuery, aF as MindooDBAppDocumentListResult, aG as MindooDBAppDocumentQuery, aH as MindooDBAppDocumentRevisionId, aI as MindooDBAppDocumentScanPreset, aJ as MindooDBAppDocumentSummary, aK as MindooDBAppDragApi, aL as MindooDBAppDragCancelReason, aM as MindooDBAppDragDropEvent, aN as MindooDBAppDragEffect, aO as MindooDBAppDragHoverResult, aP as MindooDBAppDragOffer, aQ as MindooDBAppDragOverEvent, aR as MindooDBAppDragPointer, aS as MindooDBAppDragProfile, aT as MindooDBAppEntryAttachmentRef, aU as MindooDBAppEntryProvenance, aV as MindooDBAppExtractDocumentTextInput, aW as MindooDBAppExtractDocumentTextResult, aX as MindooDBAppExtractTextFormat, aY as MindooDBAppExtractionSetup, aZ as MindooDBAppFulltextSetup, a_ as MindooDBAppHistoricalDocument, a$ as MindooDBAppHistoryQuery, b0 as MindooDBAppHostTheme, b1 as MindooDBAppIdentityApi, b2 as MindooDBAppInaccessibleDocument, b3 as MindooDBAppInaccessibleDocumentListQuery, b4 as MindooDBAppInaccessibleDocumentListResult, b5 as MindooDBAppJsonListDeletePatch, b6 as MindooDBAppJsonListInsertPatch, b7 as MindooDBAppJsonPatch, b8 as MindooDBAppJsonSetPatch, b9 as MindooDBAppJsonTextMarkPatch, ba as MindooDBAppJsonTextSplicePatch, bb as MindooDBAppJsonTextUnmarkPatch, bc as MindooDBAppJsonUnsetPatch, bd as MindooDBAppLaunchContext, be as MindooDBAppLiveQuerySubscription, bf as MindooDBAppMenuAnchor, bg as MindooDBAppMenuApi, bh as MindooDBAppMenuCommandItem, bi as MindooDBAppMenuDismissReason, bj as MindooDBAppMenuDismissedResult, bk as MindooDBAppMenuItem, bl as MindooDBAppMenuKind, bm as MindooDBAppMenuPlacement, bn as MindooDBAppMenuPointAnchor, bo as MindooDBAppMenuRect, bp as MindooDBAppMenuRectAnchor, bq as MindooDBAppMenuSelectionResult, br as MindooDBAppMenuSeparatorItem, bs as MindooDBAppProposeAppInput, bt as MindooDBAppProposeAppResult, bu as MindooDBAppQueryCoverage, bv as MindooDBAppQueryInclude, bw as MindooDBAppQueryIncludeCardinality, bx as MindooDBAppQueryIncludeSlots, by as MindooDBAppQueryResult, bz as MindooDBAppQueryRow, bA as MindooDBAppQuerySortKey, bB as MindooDBAppQueryTextClause, bC as MindooDBAppReadableAttachmentStream, bD as MindooDBAppRecipientOptions, bE as MindooDBAppResolvedViewDefinition, bF as MindooDBAppResolvedViewSource, bG as MindooDBAppRevisionPhase, bH as MindooDBAppRevisionVerification, bI as MindooDBAppRichTextBlockSpan, bJ as MindooDBAppRichTextGetOptions, bK as MindooDBAppRichTextImmutableString, bL as MindooDBAppRichTextMarkRange, bM as MindooDBAppRichTextMaterializeValue, bN as MindooDBAppRichTextPatch, bO as MindooDBAppRichTextScalar, bP as MindooDBAppRichTextSpliceStep, bQ as MindooDBAppRichTextStep, bR as MindooDBAppRichTextStepPatch, bS as MindooDBAppRichTextTextSpan, bT as MindooDBAppRuntime, bU as MindooDBAppScanAttachmentOptions, bV as MindooDBAppScanAttachmentResult, bW as MindooDBAppScopedDocId, bX as MindooDBAppScopedDocumentSummary, bY as MindooDBAppSealIntent, bZ as MindooDBAppSealedChannelOpenInput, b_ as MindooDBAppSealedChannelOpenResult, b$ as MindooDBAppSealedChannelRequestInput, c0 as MindooDBAppSession, c1 as MindooDBAppShowMenuInput, c2 as MindooDBAppShowMenuResult, c3 as MindooDBAppSignPreview, c4 as MindooDBAppSignPreviewScope, c5 as MindooDBAppSignStatementInput, c6 as MindooDBAppSignStatementResult, c7 as MindooDBAppStorageApi, c8 as MindooDBAppTextEdit, c9 as MindooDBAppTextPatch, ca as MindooDBAppThemeMode, cb as MindooDBAppTimestampApi, cc as MindooDBAppTimestampInput, cd as MindooDBAppTimestampProvider, ce as MindooDBAppTimestampResult, cf as MindooDBAppUiPreferences, cg as MindooDBAppUpdateDocumentInput, ch as MindooDBAppViewCursorDocumentListResult, ci as MindooDBAppViewCursorResult, cj as MindooDBAppViewEntry, ck as MindooDBAppViewEntryKind, cl as MindooDBAppViewNavigator, cm as MindooDBAppViewNavigatorExpansionState, cn as MindooDBAppViewNavigatorOpenOptions, co as MindooDBAppViewNavigatorPageOptions, cp as MindooDBAppViewNavigatorPageResult, cq as MindooDBAppViewNavigatorRangeQuery, cr as MindooDBAppViewNavigatorSelectionState, cs as MindooDBAppViewUpdateStats, ct as MindooDBAppViewport, cu as MindooDBAppWellKnownDragType, cv as MindooDBAppWritableAttachmentStream, cw as resolveMindooDBAppDefinitionUrl, cx as validateMindooDBAppDefinition } from './types-C-eyC839.js';
 export { M as MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME, a as MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME, b as MINDOODB_APP_BUNDLE_MANIFEST_FORMAT, c as MINDOODB_APP_BUNDLE_MANIFEST_VERSION, d as MindooDBAppBundleArchive, e as MindooDBAppBundleFileEntry, f as MindooDBAppBundleHash, g as MindooDBAppBundleManifest, h as MindooDBAppBundleManifestValidation, i as buildMindooDBAppBundleContentHashInput, j as isMindooDBAppBundleHash, n as normalizeMindooDBAppBundlePath, v as validateMindooDBAppBundleManifest } from './appBundleManifest-B0xfpaXG.js';
 import { MindooDBAppBooleanExpression } from 'mindoodb-view-language';
 export { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppFilterDefinition, MindooDBAppViewCategoryChildrenPageRequest, MindooDBAppViewColumn, MindooDBAppViewColumnRole, MindooDBAppViewDefinition, MindooDBAppViewExpansionState, MindooDBAppViewExpressionBase, MindooDBAppViewExpressionDatePart, MindooDBAppViewExpressionOperation, MindooDBAppViewFieldExpression, MindooDBAppViewIfExpression, MindooDBAppViewLetExpression, MindooDBAppViewLiteralExpression, MindooDBAppViewLookupByPath, MindooDBAppViewOperationExpression, MindooDBAppViewOriginExpression, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewRow, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewValueExpressionRef, MindooDBAppViewVariableExpression, createViewLanguage } from 'mindoodb-view-language';

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   releaseMindooDBAppBridgeSessions,
   sanitizeHostShortcutBindings,
   snapshotElementToPng
-} from "./chunk-XPPTUWW6.js";
+} from "./chunk-TPYDERAK.js";
 import {
   MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
@@ -42,6 +42,265 @@ var MINDOODB_APP_WELL_KNOWN_DRAG_TYPES = [
 ];
 var MINDOODB_APP_SEAL_SIGNING_DOMAIN = "mindoodb-seal/v1";
 
+// src/appDefinition.ts
+var MINDOODB_APP_DEFINITION_FORMAT = "mindoodb.haven.app";
+var MINDOODB_APP_DEFINITION_VERSION = 1;
+var MINDOODB_APP_DEFINITION_FILE_NAME = "haven-app.json";
+var MINDOODB_APP_DEFINITION_PERMISSIONS = [
+  "write",
+  "delete",
+  "history",
+  "attachments",
+  "views",
+  "sign",
+  "timestamps",
+  "directory",
+  "sealedchannel",
+  "proposeapps"
+];
+var MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS = ["proposeapps"];
+var LOGICAL_DATABASE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readOptionalString(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    errors.push(`App definition ${key} must be a string.`);
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function readOptionalBoolean(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "boolean") {
+    errors.push(`App definition ${key} must be a boolean.`);
+    return void 0;
+  }
+  return value || void 0;
+}
+function readStringRecord(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!isPlainObject(value)) {
+    errors.push(`App definition ${key} must be an object of string values.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue !== "string") {
+      errors.push(`App definition ${key}.${entryKey} must be a string.`);
+      continue;
+    }
+    result[entryKey] = entryValue;
+  }
+  return Object.keys(result).length ? result : void 0;
+}
+function readPermissions(value, label, allowed, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array of permission names.`);
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !allowed.includes(entry)) {
+      errors.push(`${label} contains the unknown permission ${JSON.stringify(entry)}.`);
+      continue;
+    }
+    if (!result.includes(entry)) {
+      result.push(entry);
+    }
+  }
+  return result.length ? result : void 0;
+}
+function readNetworkAllowlist(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition networkAllowlist must be an array of origins.");
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !entry.trim()) {
+      errors.push(`App definition networkAllowlist contains the invalid entry ${JSON.stringify(entry)}.`);
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (!result.includes(trimmed)) {
+      result.push(trimmed);
+    }
+  }
+  return result.length ? result : void 0;
+}
+function readDatabases(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition databases must be an array.");
+    return void 0;
+  }
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  value.forEach((entry, index) => {
+    if (!isPlainObject(entry)) {
+      errors.push(`App definition database #${index} must be an object.`);
+      return;
+    }
+    const logicalDatabaseId = typeof entry.logicalDatabaseId === "string" ? entry.logicalDatabaseId.trim() : "";
+    if (!logicalDatabaseId) {
+      errors.push(`App definition database #${index} is missing a non-empty logicalDatabaseId.`);
+      return;
+    }
+    if (!LOGICAL_DATABASE_ID_PATTERN.test(logicalDatabaseId)) {
+      errors.push(
+        `App definition database "${logicalDatabaseId}" must match ${String(LOGICAL_DATABASE_ID_PATTERN)}.`
+      );
+      return;
+    }
+    if (seen.has(logicalDatabaseId)) {
+      errors.push(`App definition lists the database "${logicalDatabaseId}" more than once.`);
+      return;
+    }
+    seen.add(logicalDatabaseId);
+    const databaseId = typeof entry.databaseId === "string" ? entry.databaseId.trim() : "";
+    if (entry.databaseId !== void 0 && entry.databaseId !== null && !databaseId) {
+      errors.push(`App definition database "${logicalDatabaseId}" has an empty databaseId.`);
+    }
+    result.push({
+      logicalDatabaseId,
+      label: typeof entry.label === "string" && entry.label.trim() ? entry.label.trim() : void 0,
+      databaseId: databaseId || void 0,
+      permissions: readPermissions(
+        entry.permissions,
+        `App definition database "${logicalDatabaseId}" permissions`,
+        MINDOODB_APP_DEFINITION_PERMISSIONS.filter(
+          (permission) => !MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS.includes(permission)
+        ),
+        errors
+      ),
+      create: entry.create === false ? false : void 0
+    });
+  });
+  return result.length ? result : void 0;
+}
+function validateMindooDBAppDefinition(raw) {
+  const errors = [];
+  if (!isPlainObject(raw)) {
+    return { definition: null, errors: ["App definition must be a JSON object."] };
+  }
+  if (raw.format !== MINDOODB_APP_DEFINITION_FORMAT) {
+    errors.push(
+      `App definition format must be "${MINDOODB_APP_DEFINITION_FORMAT}", received ${JSON.stringify(raw.format)}.`
+    );
+  }
+  if (raw.formatVersion !== MINDOODB_APP_DEFINITION_VERSION) {
+    errors.push(
+      `Unsupported app definition version ${JSON.stringify(raw.formatVersion)}, expected ${MINDOODB_APP_DEFINITION_VERSION}.`
+    );
+  }
+  const appId = typeof raw.appId === "string" ? raw.appId.trim() : "";
+  if (!appId) {
+    errors.push("App definition is missing a non-empty appId.");
+  }
+  const label = typeof raw.label === "string" ? raw.label.trim() : "";
+  if (!label) {
+    errors.push("App definition is missing a non-empty label.");
+  }
+  const runtime = raw.runtime;
+  if (runtime !== void 0 && runtime !== "iframe" && runtime !== "window") {
+    errors.push(`App definition runtime must be "iframe" or "window", received ${JSON.stringify(runtime)}.`);
+  }
+  const hosting = raw.hosting;
+  if (hosting !== void 0 && hosting !== "external" && hosting !== "hosted") {
+    errors.push(
+      `App definition hosting must be "external" or "hosted", received ${JSON.stringify(hosting)}.`
+    );
+  }
+  const description = readOptionalString(raw, "description", errors);
+  const version = readOptionalString(raw, "version", errors);
+  const defaultLaunchDatabaseId = readOptionalString(raw, "defaultLaunchDatabaseId", errors);
+  const networkAllowlist = readNetworkAllowlist(raw.networkAllowlist, errors);
+  const launchParameters = readStringRecord(raw, "launchParameters", errors);
+  const databases = readDatabases(raw.databases, errors);
+  const permissions = readPermissions(
+    raw.permissions,
+    "App definition permissions",
+    MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS,
+    errors
+  );
+  const allowPopups = readOptionalBoolean(raw, "allowPopups", errors);
+  const allowCamera = readOptionalBoolean(raw, "allowCamera", errors);
+  const allowMicrophone = readOptionalBoolean(raw, "allowMicrophone", errors);
+  const allowGeolocation = readOptionalBoolean(raw, "allowGeolocation", errors);
+  const allowWebRtc = readOptionalBoolean(raw, "allowWebRtc", errors);
+  const allowWorkers = readOptionalBoolean(raw, "allowWorkers", errors);
+  if (defaultLaunchDatabaseId && databases && !databases.some((database) => database.logicalDatabaseId === defaultLaunchDatabaseId)) {
+    errors.push(
+      `App definition defaultLaunchDatabaseId "${defaultLaunchDatabaseId}" is not one of the declared databases.`
+    );
+  }
+  if (errors.length) {
+    return { definition: null, errors };
+  }
+  return {
+    definition: {
+      format: MINDOODB_APP_DEFINITION_FORMAT,
+      formatVersion: MINDOODB_APP_DEFINITION_VERSION,
+      appId,
+      label,
+      description,
+      version,
+      runtime,
+      hosting,
+      networkAllowlist,
+      allowPopups,
+      allowCamera,
+      allowMicrophone,
+      allowGeolocation,
+      allowWebRtc,
+      allowWorkers,
+      permissions,
+      launchParameters,
+      defaultLaunchDatabaseId,
+      databases
+    },
+    errors: []
+  };
+}
+function resolveMindooDBAppDefinitionUrl(baseUrl) {
+  const trimmed = baseUrl.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const suffix = `/${MINDOODB_APP_DEFINITION_FILE_NAME}`;
+  try {
+    const url = new URL(trimmed);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    url.search = "";
+    url.hash = "";
+    url.pathname = path.endsWith(suffix) || path === suffix ? path : `${path === "/" ? "" : path}${suffix}`;
+    return url.toString();
+  } catch {
+    const withoutSlash = trimmed.replace(/\/+$/, "");
+    return withoutSlash.toLowerCase().endsWith(suffix) ? withoutSlash : `${withoutSlash}${suffix}`;
+  }
+}
+
 // src/attachmentPreview.ts
 function canPreviewAttachment(fileName, mimeType) {
   const normalizedMimeType = mimeType.toLowerCase();
@@ -780,6 +1039,11 @@ export {
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FORMAT,
   MINDOODB_APP_BUNDLE_MANIFEST_VERSION,
+  MINDOODB_APP_DEFINITION_FILE_NAME,
+  MINDOODB_APP_DEFINITION_FORMAT,
+  MINDOODB_APP_DEFINITION_PERMISSIONS,
+  MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS,
+  MINDOODB_APP_DEFINITION_VERSION,
   MINDOODB_APP_HOSTING_QUERY_PARAM,
   MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
   MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,
@@ -815,7 +1079,9 @@ export {
   queryDocuments,
   readMindooDBAppHostingMode,
   releaseMindooDBAppBridgeSessions,
+  resolveMindooDBAppDefinitionUrl,
   sanitizeHostShortcutBindings,
   snapshotElementToPng,
-  validateMindooDBAppBundleManifest
+  validateMindooDBAppBundleManifest,
+  validateMindooDBAppDefinition
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { an as MindooDBAppCreateViewNavigatorInput, c6 as MindooDBAppViewNavigator, b3 as MindooDBAppLaunchContext, ao as MindooDBAppDatabaseInfo, ar as MindooDBAppDocumentApi, c8 as MindooDBAppViewNavigatorOpenOptions, q as MindooDBAppAttachmentApi, aT as MindooDBAppIdentityApi, bY as MindooDBAppTimestampApi, ap as MindooDBAppDirectoryApi, j as MindooDBAppDocument, aP as MindooDBAppFulltextSetup, aO as MindooDBAppExtractionSetup, e as MindooDBAppBridge, bN as MindooDBAppSession, Q as MindooDBAppBridgeRpcRequest, aS as MindooDBAppHostTheme, ce as MindooDBAppViewport, c0 as MindooDBAppUiPreferences, bj as MindooDBAppQueryResult, cd as MindooDBAppViewUpdateStats, L as MindooDBAppBridgePortMessage, c as MindooDBAppDragStartResult, aI as MindooDBAppDragProfile } from '../types-BaXvRKXY.js';
+import { as as MindooDBAppCreateViewNavigatorInput, cl as MindooDBAppViewNavigator, bd as MindooDBAppLaunchContext, at as MindooDBAppDatabaseInfo, aB as MindooDBAppDocumentApi, cn as MindooDBAppViewNavigatorOpenOptions, v as MindooDBAppAttachmentApi, b1 as MindooDBAppIdentityApi, cb as MindooDBAppTimestampApi, az as MindooDBAppDirectoryApi, j as MindooDBAppDocument, aZ as MindooDBAppFulltextSetup, aY as MindooDBAppExtractionSetup, bs as MindooDBAppProposeAppInput, bt as MindooDBAppProposeAppResult, e as MindooDBAppBridge, c0 as MindooDBAppSession, V as MindooDBAppBridgeRpcRequest, b0 as MindooDBAppHostTheme, ct as MindooDBAppViewport, cf as MindooDBAppUiPreferences, by as MindooDBAppQueryResult, cs as MindooDBAppViewUpdateStats, R as MindooDBAppBridgePortMessage, c as MindooDBAppDragStartResult, aS as MindooDBAppDragProfile } from '../types-C-eyC839.js';
 import * as mindoodb from 'mindoodb';
 import 'mindoodb-view-language';
 
@@ -98,6 +98,11 @@ interface CreateMockMindooDBAppSessionOptions {
     databases?: MockMindooDBAppDatabaseDefinition[];
     onDisconnect?: () => MaybePromise<void>;
     sealedChannel?: MockSealedChannelOptions;
+    /**
+     * Answer for `session.proposeApp`, standing in for the user's decision in the
+     * real host's consent dialog. Omitted means declined.
+     */
+    proposeApp?: (input: MindooDBAppProposeAppInput) => MindooDBAppProposeAppResult;
     /** Initial contents of `session.storage`. */
     storage?: Record<string, string>;
 }
@@ -107,6 +112,8 @@ interface MockMindooDBAppSessionController {
     getLaunchContext(): MindooDBAppLaunchContext;
     setLaunchContext(patch?: Partial<MindooDBAppLaunchContext>): MindooDBAppLaunchContext;
     getLicensedProducts(): string[];
+    /** Every `proposeApp` call the app under test made, in order. */
+    proposedApps: MindooDBAppProposeAppInput[];
     listDatabases(): MindooDBAppDatabaseInfo[];
     setDatabases(definitions: MockMindooDBAppDatabaseDefinition[]): void;
     emitThemeChange(theme: MindooDBAppHostTheme): void;
@@ -140,6 +147,8 @@ interface FakeBridgeHostController {
     session: MindooDBAppSession;
     readonly launchId: string;
     readonly requests: ReadonlyArray<MindooDBAppBridgeRpcRequest>;
+    /** Every `apps.propose` call the app under test made, in order. */
+    readonly proposedApps: ReadonlyArray<MindooDBAppProposeAppInput>;
     install(): void;
     dispose(): void;
     emitThemeChange(theme: MindooDBAppHostTheme): void;