@drift-beacon/plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drift Beacon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,368 @@
+# @drift-beacon/plugin
+
+The plugin SDK for [Drift Beacon](https://driftbeacon.app). A plugin has **main code**, which runs on your Drift Beacon server, and a **UI**, which opens in the web app. This package gives you their APIs, a Vite plugin that builds both, and the `dbplugin` command that packages a release.
+
+Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers that run API 0.1.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Project layout and commands](#project-layout-and-commands)
+- [Manifest](#manifest)
+- [Main code](#main-code)
+- [UI](#ui)
+- [Workspace data](#workspace-data)
+- [Actions and events](#actions-and-events)
+- [Storage](#storage)
+- [Configuration](#configuration)
+- [MQTT and HTTP routes](#mqtt-and-http-routes)
+- [Errors and limits](#errors-and-limits)
+- [Developing against your server](#developing-against-your-server)
+- [Releasing a plugin](#releasing-a-plugin)
+- [Versions](#versions)
+
+## Quick start
+
+```sh
+mkdir my-plugin && cd my-plugin
+npm init -y
+npm pkg set type=module
+npm install --save-dev @drift-beacon/plugin@0.1 vite typescript @types/node
+```
+
+`package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "release": "dbplugin pack",
+    "postinstall": "dbplugin prepare"
+  }
+}
+```
+
+`vite.config.ts`:
+
+```ts
+import { driftBeacon } from "@drift-beacon/plugin/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({ plugins: [driftBeacon()] }); // with React: [react(), driftBeacon()]
+```
+
+`tsconfig.json`:
+
+```json
+{ "files": [], "references": [{ "path": "./.drift-beacon/tsconfig.main.json" }, { "path": "./.drift-beacon/tsconfig.ui.json" }] }
+```
+
+`manifest.json`:
+
+```json
+{
+  "id": "hello",
+  "name": "Hello",
+  "version": "1.0.0",
+  "apiVersion": "0.1",
+  "description": "Says hello when a session starts",
+  "author": { "name": "You" },
+  "category": "plugin",
+  "icon": "",
+  "configuration": []
+}
+```
+
+`main/src/index.ts`:
+
+```ts
+import { definePlugin } from "@drift-beacon/plugin";
+
+export default definePlugin({
+  onStart(ctx) {
+    ctx.sessions.onStarted((session) => {
+      if (session.isMine) ctx.log.info(`Started ${session.activity?.name}`);
+    });
+  },
+});
+```
+
+`ui/index.html` and `ui/src/main.ts`:
+
+```html
+<!doctype html>
+<html>
+  <body>
+    <ul id="activities"></ul>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```ts
+import { connect } from "@drift-beacon/plugin/ui";
+
+const ctx = await connect();
+const list = document.getElementById("activities")!;
+const render = () => {
+  list.replaceChildren(
+    ...ctx.activities.list().map((activity) => {
+      const item = document.createElement("li");
+      item.textContent = `${activity.name}${activity.isLive ? " (live)" : ""}`;
+      item.onclick = () => void activity.track();
+      return item;
+    }),
+  );
+};
+ctx.onDataChange(render);
+render();
+```
+
+Then `npm run build` writes `dist/`, and `npm run release` writes `releases/hello.zip`.
+
+## Project layout and commands
+
+```
+my-plugin/
+├── package.json        # "type": "module"
+├── vite.config.ts      # plugins: [driftBeacon()]
+├── tsconfig.json       # references .drift-beacon/tsconfig.{main,ui}.json
+├── manifest.json       # identity, API version, icon, settings
+├── main/src/index.ts   # main code: runs on the server
+├── ui/                 # the UI: an ordinary Vite app, shown in an iframe in the web app
+│   ├── index.html
+│   ├── src/…
+│   └── public/         # the manifest icon, plus any static files
+├── .drift-beacon/      # generated by dbplugin prepare; ignores itself
+└── dist/               # the build: exactly the release package
+```
+
+| Command | What it does |
+|---|---|
+| `vite` (`npm run dev`) | Serves the UI with hot reload and rebuilds main on every save. A Drift Beacon server in development mode applies each build and prints the plugin's status and logs in the same terminal. |
+| `vite build` | Production build into `dist/`: `manifest.json`, `package.json`, `main/index.js` and `ui/`. |
+| `dbplugin pack` | Typechecks main and the UI, builds fresh into a temporary folder and writes `releases/<id>.zip`. Prints `{ id, version, tag, asset, archivePath }` as JSON on stdout. `dist/` is untouched. `--out <dir>` picks another folder. |
+| `dbplugin prepare` | Writes `.drift-beacon/`: typed settings and the two tsconfigs. Runs on install and on every build. |
+
+Run `dbplugin` through your package scripts or `npx dbplugin …` inside the plugin folder: it's the copy from your installed SDK.
+
+- **Main** is bundled into one ESM file with every dependency except `@drift-beacon/plugin`, which the server supplies at run time. Native modules aren't supported.
+- **The UI** bundles its own dependencies, including `@drift-beacon/plugin/ui`. Use any framework and library versions you like.
+- `driftBeacon()` owns Vite's `root` (`ui/`), `base` and `build.outDir`: don't set them. It works with Vite 7 and 8.
+
+| Import | Used by | Contents |
+|---|---|---|
+| `@drift-beacon/plugin` | Main code | `definePlugin`, `PluginError`, `API_VERSION` and every type |
+| `@drift-beacon/plugin/ui` | UI | `connect()`, `PluginError`, `API_VERSION` and the shared types |
+| `@drift-beacon/plugin/vite` | `vite.config.ts` | `driftBeacon()` |
+
+## Manifest
+
+| Field | Rules |
+|---|---|
+| `id` | Lowercase letters, digits and hyphens, starting with a letter or digit, at most 64 characters |
+| `version` | Semantic version (`1.2.3`); build metadata is allowed, prereleases are not |
+| `apiVersion` | `major.minor` of the SDK you build with (`"0.1"`) |
+| `name`, `description` | Required text |
+| `author` | `{ name, email? }` |
+| `category` | `plugin`, `utility` or `ui` |
+| `icon` | A file name in `ui/public/`, or `""` |
+| `configuration` | Settings (see [Configuration](#configuration)) |
+
+Settings items have `name` (unique), `title`, `type` and optional `description` and `required`:
+
+| `type` | Extra fields | Value in `ctx.config` |
+|---|---|---|
+| `string` | `default?`, `placeholder?` | `string` |
+| `number` | `default?`, `minimum?`, `maximum?` | `number` |
+| `boolean` | `default?` | `boolean` |
+| `dropdown` | `default?`, `data: [{ title, value }]` | the selected `value` |
+
+## Main code
+
+`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.
+- **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`.
+- **Faults.** An uncaught error or unhandled rejection stops only that instance, which is retried after 5, 30 and 120 seconds.
+
+| `ctx` member | Main | UI | |
+|---|:-:|:-:|---|
+| `plugin`, `user`, `workspace` | ✓ | ✓ | Installed identity (`id`, `version`, `apiPath`), the user and the workspace |
+| `config` | ✓ | ✓ | Settings, validated, defaults applied |
+| `activities`, `categories`, `sessions` | ✓ | ✓ | Workspace data and actions |
+| `onDataChange` | ✓ | ✓ | The data changed |
+| `sessions.onStarted`, `onEnded`, `onMarked` | ✓ | | Live session events |
+| `storage` | ✓ | ✓ | Key-value storage |
+| `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 or storage).
+
+With React, re-render on every update:
+
+```tsx
+import { connect, type UiContext } from "@drift-beacon/plugin/ui";
+import { useSyncExternalStore } from "react";
+
+let context: UiContext | null = null;
+let revision = 0;
+const subscribe = (listener: () => void) => (context ? context.onDataChange(listener) : () => {});
+
+export function useDriftBeacon(): UiContext {
+  useSyncExternalStore(subscribe, () => revision);
+  if (!context) throw new Error("Not connected");
+  return context;
+}
+
+export async function start() {
+  context = await connect();
+  context.onDataChange(() => {
+    revision += 1;
+  });
+}
+```
+
+Models keep their identity when their data changes: key `React.memo` and `useMemo` on `model.data`.
+
+## Workspace data
+
+`ctx.activities`, `ctx.categories` and `ctx.sessions` return **models**: the row's fields plus links, derived values and actions.
+
+```ts
+const activity = ctx.activities.get(id);
+activity?.category?.name;   // links
+activity?.isLive;           // the current user has a live session of it
+await activity?.track();    // start a span / mark a point
+activity?.data;             // the plain row, a new frozen object whenever it changes
+
+ctx.activities.list();                                  // sorted like the app, archived hidden
+ctx.activities.list({ includeArchived: true });
+ctx.activities.list({ categoryId: null });              // uncategorized
+ctx.categories.list().map((category) => category.activities());
+ctx.sessions.list({ activityId, status: "completed" }); // newest first
+ctx.sessions.live({ mine: true });
+```
+
+- Models read the latest snapshot synchronously; nothing fetches. One model per row: identity stays, `model.data` changes.
+- Lists return the same frozen array until the data changes.
+- A removed row's model keeps its last values with `exists: false`, and its actions reject with `not-found`.
+- `startedAt` and `endedAt` are `Date`s: copy one before changing it.
+- `iconPath` on activities and categories is SVG path data (viewBox `0 0 24 24`), or `null`:
+
+```tsx
+{activity.iconPath && <svg viewBox="0 0 24 24" fill="currentColor"><path d={activity.iconPath} /></svg>}
+```
+
+| Activity | |
+|---|---|
+| `id`, `name`, `description`, `trackingType`, `icon`, `iconPath`, `color`, `categoryId`, `archived`, `sortOrder`, `unit` | Fields (`color` is resolved from the category when needed) |
+| `isSpan`, `isPoint`, `isLive`, `category` | Derived values and links |
+| `sessions(filter?)`, `live({ mine? })` | Its sessions |
+| `start()`, `mark()`, `track()`, `end()` | Actions (`end()` ends the current user's live session of it) |
+
+| Session | |
+|---|---|
+| `id`, `activityId`, `type`, `status`, `memberIds`, `startedAt`, `endedAt` | Fields |
+| `isSpan`, `isPoint`, `isLive`, `isMine`, `activity`, `duration(at?)` | Derived values and links |
+| `end()`, `discard()` | Actions on a live span |
+
+Categories have `id`, `name`, `description`, `color`, `icon`, `iconPath`, `sortOrder` and `activities(filter?)`.
+
+## Actions and events
+
+```ts
+await ctx.sessions.start(activityId);   // or activity.start()
+await ctx.sessions.mark(activityId);    // or activity.mark()
+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.
+
+| | Live session events | Data change events |
+|---|---|---|
+| API | `ctx.sessions.onStarted`, `onEnded(session, reason)`, `onMarked` | `activities/categories/sessions.onChange`, `ctx.onDataChange` |
+| Means | A user **just did** something | The data **is different** now, possibly from a sync burst |
+| Use for | Reacting: start, end, publish, notify | Refreshing what you show |
+| Where | Main code | Main code and UI |
+
+Never trigger actions from data changes. Live events fire for everyone's sessions in the workspace: check `session.isMine`.
+
+## Storage
+
+Per plugin, user and workspace, shared by main code and the UI. Values must be JSON.
+
+```ts
+const faces = ctx.storage.get<Record<string, string>>("faces") ?? {};
+await ctx.storage.set("faces", { ...faces, [side]: activityId });
+await ctx.storage.remove("draft");
+ctx.storage.onChange((key, value) => { /* changed by main code, a UI or another device */ });
+```
+
+## Configuration
+
+`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.
+
+## MQTT and HTTP routes
+
+Main code only.
+
+```ts
+ctx.mqtt.subscribe("zigbee2mqtt/cube/#", ({ topic, payload }) => { /* payload is a string */ });
+await ctx.mqtt.publish("zigbee2mqtt/lamp/set", JSON.stringify({ state: "ON" }));
+
+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.
+
+## Errors and limits
+
+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, …) |
+| `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 |
+| `failed` | Anything else, such as tracking an archived activity |
+
+| | Limit |
+|---|---|
+| `onStart` / `onStop` | 15 s / 5 s |
+| Blocking the event loop | The server restarts the plugin host after 10 s |
+| Actions | 10 s, then `unavailable` |
+| Route handlers | 30 s, then 504 |
+| Release package | 32 MiB zipped, 128 MiB unpacked, 2,000 files |
+
+## 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.
+
+## Releasing a plugin
+
+Plugins are published on GitHub. In a public repository, each immediate child folder with a `manifest.json` is a plugin. For each release:
+
+1. Bump `version` in `manifest.json` and commit.
+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/`.
+
+## 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.1` to stay on it.
+- Minor releases may add fields and new string values (such as a new `trackingType`): ignore what you don't recognise.
+
+## License
+
+MIT

package/bin/dbplugin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Committed, so pnpm can link the `dbplugin` bin before the SDK is built. The CLI itself is dist/cli.js.
+const cli = new URL("../dist/cli.js", import.meta.url);
+try {
+  await import(cli.href);
+} catch (error) {
+  // Only a missing dist/cli.js means an unbuilt SDK; a missing import inside it is a real error.
+  if (error?.code !== "ERR_MODULE_NOT_FOUND" || error.url !== cli.href) throw error;
+  console.error("Build the SDK first: pnpm --filter @drift-beacon/plugin build (in the Drift Beacon core checkout)");
+  process.exitCode = 1;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,38 @@
+/**
+ * `dbplugin` (Drift Beacon plugins), run through `bin/dbplugin.js`:
+ *
+ *   dbplugin prepare [root]              Generate .drift-beacon/ (config types and tsconfigs). Lenient: a manifest
+ *                                   problem only warns, because this runs as the plugin's postinstall.
+ *   dbplugin pack [root] [--out <dir>]   Typecheck, build fresh and write <out>/<id>.zip (default releases/).
+ *                                   Prints only the result JSON on stdout.
+ */
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { pack } from "./pack.js";
+import { prepare } from "./prepare.js";
+const USAGE = "Usage: dbplugin prepare [root]\n       dbplugin pack [root] [--out <dir>]";
+try {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: { help: { type: "boolean", short: "h" }, out: { type: "string" } },
+    });
+    const [command, root = ".", ...extra] = positionals;
+    if (values.help) {
+        console.log(USAGE);
+    }
+    else if (command === "prepare" && extra.length === 0 && values.out === undefined) {
+        prepare(path.resolve(root), { strict: false });
+    }
+    else if (command === "pack" && extra.length === 0) {
+        const result = await pack(path.resolve(root), values.out === undefined ? {} : { out: path.resolve(values.out) });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.error(USAGE);
+        process.exitCode = 1;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/dev.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The `pnpm dev` handshake between `driftBeacon()` and the Drift Beacon server. The dev tool writes a
+ * marker into the package's `dist/`; the server polls for it, connects to Vite's HMR socket and trusts
+ * the socket only after a `welcome` whose `session` equals the marker's. Messages travel as Vite custom
+ * events (`{ type: "custom", event, data }`). All wording is rendered on the server; the tool only prints.
+ */
+/** File name of the marker in `dist/`. Written as tmp, then renamed, synchronously. Never packed. */
+export declare const DEV_MARKER = ".drift-beacon-dev.json";
+export interface DevMarker {
+    readonly v: 1;
+    /** `manifest.id`; the server routes logs and the dev UI URL by it. */
+    readonly pluginId: string;
+    /** Hash of the built package; null until `dist/main/index.js` exists. A new id means a new build. */
+    readonly buildId: string | null;
+    /** One per `pnpm dev` process and package root; null after `vite build`. */
+    readonly session: string | null;
+    /** The dev server's UI URL, for example `http://localhost:5174/`. */
+    readonly uiUrl: string | null;
+    /** The dev server's HMR socket, for example `ws://localhost:5174/`. */
+    readonly wsUrl: string | null;
+}
+/** Server → tool, event `drift-beacon:hello`. */
+export interface DevHello {
+    readonly v: 1;
+    readonly session: string;
+}
+/** Tool → server, event `drift-beacon:welcome`, sent only to the socket that said hello. */
+export interface DevWelcome {
+    readonly v: 1;
+    readonly session: string;
+    readonly pluginId: string;
+}
+/** Server → tool, event `drift-beacon:print`: one line (or block) for the plugin's terminal. */
+export interface DevPrint {
+    readonly level: "info" | "success" | "warn" | "error";
+    readonly text: string;
+}
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.js

@@ -0,0 +1,8 @@
+/**
+ * The `pnpm dev` handshake between `driftBeacon()` and the Drift Beacon server. The dev tool writes a
+ * marker into the package's `dist/`; the server polls for it, connects to Vite's HMR socket and trusts
+ * the socket only after a `welcome` whose `session` equals the marker's. Messages travel as Vite custom
+ * events (`{ type: "custom", event, data }`). All wording is rendered on the server; the tool only prints.
+ */
+/** File name of the marker in `dist/`. Written as tmp, then renamed, synchronously. Never packed. */
+export const DEV_MARKER = ".drift-beacon-dev.json";

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import type { PluginErrorCode } from "./types.ts";
+/** Rejection from a platform operation. Check `code` rather than `instanceof`, which differs between SDK copies. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    constructor(code: PluginErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** Rejection from a platform operation. Check `code` rather than `instanceof`, which differs between SDK copies. */
+export class PluginError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PluginError";
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Drift Beacon plugin SDK: the API for main code (runs on the server). Plugin UIs import from `@drift-beacon/plugin/ui`.
+ *
+ * At run time the plugin host supplies this module, so `driftBeacon()` keeps it external when building main.
+ */
+export { PluginError } from "./errors.ts";
+export type * from "./main.ts";
+export { definePlugin } from "./main.ts";
+export type * from "./types.ts";
+export { API_VERSION } from "./version.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Drift Beacon plugin SDK: the API for main code (runs on the server). Plugin UIs import from `@drift-beacon/plugin/ui`.
+ *
+ * At run time the plugin host supplies this module, so `driftBeacon()` keeps it external when building main.
+ */
+export { PluginError } from "./errors.js";
+export { definePlugin } from "./main.js";
+export { API_VERSION } from "./version.js";

package/dist/internal/actions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Requests an instance's main code sends to the server through its plugin host. The server runs them
+ * as the instance's user in the instance's workspace.
+ */
+export type PluginAction = {
+    readonly name: "startSession";
+    readonly activityId: string;
+} | {
+    readonly name: "endSession";
+    readonly sessionId: string;
+} | {
+    readonly name: "markPoint";
+    readonly activityId: string;
+} | {
+    readonly name: "discardSession";
+    readonly sessionId: string;
+} | {
+    readonly name: "storageSet";
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly name: "storageRemove";
+    readonly key: string;
+} | {
+    readonly name: "mqttSubscribe";
+    readonly topic: string;
+} | {
+    readonly name: "mqttUnsubscribe";
+    readonly topic: string;
+} | {
+    readonly name: "mqttPublish";
+    readonly topic: string;
+    readonly payload: string;
+};
+//# sourceMappingURL=actions.d.ts.map

package/dist/internal/actions.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/collection.d.ts

@@ -0,0 +1,15 @@
+import type { RowChange } from "./rows.ts";
+/**
+ * A collection of plain rows keyed by id, frozen as they arrive. `replace` applies a full set of rows, keeps the
+ * object of every unchanged row (so identity only changes when data does) and reports the changes.
+ */
+export declare class Collection<T extends {
+    readonly id: string;
+}> {
+    private rows;
+    private cachedList;
+    list(): readonly T[];
+    get(id: string): T | undefined;
+    replace(incoming: readonly T[]): RowChange<T>[];
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/internal/collection.js

@@ -0,0 +1,52 @@
+import { jsonEqual } from "./json-equal.js";
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * A collection of plain rows keyed by id, frozen as they arrive. `replace` applies a full set of rows, keeps the
+ * object of every unchanged row (so identity only changes when data does) and reports the changes.
+ */
+export class Collection {
+    rows = new Map();
+    cachedList = null;
+    list() {
+        this.cachedList ??= Object.freeze([...this.rows.values()]);
+        return this.cachedList;
+    }
+    get(id) {
+        return this.rows.get(id);
+    }
+    replace(incoming) {
+        const changes = [];
+        const next = new Map();
+        for (const row of incoming) {
+            const previous = this.rows.get(row.id);
+            if (!previous) {
+                const item = deepFreeze(row);
+                next.set(row.id, item);
+                changes.push({ type: "added", item });
+            }
+            else if (jsonEqual(previous, row)) {
+                next.set(row.id, previous);
+            }
+            else {
+                const item = deepFreeze(row);
+                next.set(row.id, item);
+                changes.push({ type: "updated", item, previous });
+            }
+        }
+        for (const [id, item] of this.rows) {
+            if (!next.has(id))
+                changes.push({ type: "removed", item });
+        }
+        this.rows = next;
+        if (changes.length > 0 || next.size !== this.cachedList?.length)
+            this.cachedList = null;
+        return changes;
+    }
+}

package/dist/internal/compatibility.d.ts

@@ -0,0 +1,26 @@
+/**
+ * API versions this build of Drift Beacon runs: the newest minor of each supported major.
+ * Before 1.0 only the current version is listed, because every 0.x minor may break plugins.
+ * From 1.0, the previous major stays listed for at least six months after its successor ships.
+ */
+export declare const SUPPORTED_API_VERSIONS: readonly string[];
+export interface ApiVersion {
+    readonly major: number;
+    readonly minor: number;
+}
+/** Parse a `major.minor` API version; null when malformed. */
+export declare function parseApiVersion(value: unknown): ApiVersion | null;
+export type ApiCompatibility = {
+    readonly compatible: true;
+} | {
+    readonly compatible: false;
+    readonly reason: "invalid" | "needs-newer-app" | "needs-plugin-update";
+    readonly message: string;
+};
+/**
+ * Whether a plugin built for `pluginVersion` runs on a build supporting `supported`.
+ * Before 1.0 the minor must match exactly; from 1.0 the major must match and the plugin's
+ * minor must not be newer than the host's.
+ */
+export declare function checkApiCompatibility(pluginVersion: unknown, supported?: readonly string[]): ApiCompatibility;
+//# sourceMappingURL=compatibility.d.ts.map