Inbox API

The inbox is the editor's numbered note tray. Public frontend code uses getBackend().inbox; the shipped cloud-primary adapter stores numbered notes as encrypted workspace documents.

Numbered inbox documents use workspace-relative keys such as:

inbox/1.md
inbox/2.md

Bridge Surface

const backend = getBackend();

await backend.inbox.write(1, "# Draft 1");
const body = await backend.inbox.read(1);
const active = await backend.inbox.getActive();

BackendAPI.inbox exposes:

Method	Description
`read(n)`	Read `inbox/N.md`; returns `null` if the slot is absent.
`write(n, content)`	Write the `inbox/N.md` workspace document.
`delete(n)`	Delete an inbox slot while preserving the inbox floor of at least one draft.
`getActive()` / `setActive(n)`	Read or write the inbox active draft number.
`getCount()`	Return the highest numbered inbox slot, floored to `1`.
`new()`	Create the next inbox slot and make it active.
`tidyUp()`	Compact non-empty slots and keep at least `1.md`.
`reorder(order)`	Reorder numbered inbox slots and keep the active draft aligned.
`onChanged(cb)`	Subscribe to inbox directory changes.
`watchActive(n)` / `unwatchActive()`	Compatibility methods: resolved no-ops in cloud mode because the workspace drain delivers changes; the `RestAdapter` retains local watcher endpoints for `dev:rest`.
`onExternalChange(cb)`	Subscribe to incoming changes for the active inbox document; cloud changes arrive through the workspace drain.

Local-engine notes compatibility

Caution

The notes_* and inbox_* names and direct invoke() examples in the next two sections preserve the old local command contract. They are not registered Tauri IPC commands today and cannot be invoked by the cloud-primary renderer. The Rust functions and matching HTTP routes remain for the pnpm dev:restlocal-engine compatibility path. Production code uses the bridge surface above.

The local storage operations are shared with other Note Tray directories through directory-parameterized notes_* functions and HTTP routes.

notes_read

const content = await invoke<string | null>("notes_read", {
  dir: "inbox",
  n: 1,
});

notes_write

const success = await invoke<boolean>("notes_write", {
  dir: "inbox",
  n: 1,
  content: "# Draft 1",
});

notes_delete

const result = await invoke<InboxDeleteResult | null>("notes_delete", {
  dir: "inbox",
  n: 2,
});

For raw notes_delete, deleting the last note in a directory can return { newCount: 0, newActive: 0 }. The bridge-level inbox.delete() wraps this with inbox-specific floor behavior and recreates an empty 1.md when needed.

interface InboxDeleteResult {
  newCount: number;
  newActive: number;
}

notes_new and notes_get_count

const n = await invoke<number>("notes_new", { dir: "inbox" });
const count = await invoke<number>("notes_get_count", { dir: "inbox" });

notes_get_count reports the highest present numeric slot. inbox.getCount() floors this value to 1.

notes_tidy_up

const result = await invoke<TidyUpResult | null>("notes_tidy_up", {
  dir: "inbox",
  active: 3,
});

notes_reorder

const result = await invoke<TidyUpResult | null>("notes_reorder", {
  dir: "inbox",
  order: [3, 1, 2],
  active: 3,
});

interface TidyUpResult {
  newCount: number;
  newActive: number;
}

Local-engine active-inbox compatibility

Active selection is intentionally inbox-only.

inbox_get_active

const activeDraft = await invoke<number>("inbox_get_active");

The historical command returned the active inbox draft number from local settings, defaulting to 1. The current bridge stores this selection in machine-local transient state instead.

inbox_set_active

const ok = await invoke<boolean>("inbox_set_active", {
  draftNumber: 2,
});

Returns false for invalid numbers outside the supported 1..99 range.

inbox_watch_active

await invoke<boolean>("inbox_watch_active", {
  draftNumber: 1,
});

Watches inbox/1.md for external writes. Only one active inbox watcher is held at a time; starting a new watch replaces the previous one.

inbox_unwatch_active

await invoke<boolean>("inbox_unwatch_active");

Stops the active inbox file watcher.

Events

notes:changed (local-engine compatibility)

The non-cloud dev:rest adapter subscribes to this SSE event to refresh inbox state when local numbered files are added, removed, or renamed. Cloud adapters derive the same bridge callback from committed workspace changes.

draft:externalChange (local-engine compatibility)

The non-cloud dev:rest engine emits this SSE event when its watched local inbox file is modified by an external process. Cloud adapters instead publish incoming workspace changes through the bridge callback.

const unsubscribe = backend.inbox.onExternalChange((draftNumber) => {
  console.log(draftNumber);
});

unsubscribe();

The bridge-level subscription in both modes is backend.inbox.onExternalChange(cb); production code does not listen to the local event name directly.

Sync Behavior

Draft content is saved by the frontend hooks. useDraftAutoSave writes through backend.inbox.write() after a debounce. On draft switch, the frontend saves the current slot, reads the target slot, and updates the inbox active selection.

There is no local-workspace active-file path in this API. Cloud inbox documents are addressed by workspace-relative keys through the bridge.