mindoodb-app-sdk 0.0.40 → 0.0.42

package/README.md

@@ -412,6 +412,8 @@ await db.documents.undelete(docId);
 
 Every `MindooDBAppDocument` snapshot also exposes a `heads?: string[]` field. Those heads identify the document's current Automerge version and are the value you pass to `baseHeads` when issuing the next text patch. After Haven applies and merges your patch, the returned document carries the new `heads` you should use for the following edit cycle.
 
+A snapshot also carries `decryptionKeyId?: string` — the named shared key its payload is encrypted with (`"default"` unless the document was created with another key). That is the key someone else needs access to before they can open the document, so show it wherever an app offers sharing. It is absent for person-encrypted documents (created with `recipients`), which have no shareable named key: those are shared by editing the recipient list. It is also absent on Haven versions older than this field.
+
 `documents.list()` is backed by Haven's internal changefeed, not by a positional offset. The query object supports:
 
 | Field                                       | Meaning                                                                        |
@@ -455,7 +457,8 @@ const history = await db.documents.listHistory(docId);
 //   isDeleted,
 //   isCurrent,
 //   summary?,
-//   dependencyIds?
+//   dependencyIds?,
+//   decryptionKeyId?
 // }
 
 // Load the document state at an exact DAG revision
@@ -504,6 +507,8 @@ const merged = await db.documents.getAtHeads(docId, entry.dependencyIds ?? []);
 
 An id in `dependencyIds` may name a revision the timeline does not list, because a change that left the document state untouched produces no timeline row. Draw only the edges whose endpoints you have; `getAtHeads` still resolves the full list.
 
