@drift-beacon/plugin 0.1.1 → 0.2.1

package/dist/internal/semver.js

@@ -0,0 +1,47 @@
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const isStableVersion = (value) => typeof value === "string" &&
+    STABLE_VERSION.test(value) &&
+    (value.split("+")[0] ?? "").split(".").every((part) => Number.isSafeInteger(Number(part)));
+const parts = (version) => {
+    const [major = 0, minor = 0, patch = 0] = (version.split("+")[0] ?? "").split(".").map(Number);
+    return [major, minor, patch];
+};
+export function compareVersions(left, right) {
+    if (!isStableVersion(left) || !isStableVersion(right))
+        throw new Error("Expected a stable semantic version");
+    const a = parts(left);
+    const b = parts(right);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return (a[i] ?? 0) > (b[i] ?? 0) ? 1 : -1;
+    return 0;
+}
+const RANGE = /^(\^|~|>=)?(.+)$/;
+export function validateRange(range) {
+    if (range === "*")
+        return;
+    const match = typeof range === "string" ? RANGE.exec(range) : null;
+    if (!match?.[2] || !isStableVersion(match[2]) || match[2].includes("+"))
+        throw new Error(`Unsupported version range "${String(range)}": use 1.2.3, ^1.2.3, ~1.2.3, >=1.2.3 or *`);
+}
+export function satisfiesRange(version, range) {
+    validateRange(range);
+    if (range === "*")
+        return true;
+    const [, operator = "", base = ""] = RANGE.exec(range) ?? [];
+    if (compareVersions(version, base) < 0)
+        return false;
+    if (operator === "")
+        return compareVersions(version, base) === 0;
+    if (operator === ">=")
+        return true;
+    const [major, minor, patch] = parts(base);
+    const [vMajor, vMinor, vPatch] = parts(version);
+    if (operator === "~")
+        return vMajor === major && vMinor === minor;
+    if (major > 0)
+        return vMajor === major;
+    if (minor > 0)
+        return vMajor === 0 && vMinor === minor;
+    return vMajor === 0 && vMinor === 0 && vPatch === patch;
+}

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PeerStateApi, PluginConfig, PluginInfo, PluginPeer, PluginsApi, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export type SessionEndReason = "completed" | "discarded";
 export interface MainSessionsApi extends SessionsApi {
     /**
@@ -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;
 }
@@ -51,6 +57,94 @@ export interface LogApi {
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
 }
+/** Who ran a command: another plugin's main code (by manifest id), a plugin UI, or an integration such as Home Assistant. */
+export type CommandCaller = {
+    readonly kind: "plugin";
+    readonly plugin: string;
+} | {
+    readonly kind: "ui";
+    readonly plugin: string;
+} | {
+    readonly kind: "integration";
+};
+/** The commands this plugin provides. `dbplugin prepare` fills this in from manifest.json `provides` (.drift-beacon/config.d.ts). */
+export interface PluginCommands {
+}
+/** The events this plugin emits. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginEvents {
+}
+/** The state this plugin publishes. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginState {
+}
+/** A declared map, or any name when nothing is declared (a plugin without generated types). */
+type Declared<T, Fallback> = keyof T extends never ? {
+    readonly [name: string]: Fallback;
+} : T;
+type Commands = Declared<PluginCommands, {
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly output: unknown;
+}>;
+type Events = Declared<PluginEvents, unknown>;
+type States = Declared<PluginState, unknown>;
+type CommandName = keyof Commands & string;
+type EventName = keyof Events & string;
+type StateKey = keyof States & string;
+/** The chain a call belongs to: commands, events and state changes a handler or listener causes continue it. */
+export interface ChainInfo {
+    readonly chainId: string;
+    /**
+     * 1 for anything started outside a handler or listener; one more per step. Past 8, commands fail (`loop`),
+     * events are dropped and state changes run no callbacks. 0 for changes Drift Beacon makes itself (a plugin
+     * stopping or being replaced).
+     */
+    readonly depth: number;
+}
+export interface CommandMeta extends ChainInfo {
+    readonly caller: CommandCaller;
+    /** When the caller stops waiting (epoch milliseconds). */
+    readonly deadline: number;
+    /** Aborts at the deadline: pass it to `fetch` and the like. */
+    readonly signal: AbortSignal;
+}
+/** Handles a command: `input` has the declared fields (`{}` when it declares none); the result is the command's output. */
+export type CommandHandler<K extends CommandName = CommandName> = (input: Commands[K]["input"], meta: CommandMeta) => undefined extends Commands[K]["output"] ? unknown : Commands[K]["output"] | Promise<Commands[K]["output"]>;
+export interface CommandsApi {
+    /** Handle a command declared in manifest.json `provides.commands`. One handler per command; throws `invalid` otherwise. */
+    handle<K extends CommandName>(name: K, handler: CommandHandler<K>): Unsubscribe;
+}
+export interface EventsApi {
+    /**
+     * Send a declared event (manifest.json `provides.events`) to the plugins that use this one, and to this plugin
+     * itself. Throws `invalid` for an undeclared event or a payload that doesn't match its schema (or is over 64 KiB).
+     */
+    emit<K extends EventName>(name: K, ...payload: undefined extends Events[K] ? [payload?: Events[K]] : [payload: Events[K]]): void;
+}
+/** The state this plugin publishes to the plugins that use it (manifest.json `provides.state`). Kept in memory while it runs. */
+export interface StateApi {
+    get<K extends StateKey>(key: K): States[K] | undefined;
+    keys(): readonly StateKey[];
+    /**
+     * Publish a value (`undefined` removes it). Throws `invalid` for an undeclared key, a value that doesn't match
+     * its schema, over 64 KiB, or over 256 KiB of state in all.
+     */
+    set<K extends StateKey>(key: K, value: States[K] | undefined): void;
+}
+/** Another plugin's state, with the chain of the change that caused each callback. */
+export interface MainPeerStateApi extends PeerStateApi {
+    onChange(callback: (key: string, value: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginPeer extends PluginPeer {
+    readonly state: MainPeerStateApi;
+    /**
+     * Called for each of its events with this name. Commands, events and state changes the callback causes continue
+     * its chain. A throw, or a rejection of the promise it returns, stops the instance.
+     */
+    onEvent(name: string, callback: (payload: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginsApi extends PluginsApi {
+    get(id: string): MainPluginPeer;
+    readonly self: MainPluginPeer;
+}
 /** Everything a plugin's main code can use. One `ctx` per instance: a plugin for one user in one workspace. */
 export interface MainContext {
     readonly plugin: PluginInfo;
@@ -66,6 +160,14 @@ export interface MainContext {
     readonly storage: StorageApi;
     readonly mqtt: MqttApi;
     readonly routes: RoutesApi;
+    /** The commands this plugin provides to other plugins, its UI and integrations. */
+    readonly commands: CommandsApi;
+    /** The events this plugin emits to the plugins that use it. */
+    readonly events: EventsApi;
+    /** The state this plugin publishes to the plugins that use it. */
+    readonly state: StateApi;
+    /** The plugins this one uses, and itself. */
+    readonly plugins: MainPluginsApi;
     readonly log: LogApi;
     /**
      * Run when the instance stops: disabled, reconfigured, updated or shut down. `ctx` still works
@@ -89,4 +191,5 @@ export interface PluginDefinition {
  * ```
  */
 export declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+export {};
 //# sourceMappingURL=main.d.ts.map

package/dist/pack.js

@@ -90,15 +90,14 @@ export async function pack(root, options = {}) {
         const typescript = require.resolve("typescript/package.json");
         const { bin } = JSON.parse(await readFile(typescript, "utf8"));
         const tsc = path.join(path.dirname(typescript), bin.tsc);
-        for (const project of ["tsconfig.main.json", "tsconfig.ui.json"]) {
-            const result = spawnSync(process.execPath, [tsc, "-p", path.join(".drift-beacon", project)], {
-                cwd: pkg,
-                stdio: ["ignore", 2, 2],
-            });
+        for (const part of ["main", "ui"]) {
+            const authored = `${part}/tsconfig.json`;
+            const project = existsSync(path.join(pkg, authored)) ? authored : `.drift-beacon/tsconfig.${part}.json`;
+            const result = spawnSync(process.execPath, [tsc, "-p", project], { cwd: pkg, stdio: ["ignore", 2, 2] });
             if (result.error)
                 throw result.error;
             if (result.status !== 0)
-                throw new Error(`Type errors (.drift-beacon/${project}); nothing was packed`);
+                throw new Error(`Type errors (${project}); nothing was packed`);
         }
         temp = await mkdtemp(path.join(tmpdir(), "dbplugin-pack-"));
         const vite = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("vite")).href));

package/dist/prepare.js

@@ -46,7 +46,7 @@ export function prepare(root, { strict }) {
     const out = path.join(root, ".drift-beacon");
     mkdirSync(out, { recursive: true });
     writeIfChanged(path.join(out, ".gitignore"), "*\n");
-    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest.configuration));
+    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest));
     writeIfChanged(path.join(out, "tsconfig.main.json"), `${JSON.stringify(TSCONFIG_MAIN, null, 2)}\n`);
     writeIfChanged(path.join(out, "tsconfig.ui.json"), `${JSON.stringify(TSCONFIG_UI, null, 2)}\n`);
     return loaded;
@@ -74,23 +74,68 @@ export function loadManifest(root) {
         throw new Error(`${file}: ${compatibility.message}`);
     return { manifest, bytes };
 }
-function configTypes(configuration) {
+function configTypes(manifest) {
     const lines = [
         "// Generated by dbplugin prepare from manifest.json. Do not edit.",
         'import type {} from "@drift-beacon/plugin";',
         'declare module "@drift-beacon/plugin" {',
         "  interface PluginConfig {",
     ];
-    for (const item of configuration) {
-        const doc = [item.title, item.description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    const member = (title, description, name, type) => {
+        const doc = docComment(title, description);
         if (doc)
-            lines.push(`    /** ${doc} */`);
+            lines.push(`    ${doc}`);
+        lines.push(`    ${name}: ${type};`);
+    };
+    for (const item of manifest.configuration) {
         const optional = item.required === true || item.default !== undefined ? "" : "?";
-        lines.push(`    ${JSON.stringify(item.name)}${optional}: ${valueType(item)};`);
+        member(item.title, item.description, `${JSON.stringify(item.name)}${optional}`, valueType(item));
     }
-    lines.push("  }", "}", "");
+    lines.push("  }");
+    const { commands = {}, events = {}, state = {} } = manifest.provides ?? {};
+    const block = (name, declarations, type) => {
+        if (!manifest.provides)
+            return;
+        lines.push(`  interface ${name} {`);
+        if (Object.keys(declarations).length === 0)
+            lines.push("    readonly [name: string]: never;");
+        for (const [key, declaration] of Object.entries(declarations))
+            member(declaration.title, declaration.description, JSON.stringify(key), type(declaration));
+        lines.push("  }");
+    };
+    block("PluginCommands", commands, ({ input, output }) => {
+        const inputType = input ? tsType(input) : NO_PROPERTIES;
+        return `{ readonly input: ${inputType}; readonly output: ${output ? tsType(output) : "undefined"} }`;
+    });
+    block("PluginEvents", events, ({ payload }) => (payload ? tsType(payload) : "undefined"));
+    block("PluginState", state, ({ schema }) => tsType(schema));
+    lines.push("}", "");
     return lines.join("\n");
 }
+const docComment = (title, description) => {
+    const doc = [title, description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    return doc ? `/** ${doc} */` : "";
+};
+const NO_PROPERTIES = "{ readonly [key: string]: never }";
+const SCALAR_TYPES = { string: "string", number: "number", integer: "number", boolean: "boolean", null: "null" };
+function tsType(schema) {
+    if (schema.enum)
+        return unique(schema.enum.map((value) => JSON.stringify(value)));
+    const types = typeof schema.type === "string" ? [schema.type] : schema.type;
+    return unique(types.map((type) => type === "array"
+        ? `readonly (${schema.items ? tsType(schema.items) : "unknown"})[]`
+        : type === "object"
+            ? objectType(schema)
+            : SCALAR_TYPES[type]));
+}
+function objectType(schema) {
+    const required = new Set(schema.required ?? []);
+    const members = Object.entries(schema.properties ?? {}).map(([name, property]) => `readonly ${JSON.stringify(name)}${required.has(name) ? "" : "?"}: ${tsType(property)}`);
+    if (schema.additionalProperties === true)
+        members.push("readonly [key: string]: unknown");
+    return members.length === 0 ? NO_PROPERTIES : `{ ${members.join("; ")} }`;
+}
+const unique = (types) => [...new Set(types)].join(" | ");
 const valueType = (item) => item.type !== "dropdown"
     ? item.type
     : item.data.length === 0

package/dist/types.d.ts

@@ -178,16 +178,78 @@ 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 the server has stored it. */
+    /**
+     * Applies locally at once and resolves when Drift Beacon has accepted the write. `undefined` removes the key;
+     * 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. */
     remove(key: string): Promise<void>;
     /** Called for changes made anywhere else: main code, a UI or another device. */
     onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
 }
-/** Error codes on rejected operations (`error.code`). */
-export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed";
+/**
+ * Error codes on rejected operations (`error.code`). For a command to another plugin: `unavailable`
+ * means it didn't run (the plugin isn't running here); `timeout` and `stopped` mean it may have run.
+ */
+export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed" | "not-installed" | "disabled" | "incompatible" | "loop" | "timeout";
+export interface CommandOptions {
+    /** How long to wait, in milliseconds (default 10 s, at most 30 s). Inside a command, at most what its caller has left. */
+    readonly timeoutMs?: number;
+}
+export type PluginStatusState = "running" | "starting" | "unavailable" | "disabled" | "incompatible" | "not-installed";
+/** Whether another plugin can run for this user in this workspace now. */
+export interface PluginStatus {
+    readonly state: PluginStatusState;
+    /** The version it resolved to, when one did. */
+    readonly version?: string;
+    /** Why it isn't running, when known. */
+    readonly reason?: string;
+}
+/** Another plugin's published state (or this plugin's own, as others see it: after a round trip). Values are read-only. */
+export interface PeerStateApi {
+    get<T = unknown>(key: string): T | undefined;
+    keys(): readonly string[];
+    /** A key changed, or was removed (`undefined`). */
+    onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
+}
+/** Another plugin this one uses (listed in manifest.json `uses`), or this plugin itself. */
+export interface PluginPeer {
+    /** Its manifest id. */
+    readonly id: string;
+    /**
+     * The same object until it changes. In main code, updated at once when the plugin starts, finishes starting or
+     * stops, and otherwise within 250 ms; in a UI, within about 250 ms.
+     */
+    readonly status: PluginStatus;
+    /** Called when its `state`, `version` or `reason` changes. */
+    onStatusChange(callback: (status: PluginStatus) => void): Unsubscribe;
+    /**
+     * Run one of its commands (manifest.json `provides.commands`) as this user in this workspace and wait for
+     * the result. Fails fast with `not-installed`, `disabled`, `incompatible` or `unavailable` when it can't run;
+     * `timeout` means it may have run. In main code, the state it published reaches this plugin before this resolves;
+     * in a UI, it (like storage and workspace data the command changed) can arrive just after.
+     */
+    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 {
+    /** A plugin listed in manifest.json `uses`, or this plugin's own manifest id. Anything else throws `invalid`. */
+    get(id: string): PluginPeer;
+    /** This plugin itself, as other plugins see it. */
+    readonly self: PluginPeer;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui.d.ts

@@ -1,9 +1,10 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export { PluginError } from "./errors.ts";
 export type * from "./types.ts";
 export { API_VERSION } from "./version.ts";
 /** Everything a plugin UI can use. */
 export interface UiContext {
+    /** The installed plugin; it can change while the UI is open, for example to a new version. */
     readonly plugin: PluginInfo;
     readonly user: UserInfo;
     readonly workspace: WorkspaceInfo;
@@ -12,9 +13,18 @@ export interface UiContext {
     readonly activities: ActivitiesApi;
     readonly categories: CategoriesApi;
     readonly sessions: SessionsApi;
-    /** Called after each update from the app (workspace data, config or storage) and after local storage writes. */
+    /**
+     * Called after each update from the app (workspace data, config, storage, or other plugins' status and state) and
+     * 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),
+     * 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;
 }
 export interface ConnectOptions {
     /** How long to wait for the app to answer. Default 10 seconds. */