@drift-beacon/plugin 0.2.0 → 0.2.1

package/README.md

@@ -201,9 +201,9 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 
 `main/src/index.ts` default-exports `definePlugin({ onStart(ctx) { … } })`. The server runs one **instance** for each user and workspace that enabled the plugin; each gets its own `ctx`.
 
-- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. If it throws, the instance doesn't start.
+- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. Callbacks and routes work as soon as they are registered. If it throws, the instance doesn't start.
 - **Register through `ctx`.** Callbacks, routes and MQTT subscriptions made through `ctx` are released when the instance stops. Keep per-instance state inside `onStart`, never at module scope: the module is shared by every instance.
-- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total. Afterwards every `ctx` call throws `PluginError` with code `stopped`.
+- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total, whatever stops the instance (a fault or server shutdown too, even when something else stops it meanwhile). Afterwards every `ctx` call throws `PluginError` with code `stopped`. A server that is killed rather than shut down cuts them short.
 - **Faults.** An uncaught error or unhandled rejection stops only that instance, which is retried after 5, 30 and 120 seconds.
 
 | `ctx` member | Main | UI | |
@@ -214,13 +214,13 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 | `onDataChange` | ✓ | ✓ | The data changed |
 | `sessions.onStarted`, `onEnded`, `onMarked` | ✓ | | Live session events |
 | `storage` | ✓ | ✓ | Key-value storage |
-| `plugins` | ✓ | ✓ | The plugins it uses and itself: status, state and commands (and events, in main code) |
+| `plugins` | ✓ | ✓ | The plugins it uses and itself: status, state, events and commands |
 | `commands`, `events`, `state` | ✓ | | What it provides to other plugins |
 | `mqtt`, `routes`, `log`, `onStop` | ✓ | | Main code only |
 
 ## UI
 
-`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings, storage, or other plugins' status and state).
+`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings, storage, or other plugins' status and state; not their events).
 
 With React, re-render on every update:
 
@@ -301,7 +301,7 @@ await ctx.sessions.end(sessionId);      // or session.end(), activity.end()
 await ctx.sessions.discard(sessionId);  // or session.discard()
 ```
 
-Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app.
+Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app. An id that isn't a non-empty string rejects with `invalid`.
 
 | | Live session events | Data change events |
 |---|---|---|
@@ -314,7 +314,7 @@ Never trigger actions from data changes. Live events fire for everyone's session
 
 ## Storage
 
-Per plugin, user and workspace, shared by main code and the UI. Values must be JSON: anything else rejects with `invalid`, and setting `undefined` removes the key. `set` and `remove` apply at once and resolve when Drift Beacon has accepted the write.
+Per plugin, user and workspace, shared by main code and the UI. Keys are non-empty strings and values must be JSON: anything else rejects with `invalid`, and setting `undefined` removes the key. `set` and `remove` apply at once and resolve when Drift Beacon has accepted the write.
 
 ```ts
 const faces = ctx.storage.get<Record<string, string>>("faces") ?? {};