+`decryptionKeyId` is per revision, so a document whose key changed over its life shows that in the timeline — useful when deciding which key to grant before handing an old version to someone. It follows the same rule as on `documents.get`: absent for person-encrypted revisions.
+
 ### Granular JSON edits
 
 When you need to edit nested objects or lists inside a document — not just top-level fields — describe the change as a **granular JSON patch** rather than rewriting the whole document. This is the model behind structured collaborative editing in apps like [`mindoodb-app-teamgrid`](https://github.com/klehmann/mindoodb-app-teamgrid), where two users can insert different rows into the same worksheet on different devices and the merge keeps both sides cleanly.
@@ -1467,7 +1472,70 @@ wrangler deploy
 
 Other static hosting options work just as well: Netlify, Vercel, any web server serving your `dist/` folder.
 
-**Haven-hosted bundles** are an alternative: import your built app directly into Haven, where it is served by a service worker on an opaque origin. Haven-hosted apps load without a network connection and receive a stricter sandbox.
+### Haven-hosted bundles
+
+Instead of Haven loading your app from your server on every launch, you can hand Haven the build itself. Haven stores it in its own cache and serves it from a service worker on an opaque origin, so the app loads offline and runs in a stricter sandbox than an external URL gets.
+
+You can upload a build directory by hand, but the useful form is to publish a **bundle manifest** next to your app and let Haven fetch and update it. Add the plugin to your Vite config:
+
+```ts
+import { havenBundle } from "mindoodb-app-sdk/vite";
+
+export default defineConfig({
+  // Haven serves the bundle under a path it picks, so assets must be relative.
+  base: "./",
+  plugins: [havenBundle()],
+});
+```
+
+After `vite build`, `dist/` additionally contains `haven-bundle.json` (app id, version, a SHA-256 for every file, and one for the bundle as a whole) and `haven-bundle.zip` (all of it in one archive). The app's own service worker files are left out — Haven serves the bundle and a second service worker would only fight it for the scope. The user pastes the URL of `haven-bundle.json` into Haven's application settings; Haven downloads the archive, rejects it unless every hash matches the manifest, and installs it.
+
+Haven then owns updates. It re-reads the manifest before launches and on a slow background timer, and installs a new version when the `contentHash` changes — which means an app in hosted mode should **not** run its own update logic:
+
+```ts
+import { isHostedBundleRuntime } from "mindoodb-app-sdk";
+
+if (!isHostedBundleRuntime()) {
+  registerServiceWorker();
+}
+```
+
+Serving the manifest and archive to Haven needs CORS, since Haven is on a different origin than your app:
+
+```
+/haven-bundle.json
+  Access-Control-Allow-Origin: *
+  Cache-Control: no-cache
+
+/haven-bundle.zip
+  Access-Control-Allow-Origin: *
+  Cache-Control: public, max-age=300
+```
+
+The manifest must not be cached — it is the signal that a new version exists. The archive can be, because the manifest pins it by hash.
+
+#### Storage in hosted mode
+
+An opaque origin has no storage: touching `localStorage` throws a `SecurityError`. The host keeps a small amount of key/value state for the app instead, reachable at `session.storage`:
+
+```ts
+await session.storage.set("my-app.theme", "dark");
+const theme = await session.storage.get("my-app.theme");
+```
+
+That is asynchronous, and most existing app code reads preferences synchronously during render. For those, install a shim before the app boots. It replaces the global `localStorage` with one hydrated from the host, serves reads from memory, and writes keys under the given prefixes back to the host in the background:
+
+```ts
+// entry point, before importing the app
+await installHavenStorageShim({ persistPrefixes: ["my-app-"] });
+await import("./main");
+```
+
+Outside hosted mode this does nothing and the real `localStorage` stays in place. Keys outside `persistPrefixes` still work but live only for the session — a deliberate choice, since the budget is meant for preferences.
+
+Two things are worth knowing when you use it. Writes are coalesced, so a value written on every `pointermove` costs one message rather than sixty per second; still, prefer committing such a value once when the interaction ends. And the budget is finite (256 KB per installed app, 64 KB per value), so `setItem` can throw `QuotaExceededError` just as it can in a browser. Anything larger than a preference belongs in a database.
+
+Haven asks the app to flush pending writes before it tears the iframe down, so a preference set immediately before closing is not lost. The shim answers that on its own.
 
 ## Local development workflow
 
@@ -1505,10 +1573,25 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `closeSealedChannel(channelId)`       | `Promise<void>`                      |
 | `menus.show(input)`                   | `Promise<MindooDBAppShowMenuResult>` |
 | `menus.hide()`                        | `Promise<void>`                      |
+| `storage`                             | `MindooDBAppStorageApi`              |
 | `onThemeChange(listener)`             | `() => void` (unsubscribe)           |
 | `onViewportChange(listener)`          | `() => void` (unsubscribe)           |
+| `onBeforeClose(listener)`             | `() => void` (unsubscribe)           |
 | `disconnect()`                        | `Promise<void>`                      |
 
+### MindooDBAppStorageApi
+
+Host-kept key/value state, the only durable storage a hosted app has. See [Storage in hosted mode](#storage-in-hosted-mode).
+
+| Method                | Returns                             |
+| --------------------- | ----------------------------------- |
+| `snapshot(options?)`  | `Promise<Record<string, string>>`   |
+| `get(key)`            | `Promise<string \| null>`           |
+| `set(key, value)`     | `Promise<void>`                     |
+| `remove(key)`         | `Promise<void>`                     |
+| `keys(options?)`      | `Promise<string[]>`                 |
+| `clear(options?)`     | `Promise<void>`                     |
+
 ### MindooDBAppDatabase
 
 | Property / Method            | Returns                                        |
@@ -1549,7 +1632,7 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 
 `list(query?)` accepts the changefeed query options documented above. The `cursor` value is an opaque checkpoint string managed by Haven and should be stored and passed back unchanged.
 
-`listInaccessible(query?)` returns documents that exist locally but the current user cannot decrypt (not a recipient, or missing the document key). Those ids never appear in `list` / `get`. Each row is unsigned store metadata only (`id`, `createdAt`, `decryptionKeyId`, optional `authorLabel`) — the app does not get CAS access. Use it to distinguish an empty database from one sealed to someone else.
+`listInaccessible(query?)` returns documents that exist locally but the current user cannot decrypt (not a recipient, or missing the document key). Those ids never appear in `list` / `get`. Each row is unsigned store metadata only (`id`, `createdAt`, `decryptionKeyId`, optional `authorLabel`) — the app does not get CAS access. Use it to distinguish an empty database from one sealed to someone else. For documents the user *can* open, the same key id is on `documents.get` and on each `listHistory` entry; `documents.list` rows do not carry it.
 
 For `create(input)`, use `MindooDBAppCreateDocumentInput` with shape `{ set: Record<string, unknown>; decryptionKeyId?: string; recipients?: string[]; recipientOptions?: { includeSelf?: boolean }; id?: string }`. Omit both `decryptionKeyId` and `recipients` to use the database default shared key (`getDefaultCreateKeyId()` / `listCreateKeys()`). Pass `recipients` to encrypt the document for specific directory users (the launching user is included unless `recipientOptions.includeSelf` is `false`). Use `includeSelf: false` to write initial `set` values and hand the document to someone else — empty `recipients` with `includeSelf: false` is rejected. Changing that list later is `addRecipients` / `removeRecipients` / `setRecipients` — do not write `_encryptFor` via `update`. The optional `id` lets the app pick the document id instead of letting MindooDB generate an ObjectId; when provided it must match `/^[a-z][a-z0-9_]*$/` (lowercase only, since ids become on-disk filenames) and existing live documents with that id are returned as-is (idempotent create-if-missing). If an existing custom-id document is deleted, `create({ id })` undeletes it and preserves the previous document body. Documents created with the same custom id on different replicas converge correctly when synced.
 
@@ -1637,6 +1720,14 @@ interface MindooDBAppUpdateDocumentInput {
 | `createViewLanguage<T>()`                  | Create a typed expression builder for view definitions                                      |
 | `abbreviateCanonicalName(value)`           | Convert a canonical Notes-style name like `cn=Jane/ou=Dev/o=Mindoo` to `Jane/Dev/Mindoo`    |
 | `expandAbbreviatedName(value)`             | Convert an abbreviated Notes-style name like `Jane/Dev/Mindoo` to `cn=Jane/ou=Dev/o=Mindoo` |
+| `isHostedBundleRuntime(search?)`           | Whether Haven is serving this app as a hosted bundle rather than from its own URL           |
+| `installHavenStorageShim(options?)`        | Replace `localStorage` with a host-backed shim in hosted mode; a no-op everywhere else      |
+
+The Vite plugin lives behind its own entrypoint:
+
+| Function                | Import from               | Description                                              |
+| ----------------------- | ------------------------- | -------------------------------------------------------- |
+| `havenBundle(options?)` | `mindoodb-app-sdk/vite`   | Emit `haven-bundle.json` and `haven-bundle.zip` on build |
 
 ## Permissions and mappings
 

package/TESTING.md

@@ -102,7 +102,7 @@ When you pass `databases`, the mock session also exposes them through `session.g
 Each database entry can provide:
 
 - `info`
-- `documents` — seed documents into the mock store (used by `list`/`query` and by evaluating VirtualViews)
+- `documents` — seed documents into the mock store (used by `list`/`query` and by evaluating VirtualViews). A seed's `decryptionKeyId` is reported back by `documents.get`, like a real host; documents created through the mock report `"default"` unless `create` named a key, and person-encrypted documents (`recipients`) report none.
 - `methods.documents`
 - `methods.views` for session-level `createView()` and `openView()` calls (overrides the default evaluating navigator)
 - `methods.attachments`

package/dist/appBundleManifest-B0xfpaXG.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared description of a built application bundle that a MindooDB host can install
+ * and update from a URL.
+ *
+ * The build side (`mindoodb-app-sdk/vite`) writes the manifest, the host side reads and
+ * validates it. Both import this module so the format has exactly one definition.
+ */
+declare const MINDOODB_APP_BUNDLE_MANIFEST_FORMAT = "mindoodb.app.bundle";
+declare const MINDOODB_APP_BUNDLE_MANIFEST_VERSION = 1;
+declare const MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME = "haven-bundle.json";
+declare const MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME = "haven-bundle.zip";
+/** A `sha256-<64 lowercase hex chars>` digest string. */
+type MindooDBAppBundleHash = string;
+interface MindooDBAppBundleFileEntry {
+    /** Bundle-relative POSIX path, e.g. `assets/index-a1b2c3.js`. */
+    path: string;
+    hash: MindooDBAppBundleHash;
+    size: number;
+}
+interface MindooDBAppBundleArchive {
+    /** Path of the archive relative to the manifest URL. */
+    path: string;
+    hash: MindooDBAppBundleHash;
+    size: number;
+}
+interface MindooDBAppBundleManifest {
+    format: typeof MINDOODB_APP_BUNDLE_MANIFEST_FORMAT;
+    formatVersion: number;
+    /** Stable identifier of the application, used to detect a swapped bundle source. */
+    appId: string;
+    /** Human-readable version. Informational only — updates key off `contentHash`. */
+    version: string;
+    /** Entry HTML file, always present in `files`. */
+    entry: string;
+    archive: MindooDBAppBundleArchive;
+    /** Identity of the bundle: a digest over the sorted file list. */
+    contentHash: MindooDBAppBundleHash;
+    generatedAt: string;
+    files: MindooDBAppBundleFileEntry[];
+}
+declare function isMindooDBAppBundleHash(value: unknown): value is MindooDBAppBundleHash;
+/**
+ * Mirrors the host-side path rules: POSIX separators, no leading slash, no `.`/`..`
+ * segments and no empty segments. Returns `null` for paths that must be rejected.
+ */
+declare function normalizeMindooDBAppBundlePath(rawPath: unknown): string | null;
+/**
+ * Canonical byte input for `contentHash`. Both the build and the host derive the digest
+ * from this exact string so a mismatch always means the content really differs.
+ */
+declare function buildMindooDBAppBundleContentHashInput(files: readonly Pick<MindooDBAppBundleFileEntry, "path" | "hash">[]): string;
+interface MindooDBAppBundleManifestValidation {
+    manifest: MindooDBAppBundleManifest | null;
+    errors: string[];
+}
+/**
+ * Structural validation only — it does not verify any digest. Callers still have to
+ * compare `contentHash` and the per-file hashes against the bytes they downloaded.
+ */
+declare function validateMindooDBAppBundleManifest(raw: unknown): MindooDBAppBundleManifestValidation;
+
+export { MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME as M, MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME as a, MINDOODB_APP_BUNDLE_MANIFEST_FORMAT as b, MINDOODB_APP_BUNDLE_MANIFEST_VERSION as c, type MindooDBAppBundleArchive as d, type MindooDBAppBundleFileEntry as e, type MindooDBAppBundleHash as f, type MindooDBAppBundleManifest as g, type MindooDBAppBundleManifestValidation as h, buildMindooDBAppBundleContentHashInput as i, isMindooDBAppBundleHash as j, normalizeMindooDBAppBundlePath as n, validateMindooDBAppBundleManifest as v };