@@ -327,7 +327,7 @@ ctx.storage.onChange((key, value) => { /* changed by main code, a UI or another
 
 `ctx.config` holds the settings from the manifest's `configuration`. `dbplugin prepare` turns them into types (`.drift-beacon/config.d.ts`), so `ctx.config.mqttTopic` is typed in main code and the UI. A setting is optional unless it is `required` or has a `default`. An instance only runs with valid settings; changing them restarts it.
 
-A UI can open before setup is finished. Until then its `ctx.config` holds the defaults under whatever the user has saved, unvalidated: a `required` setting can still be missing. Check before relying on one.
+The app blocks opening a UI when required settings are missing or blank. This presence check does not validate every setting: if saved values fail schema validation, the UI receives defaults under the saved values while main does not run. Check values before relying on them.
 
 ## MQTT and HTTP routes
 
@@ -341,12 +341,12 @@ ctx.routes.post("webhook", async ({ body }) => ({ status: 202, body: { ok: true
 ctx.routes.get("status", () => ({ body: { live: ctx.sessions.live({ mine: true }).length } }));
 ```
 
-- MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one.
-- Routes are served at `<server>/api/plugins/<plugin id>/api/<name>` (`ctx.plugin.apiPath` is the path up to `/api`). Callers send `Authorization: Bearer <workspace API key>`, which picks the user and workspace. Handlers return `{ status?, body? }`; `body` is sent as JSON.
+- MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one or while it isn't connected, and with `invalid` for an empty topic or a payload that isn't a string (nothing is sent).
+- Routes are served at `<server>/api/plugins/<plugin id>/api/<name>` (`ctx.plugin.apiPath` is the path up to `/api`). Callers send `Authorization: Bearer <workspace API key>`, which picks the user and workspace. Handlers return `{ status?, body? }`; `body` is sent as JSON. While `onStart` runs, a route not registered yet answers 503 (retry after 5 s).
 
 ## Commands between plugins
 
-Main code provides commands; main code and UIs run them. A plugin declares the commands it provides in `manifest.json` and handles them; another plugin lists it in `uses` and runs them, as the same user in the same workspace.
+Main code provides commands; main code, UIs and Home Assistant run them. A plugin declares the commands it provides in `manifest.json` and handles them; another plugin lists it in `uses` and runs them, as the same user in the same workspace.
 
 ```jsonc
 // magic-cube/manifest.json
@@ -371,11 +371,25 @@ const result = await ctx.plugins.get("magic-cube").command("selectPreset", { pre
 - It fails fast: `not-installed`, `disabled`, `incompatible` (outside your range) or `unavailable` (not running; it didn't run). `timeout` and `stopped` mean it may have run.
 - `timeoutMs` defaults to 10 s (at most 30 s). A command run inside another continues its chain and shares what's left of its time; the ninth step of a chain is refused with `loop`.
 - From a UI: `ctx.plugins.get(id).command(…)` as in main code. The UI waits the command's time plus 2 s, then rejects `timeout`.
-- `dbplugin prepare` types what you provide (`.drift-beacon/config.d.ts`): `ctx.commands.handle`, `ctx.events.emit` and `ctx.state` take only declared names, with their declared types (none for a kind you declare nothing of). Plugins you use aren't typed yet.
+- In Home Assistant, each command is an action, `drift_beacon.<manifest id>_<command in snake_case>` (`drift_beacon.magic_cube_select_preset`), on a workspace's device: its fields are your input's properties; if you declare `output`, a call on one workspace can ask for the response `{ output }`. It runs as that workspace's user with `meta.caller` `{ kind: "integration" }` and 10 s, and needs no `uses`. Renaming a command or input field breaks automations as it breaks other plugins.
+- `dbplugin prepare` types what you provide (`.drift-beacon/config.d.ts`): `ctx.commands.handle`, `ctx.events.emit` and `ctx.state` take only declared names, with their declared types (none for a kind you declare nothing of).
+- Plugins you use aren't typed for you: keep a copy of the types you need, written from their manifest. `command<T>()` and `state.get<T>()` take the type, and an event's payload is `unknown` until you narrow it. Update the copy along with your `uses` range.
+
+```ts
+// cartridge-reader: what it uses from magic-cube ^1.1.0, kept by hand
+interface SelectPresetOutput {
+  activePresetId: string | null;
+}
+
+const cube = ctx.plugins.get("magic-cube");
+const { activePresetId } = await cube.command<SelectPresetOutput>("selectPreset", { preset: "Focus" });
+const preset = cube.state.get<string | null>("activePreset");
+cube.onEvent("faceChanged", (face) => showFace(face as number));
+```
 
 ## Events, state and status between plugins
 
-Main code emits and publishes; UIs read state and status (not events). A plugin emits the events and publishes the state it declares in `provides`; the plugins that use it (and the plugin itself, through `ctx.plugins.self`) receive them, and see its status.
+Main code emits and publishes; main code and UIs receive them. A plugin emits the events and publishes the state it declares in `provides`; the plugins that use it (and the plugin itself, through `ctx.plugins.self`) receive them, and see its status.
 
 ```jsonc
 // magic-cube/manifest.json
@@ -397,11 +411,13 @@ cube.onStatusChange(({ state, reason }) => ctx.log.info(state, reason ?? ""));
 ```
 
 - `emit` and `set` throw `invalid` for an undeclared name, a value that doesn't match its schema, or over 64 KiB (256 KiB of state in all). Received values are frozen.
-- Events reach listeners registered by then (from `onStart` on); earlier ones are missed. State is kept in memory while the provider runs, cleared when it stops, never persisted.
+- Events reach listeners registered by then (from `onStart` on; in a UI, right after `connect()`); earlier ones are missed. State is kept in memory while the provider runs, cleared when it stops, never persisted.
+- A plugin can emit 50 events a second on average, in bursts up to 100; Drift Beacon drops the rest, with a warning in your console at most every 10 s (each after the first says how many it dropped). For a value that changes faster, publish the latest as state (not limited) or send fewer, bigger events.
 - In main code, a command handler's events and state changes arrive before its caller's `await` resumes.
 - Listeners continue the chain of what caused them; past 8 steps, events are dropped (with a warning) and state changes call no callbacks.
 - `status.state` is `running`, `starting`, `unavailable`, `disabled`, `incompatible` or `not-installed`, with the resolved `version` and a `reason`.
 - In a UI, status and state arrive within about 250 ms (and `ctx.onDataChange` fires), as the latest at each update (changes close together arrive as one), so a command's effects can show just after it resolves: render from `onChange`, or use its output.
+- In a UI (from 0.2.1), events come with those updates, each after the state its plugin set before it. None are replayed (reconnects, reloads, more than about 100 between two updates), every open copy of the UI gets each one, and a command a UI listener runs starts a new chain: render in UI listeners, and react with commands in main code. On an older Drift Beacon they never arrive.
 
 ## Errors and limits
 
@@ -410,7 +426,7 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 | Code | Meaning |
 |---|---|
 | `unsupported` | The app doesn't support this API version or request |
-| `invalid` | Bad arguments (tracking a point with `start()`, a value that isn't JSON, an undeclared event, …) |
+| `invalid` | Bad arguments (an empty id or storage key, an MQTT payload that isn't a string, tracking a point with `start()`, a value that isn't JSON, an undeclared event, …) |
 | `not-found` | The activity or session doesn't exist, or the model was removed |
 | `unavailable` | Something needed isn't there: no MQTT broker, no answer from the app |
 | `stopped` | The instance has stopped |
@@ -429,7 +445,7 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 
 ## Developing against your server
 
-On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
+On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Repositories → Local development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
 
 ## Releasing a plugin
 
@@ -439,13 +455,13 @@ Plugins are published on GitHub. In a public repository, each immediate child fo
 2. Run `npm run release` (or `npx dbplugin pack`), which writes `releases/<id>.zip`.
 3. Create a GitHub release tagged `<id>-<version>` (for example `hello-1.0.0`) and attach `<id>.zip`.
 
-Users add the repository URL in **Plugins → Store** and install from there. Don't commit `dist/` or `releases/`.
+Users add the repository URL in **Plugins → Repositories** and install from there. Don't commit `dist/` or `releases/`.
 
 ## Versions
 
 - `apiVersion` in the manifest must match the SDK: `dbplugin`, `vite build` and the server all check it.
 - Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.2` to stay on it.
-- Minor releases may add fields and new string values (such as a new `trackingType`): ignore what you don't recognise.
+- Patch releases (`0.2.x`) fix bugs and may add to API 0.2. An addition that needs the app, such as UI events in 0.2.1, does nothing on an older Drift Beacon. Ignore fields and string values you don't recognise (such as a new `trackingType`).
 
 ## License
 

package/dist/internal/actions.js

@@ -1 +1,23 @@
-export {};
+const nonEmpty = (value, what) => typeof value === "string" && value !== "" ? null : `${what} must be a non-empty string`;
+const ARGUMENTS = {
+    startSession: (action) => nonEmpty(action.activityId, "Activity id"),
+    markPoint: (action) => nonEmpty(action.activityId, "Activity id"),
+    endSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    discardSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    storageSet: (action) => nonEmpty(action.key, "Storage key"),
+    storageRemove: (action) => nonEmpty(action.key, "Storage key"),
+    mqttSubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttUnsubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttPublish: (action) => nonEmpty(action.topic, "MQTT topic") ??
+        (typeof action.payload === "string" ? null : "MQTT payload must be a string"),
+};
+export function checkedAction(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const action = value;
+    const name = action.name;
+    if (typeof name !== "string" || !Object.hasOwn(ARGUMENTS, name))
+        return null;
+    const problem = ARGUMENTS[name](action);
+    return problem === null ? { ok: true, action: action } : { ok: false, problem };
+}

package/dist/internal/peers.js

@@ -6,9 +6,14 @@ export const PEER_LIMITS = {
     valueBytes: 64 * 1024,
     stateBytes: 256 * 1024,
     depth: 8,
+    eventsPerSecond: 50,
+    eventBurst: 100,
 };
 export const COMMAND_TIMEOUT = { defaultMs: 10_000, maxMs: 30_000, minimumMs: 100 };
 export const commandBudgetMs = (timeoutMs) => Math.min(timeoutMs ?? COMMAND_TIMEOUT.defaultMs, COMMAND_TIMEOUT.maxMs);
+export const eventNameProblem = (name) => typeof name === "string" && PEER_NAME.test(name)
+    ? null
+    : `Event names are camelCase letters and digits (got "${String(name)}")`;
 export function commandArgumentsProblem(command, input, options) {
     if (typeof command !== "string" || !command)
         return "Command name must be a non-empty string";

package/dist/main.d.ts

@@ -19,9 +19,15 @@ export interface MqttMessage {
 export interface MqttApi {
     /** Subscribe to a topic filter. `+` matches one level and `#` the remaining levels. */
     subscribe(topic: string, callback: (message: MqttMessage) => void): Unsubscribe;
-    /** Rejects when no broker is configured or the broker refuses the message. */
+    /**
+     * Rejects with `invalid` when the topic is empty or the payload isn't a string (nothing is sent), and with
+     * `unavailable` when the workspace has no broker, the broker isn't connected, or it refuses the message.
+     */
     publish(topic: string, payload: string): Promise<void>;
-    /** `unavailable` when no broker is configured for the workspace. */
+    /**
+     * `unavailable` when the workspace has no broker: none is configured, or the server couldn't connect to it when
+     * it was saved or when the server started.
+     */
     readonly status: MqttStatus;
     onStatusChange(callback: (status: MqttStatus) => void): Unsubscribe;
 }

package/dist/types.d.ts

@@ -178,13 +178,13 @@ export interface SessionsApi {
     /** Data change events. They can arrive in bursts after a sync; don't use them to trigger actions. */
     onChange(callback: (change: Change<Session>) => void): Unsubscribe;
 }
-/** The plugin's own key-value storage, per user and workspace. Values must be JSON-compatible. */
+/** The plugin's own key-value storage, per user and workspace: non-empty string keys, JSON-compatible values. */
 export interface StorageApi {
     get<T = unknown>(key: string): T | undefined;
     keys(): readonly string[];
     /**
      * Applies locally at once and resolves when Drift Beacon has accepted the write. `undefined` removes the key;
-     * a value that isn't JSON-compatible rejects with `invalid`.
+     * an empty key or a value that isn't JSON-compatible rejects with `invalid`.
      */
     set(key: string, value: unknown): Promise<void>;
     /** Applies locally at once and resolves when Drift Beacon has accepted the removal. */
@@ -237,6 +237,13 @@ export interface PluginPeer {
     command<T = unknown>(name: string, input?: Readonly<Record<string, unknown>>, options?: CommandOptions): Promise<T>;
     /** The state it publishes (manifest.json `provides.state`). */
     readonly state: PeerStateApi;
+    /**
+     * Called for each of its events with this name (manifest.json `provides.events`), with the payload (frozen). In a
+     * UI (from 0.2.1): from `connect()` on, with the state its plugin set before it, not replayed, errors logged, and
+     * every open copy of the UI gets each one; against an older Drift Beacon it's never called. In main code, see
+     * `MainPluginPeer.onEvent`. Throws `invalid` for a name that isn't camelCase.
+     */
+    onEvent(name: string, callback: (payload: unknown) => void): Unsubscribe;
 }
 /** The plugins this one uses. */
 export interface PluginsApi {

package/dist/ui.d.ts

@@ -15,13 +15,14 @@ export interface UiContext {
     readonly sessions: SessionsApi;
     /**
      * Called after each update from the app (workspace data, config, storage, or other plugins' status and state) and
-     * after local storage writes.
+     * after local storage writes; not for other plugins' events.
      */
     onDataChange(callback: () => void): Unsubscribe;
     readonly storage: StorageApi;
     /**
-     * Its own plugin and the plugins it uses: their status and published state (within about 250 ms of a change), and
-     * their commands. A command's effects on their state, storage or data can arrive just after it resolves.
+     * Its own plugin and the plugins it uses: their status and published state (within about 250 ms of a change),
+     * their events (with them), and their commands. A command's effects on their state, storage or data, and its events,
+     * can arrive just after it resolves.
      */
     readonly plugins: PluginsApi;
 }

package/dist/ui.js

@@ -1,9 +1,10 @@
 import { PluginError } from "./errors.js";
+import { checkedAction } from "./internal/actions.js";
 import { Collection } from "./internal/collection.js";
 import { deepFreeze } from "./internal/freeze.js";
 import { jsonEqual } from "./internal/json-equal.js";
 import { WorkspaceModels } from "./internal/models.js";
-import { commandArgumentsProblem, commandBudgetMs, samePluginStatus } from "./internal/peers.js";
+import { commandArgumentsProblem, commandBudgetMs, eventNameProblem, samePluginStatus } from "./internal/peers.js";
 import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
 import { API_VERSION } from "./version.js";
 export { PluginError } from "./errors.js";
@@ -127,10 +128,6 @@ class UiClient {
         this.applyData(welcome.data);
         const apis = this.models.apis();
         const self = this;
-        const subscribe = (listeners, callback) => {
-            listeners.add(callback);
-            return () => listeners.delete(callback);
-        };
         this.context = {
             get plugin() {
                 return self.plugin;
@@ -178,10 +175,6 @@ class UiClient {
         if (existing)
             return existing;
         const view = this.viewOf(id);
-        const subscribe = (listeners, callback) => {
-            listeners.add(callback);
-            return () => listeners.delete(callback);
-        };
         const peer = Object.freeze({
             id,
             get status() {
@@ -194,6 +187,20 @@ class UiClient {
                 keys: () => [...view.state.keys()],
                 onChange: (callback) => subscribe(view.stateListeners, callback),
             }),
+            onEvent: (name, callback) => {
+                const invalidName = eventNameProblem(name);
+                if (invalidName)
+                    throw new PluginError("invalid", invalidName);
+                const problem = this.unreachable(id);
+                if (problem)
+                    throw problem;
+                let listeners = view.eventListeners.get(name);
+                if (!listeners) {
+                    listeners = new Set();
+                    view.eventListeners.set(name, listeners);
+                }
+                return subscribe(listeners, callback);
+            },
         });
         this.peerObjects.set(id, peer);
         return peer;
@@ -206,7 +213,13 @@ class UiClient {
     viewOf(id) {
         let view = this.peerViews.get(id);
         if (!view) {
-            view = { status: NO_PEERS, state: new Map(), statusListeners: new Set(), stateListeners: new Set() };
+            view = {
+                status: NO_PEERS,
+                state: new Map(),
+                statusListeners: new Set(),
+                stateListeners: new Set(),
+                eventListeners: new Map(),
+            };
             this.peerViews.set(id, view);
         }
         return view;
@@ -291,6 +304,10 @@ class UiClient {
                 pending.resolve(message.result);
             return;
         }
+        if (message.type === "event") {
+            this.applyEvent(message);
+            return;
+        }
         if (message.type !== "state")
             return;
         if (message.config)
@@ -306,6 +323,15 @@ class UiClient {
             this.applyPeers(message.peers);
         notify(this.dataListeners, (listener) => listener());
     }
+    applyEvent({ plugin, event, payload }) {
+        if (!this.listed.has(plugin))
+            return;
+        const listeners = this.peerViews.get(plugin)?.eventListeners.get(event);
+        if (!listeners?.size)
+            return;
+        const frozen = deepFreeze(payload);
+        notify(listeners, (listener) => listener(frozen));
+    }
     applyData(data) {
         const changes = this.models.update({
             activities: this.rows.activities.replace(data.activities),
@@ -341,6 +367,9 @@ class UiClient {
         return changed;
     }
     async write(key, value) {
+        const checked = checkedAction(value === undefined ? { name: "storageRemove", key } : { name: "storageSet", key, value });
+        if (checked?.ok === false)
+            throw new PluginError("invalid", checked.problem);
         const writeId = ++this.nextWrite;
         this.pendingWrites.set(key, (this.pendingWrites.get(key) ?? 0) + 1);
         this.writesSincePush.set(key, writeId);
@@ -385,13 +414,24 @@ class UiClient {
         });
     }
 }
+function subscribe(listeners, callback) {
+    if (typeof callback !== "function")
+        throw new PluginError("invalid", "Callback must be a function");
+    listeners.add(callback);
+    return () => listeners.delete(callback);
+}
+const logListenerError = (error) => console.error("[drift-beacon] Error in plugin listener:", error);
 function notify(listeners, call) {
-    for (const listener of listeners) {
+    for (const listener of [...listeners]) {
+        if (!listeners.has(listener))
+            continue;
         try {
-            call(listener);
+            const result = call(listener);
+            if (result && typeof result.then === "function")
+                result.then(undefined, logListenerError);
         }
         catch (error) {
-            console.error("[drift-beacon] Error in plugin listener:", error);
+            logListenerError(error);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drift-beacon/plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The Drift Beacon plugin SDK: APIs for plugin main code and UIs, the driftBeacon() Vite plugin and the dbplugin CLI",
   "license": "MIT",
   "author": {