@drift-beacon/plugin 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Data and APIs shared by plugin main code (server) and UIs (iframe).
+ *
+ * Workspace data comes as models: an `Activity`, `Category` or `Session` with its fields, links,
+ * derived values and actions. Models read the latest snapshot the app sent, synchronously; there is
+ * one model per row for the life of a `ctx`, and `model.data` is its plain, frozen row. Later API
+ * versions may add fields and new values to string unions such as `trackingType`, so plugins must
+ * ignore what they don't recognise.
+ */
+/** Stops a subscription. Subscriptions made through `ctx` also stop when the instance stops. */
+export type Unsubscribe = () => void;
+/** An activity's plain row: what `activity.data` returns. */
+export interface ActivityData {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly trackingType: "span" | "point";
+    readonly icon: string;
+    /** SVG path data for `icon` (viewBox 0 0 24 24; draw with fill), computed by the app. Null when `icon` isn't a known MDI icon. */
+    readonly iconPath: string | null;
+    /** Display colour, already resolved from the category when the activity uses its category's colour. */
+    readonly color: string;
+    readonly categoryId: string | null;
+    readonly archived: boolean;
+    /** Position within the activity's category. */
+    readonly sortOrder: number;
+    readonly unit: string | null;
+}
+/** A category's plain row: what `category.data` returns. */
+export interface CategoryData {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly color: string;
+    readonly icon: string;
+    /** SVG path data for `icon` (viewBox 0 0 24 24; draw with fill), computed by the app. Null when `icon` isn't a known MDI icon. */
+    readonly iconPath: string | null;
+    readonly sortOrder: number;
+}
+/** A session's plain row: what `session.data` returns. */
+export interface SessionData {
+    readonly id: string;
+    readonly activityId: string;
+    /** `span` sessions run from start to end; `point` sessions are a single mark. */
+    readonly type: "span" | "point";
+    readonly status: "live" | "completed";
+    /** Users taking part in the session. */
+    readonly memberIds: readonly string[];
+    /** When a span started, or when a point was marked. Don't mutate it: copy it first. */
+    readonly startedAt: Date;
+    /** When a span ended; null while live and for points. */
+    readonly endedAt: Date | null;
+}
+/** Fields every model has. */
+export interface Model<Data> {
+    /** False once the row is gone from the workspace; the fields then keep their last values. */
+    readonly exists: boolean;
+    /** The row in the latest snapshot, frozen: a new object whenever the row changes. */
+    readonly data: Data;
+}
+export interface Activity extends Readonly<ActivityData>, Model<ActivityData> {
+    readonly isSpan: boolean;
+    readonly isPoint: boolean;
+    /** The current user has a live session of this activity. */
+    readonly isLive: boolean;
+    readonly category: Category | undefined;
+    /** This activity's sessions, newest first. */
+    sessions(filter?: Omit<SessionFilter, "activityId">): readonly Session[];
+    /** Live sessions of this activity; with `mine: true`, only the current user's. */
+    live(options?: {
+        readonly mine?: boolean;
+    }): readonly Session[];
+    /** Start a span session for the current user. */
+    start(): Promise<Session>;
+    /** Mark a point activity for the current user. */
+    mark(): Promise<Session>;
+    /** `start()` for a span activity, `mark()` for a point activity. */
+    track(): Promise<Session>;
+    /** End the current user's live session of this activity. Rejects with `not-found` when there is none. */
+    end(): Promise<Session>;
+}
+export interface Category extends Readonly<CategoryData>, Model<CategoryData> {
+    /** Activities in this category, sorted. Archived ones are hidden unless `includeArchived` is set. */
+    activities(filter?: Omit<ActivityFilter, "categoryId">): readonly Activity[];
+}
+export interface Session extends Readonly<SessionData>, Model<SessionData> {
+    readonly isSpan: boolean;
+    readonly isPoint: boolean;
+    readonly isLive: boolean;
+    /** The current user takes part in the session. */
+    readonly isMine: boolean;
+    readonly activity: Activity | undefined;
+    /** Milliseconds from start to end; while live, from start to `at` (default: now). 0 for points. */
+    duration(at?: Date): number;
+    /** End this live span session. */
+    end(): Promise<Session>;
+    /** Discard this live span session, as if it never happened. */
+    discard(): Promise<void>;
+}
+export interface ActivityFilter {
+    /** Activities in this category; `null` for activities without one. */
+    readonly categoryId?: string | null;
+    readonly trackingType?: "span" | "point";
+    /** Archived activities are hidden unless this is true. */
+    readonly includeArchived?: boolean;
+}
+export interface SessionFilter {
+    readonly activityId?: string;
+    readonly status?: "live" | "completed";
+    /** Only sessions the current user takes part in. */
+    readonly mine?: boolean;
+}
+/** One change to a collection, reported by `onChange`. `previous` is the row before the change. */
+export type Change<T extends Model<unknown>> = {
+    readonly type: "added";
+    readonly item: T;
+} | {
+    readonly type: "updated";
+    readonly item: T;
+    readonly previous: T["data"];
+} | {
+    readonly type: "removed";
+    readonly item: T;
+};
+export interface PluginInfo {
+    /** Installed identity, for example `github.123.magic-cube`. Differs from the manifest id for installed plugins. */
+    readonly id: string;
+    readonly version: string;
+    /** Base path of this plugin's HTTP routes, for example `/api/plugins/<id>/api`. */
+    readonly apiPath: string;
+}
+export interface UserInfo {
+    readonly id: string;
+}
+export interface WorkspaceInfo {
+    readonly id: string;
+}
+/** The plugin's settings. `dbplugin prepare` fills this in from manifest.json `configuration` (.drift-beacon/config.d.ts). */
+export interface PluginConfig {
+}
+export interface ActivitiesApi {
+    /**
+     * In the app's order: by category (uncategorized last), then `sortOrder`, then name. Archived
+     * activities are hidden unless `includeArchived` is set. The same array comes back until the next snapshot.
+     */
+    list(filter?: ActivityFilter): readonly Activity[];
+    /** Any activity in the workspace, archived or not. */
+    get(id: string): Activity | undefined;
+    /** Data change events. They can arrive in bursts after a sync; don't use them to trigger actions. */
+    onChange(callback: (change: Change<Activity>) => void): Unsubscribe;
+}
+export interface CategoriesApi {
+    /** Sorted by `sortOrder`, then name. The same array comes back until the next snapshot. */
+    list(): readonly Category[];
+    get(id: string): Category | undefined;
+    /** Data change events. They can arrive in bursts after a sync; don't use them to trigger actions. */
+    onChange(callback: (change: Change<Category>) => void): Unsubscribe;
+}
+export interface SessionsApi {
+    /** Newest first. The same array comes back until the next snapshot. */
+    list(filter?: SessionFilter): readonly Session[];
+    get(id: string): Session | undefined;
+    /** Live sessions in the workspace: `list({ status: "live", mine })`. */
+    live(options?: {
+        readonly mine?: boolean;
+    }): readonly Session[];
+    /**
+     * Start a span session for the current user. Actions resolve once the snapshot containing
+     * their result has arrived, so lists and models already show it.
+     */
+    start(activityId: string): Promise<Session>;
+    /** End a live span session. */
+    end(sessionId: string): Promise<Session>;
+    /** Mark a point activity for the current user. */
+    mark(activityId: string): Promise<Session>;
+    /** Discard a live span session, as if it never happened. Afterwards it is no longer live (or gone). */
+    discard(sessionId: string): Promise<void>;
+    /** 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. */
+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. */
+    set(key: string, value: unknown): Promise<void>;
+    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";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Data and APIs shared by plugin main code (server) and UIs (iframe).
+ *
+ * Workspace data comes as models: an `Activity`, `Category` or `Session` with its fields, links,
+ * derived values and actions. Models read the latest snapshot the app sent, synchronously; there is
+ * one model per row for the life of a `ctx`, and `model.data` is its plain, frozen row. Later API
+ * versions may add fields and new values to string unions such as `trackingType`, so plugins must
+ * ignore what they don't recognise.
+ */
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,25 @@
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, 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 {
+    readonly plugin: PluginInfo;
+    readonly user: UserInfo;
+    readonly workspace: WorkspaceInfo;
+    /** The plugin's current settings; they can change while the UI is open. */
+    readonly config: Readonly<PluginConfig>;
+    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. */
+    onDataChange(callback: () => void): Unsubscribe;
+    readonly storage: StorageApi;
+}
+export interface ConnectOptions {
+    /** How long to wait for the app to answer. Default 10 seconds. */
+    readonly timeoutMs?: number;
+}
+/** Connect to the Drift Beacon web app. Resolves once the app accepts this UI; later calls return the same context. */
+export declare function connect(options?: ConnectOptions): Promise<UiContext>;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.js

@@ -0,0 +1,265 @@
+/**
+ * The UI client: runs inside a plugin's iframe and talks to the Drift Beacon web app.
+ *
+ * ```ts
+ * const ctx = await connect();
+ * ctx.onDataChange(render);
+ * ```
+ */
+import { PluginError } from "./errors.js";
+import { Collection } from "./internal/collection.js";
+import { jsonEqual } from "./internal/json-equal.js";
+import { WorkspaceModels } from "./internal/models.js";
+import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
+import { API_VERSION } from "./version.js";
+export { PluginError } from "./errors.js";
+export { API_VERSION } from "./version.js";
+const HELLO_INTERVAL_MS = 250;
+const REQUEST_TIMEOUT_MS = 10_000;
+let connection = null;
+/** Connect to the Drift Beacon web app. Resolves once the app accepts this UI; later calls return the same context. */
+export function connect(options = {}) {
+    connection ??= open(options.timeoutMs ?? 10_000);
+    return connection;
+}
+function open(timeoutMs) {
+    if (typeof window === "undefined" || window.parent === window) {
+        return Promise.reject(new PluginError("unavailable", "A plugin UI must run inside Drift Beacon"));
+    }
+    const host = window.parent;
+    const post = (message) => host.postMessage(message, "*");
+    return new Promise((resolve, reject) => {
+        let client = null;
+        const finish = () => {
+            clearInterval(hello);
+            clearTimeout(timeout);
+        };
+        const onMessage = (event) => {
+            if (event.source !== host || !isUiMessage(event.data))
+                return;
+            const message = event.data;
+            if (message.type === "reconnect") {
+                sayHello();
+                return;
+            }
+            if (client) {
+                client.receive(message);
+                return;
+            }
+            if (message.type === "welcome") {
+                finish();
+                client = new UiClient(message, post);
+                resolve(client.context);
+            }
+            else if (message.type === "reject") {
+                finish();
+                window.removeEventListener("message", onMessage);
+                reject(new PluginError("unsupported", message.reason));
+            }
+        };
+        window.addEventListener("message", onMessage);
+        const sayHello = () => post({ channel: UI_CHANNEL, type: "hello", apiVersion: API_VERSION });
+        // Repeat until answered: the app may still be setting up when the UI first loads.
+        const hello = setInterval(sayHello, HELLO_INTERVAL_MS);
+        sayHello();
+        const timeout = setTimeout(() => {
+            finish();
+            window.removeEventListener("message", onMessage);
+            reject(new PluginError("unavailable", "Drift Beacon did not answer. Reload the plugin."));
+        }, timeoutMs);
+    });
+}
+class UiClient {
+    post;
+    context;
+    config;
+    rows = {
+        activities: new Collection(),
+        categories: new Collection(),
+        sessions: new Collection(),
+    };
+    models;
+    activityListeners = new Set();
+    categoryListeners = new Set();
+    sessionListeners = new Set();
+    dataListeners = new Set();
+    storageListeners = new Set();
+    storage = new Map();
+    serverStorage;
+    /** Keys with writes the app hasn't answered; older pushes must not revert them. */
+    pendingWrites = new Map();
+    /**
+     * Keys written since the app last sent storage, with the latest write's ID. The app may answer a
+     * write before its next push, so an answered write stays in place until that push arrives.
+     */
+    writesSincePush = new Map();
+    nextWrite = 0;
+    pending = new Map();
+    nextRequest = 0;
+    constructor(welcome, post) {
+        this.post = post;
+        this.config = welcome.config;
+        this.serverStorage = welcome.storage;
+        this.storage = new Map(Object.entries(welcome.storage));
+        this.models = new WorkspaceModels({
+            userId: welcome.user.id,
+            rows: this.rows,
+            actions: {
+                start: (activityId) => this.request({ method: "sessions.start", params: { activityId } }),
+                end: (sessionId) => this.request({ method: "sessions.end", params: { sessionId } }),
+                mark: (activityId) => this.request({ method: "sessions.mark", params: { activityId } }),
+                discard: (sessionId) => this.request({ method: "sessions.discard", params: { sessionId } }),
+            },
+        });
+        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 = {
+            plugin: welcome.plugin,
+            user: welcome.user,
+            workspace: welcome.workspace,
+            get config() {
+                return self.config;
+            },
+            activities: { ...apis.activities, onChange: (callback) => subscribe(this.activityListeners, callback) },
+            categories: { ...apis.categories, onChange: (callback) => subscribe(this.categoryListeners, callback) },
+            sessions: { ...apis.sessions, onChange: (callback) => subscribe(this.sessionListeners, callback) },
+            onDataChange: (callback) => subscribe(this.dataListeners, callback),
+            storage: {
+                get: (key) => this.storage.get(key),
+                keys: () => [...this.storage.keys()],
+                set: (key, value) => this.write(key, JSON.parse(JSON.stringify(value))),
+                remove: (key) => this.write(key, undefined),
+                onChange: (callback) => subscribe(this.storageListeners, callback),
+            },
+        };
+    }
+    receive(message) {
+        if (message.type === "welcome") {
+            // A reconnect: identity is unchanged, so only the state is new.
+            this.receive({
+                channel: message.channel,
+                type: "state",
+                config: message.config,
+                data: message.data,
+                storage: message.storage,
+            });
+            return;
+        }
+        if (message.type === "response") {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            if (message.error)
+                pending.reject(new PluginError(message.error.code, message.error.message));
+            else
+                pending.resolve(message.result);
+            return;
+        }
+        if (message.type !== "state")
+            return;
+        if (message.config)
+            this.config = message.config;
+        if (message.data)
+            this.applyData(message.data);
+        if (message.storage) {
+            this.serverStorage = message.storage;
+            this.writesSincePush.clear();
+            this.reconcileStorage();
+        }
+        notify(this.dataListeners, (listener) => listener());
+    }
+    /** Replace all three collections before telling anyone, so callbacks see one consistent snapshot. */
+    applyData(data) {
+        const changes = this.models.update({
+            activities: this.rows.activities.replace(data.activities),
+            categories: this.rows.categories.replace(data.categories),
+            sessions: this.rows.sessions.replace(data.sessions),
+        });
+        for (const change of changes.activities)
+            notify(this.activityListeners, (listener) => listener(change));
+        for (const change of changes.categories)
+            notify(this.categoryListeners, (listener) => listener(change));
+        for (const change of changes.sessions)
+            notify(this.sessionListeners, (listener) => listener(change));
+    }
+    /** Apply the app's storage, keeping local values for keys with unconfirmed writes. Returns whether anything changed. */
+    reconcileStorage() {
+        const isProtected = (key) => this.pendingWrites.has(key) || this.writesSincePush.has(key);
+        const next = new Map();
+        for (const [key, value] of Object.entries(this.serverStorage))
+            if (!isProtected(key))
+                next.set(key, value);
+        for (const [key, value] of this.storage)
+            if (isProtected(key))
+                next.set(key, value);
+        const previous = this.storage;
+        this.storage = next;
+        let changed = false;
+        for (const key of new Set([...previous.keys(), ...next.keys()])) {
+            if (jsonEqual(previous.get(key), next.get(key)))
+                continue;
+            changed = true;
+            if (!isProtected(key))
+                notify(this.storageListeners, (listener) => listener(key, next.get(key)));
+        }
+        return changed;
+    }
+    async write(key, value) {
+        const writeId = ++this.nextWrite;
+        this.pendingWrites.set(key, (this.pendingWrites.get(key) ?? 0) + 1);
+        this.writesSincePush.set(key, writeId);
+        if (value === undefined)
+            this.storage.delete(key);
+        else
+            this.storage.set(key, value);
+        notify(this.dataListeners, (listener) => listener());
+        try {
+            await this.request(value === undefined
+                ? { method: "storage.remove", params: { key } }
+                : { method: "storage.set", params: { key, value } });
+        }
+        catch (error) {
+            // Roll back to the app's value, unless a later local write replaced this one.
+            if (this.writesSincePush.get(key) === writeId)
+                this.writesSincePush.delete(key);
+            throw error;
+        }
+        finally {
+            const remaining = (this.pendingWrites.get(key) ?? 1) - 1;
+            if (remaining > 0)
+                this.pendingWrites.set(key, remaining);
+            else
+                this.pendingWrites.delete(key);
+            if (this.reconcileStorage())
+                notify(this.dataListeners, (listener) => listener());
+        }
+    }
+    request(request) {
+        const id = String(++this.nextRequest);
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.post({ channel: UI_CHANNEL, type: "request", id, ...request });
+            setTimeout(() => {
+                if (!this.pending.delete(id))
+                    return;
+                reject(new PluginError("unavailable", `${request.method} timed out`));
+            }, REQUEST_TIMEOUT_MS);
+        });
+    }
+}
+function notify(listeners, call) {
+    for (const listener of listeners) {
+        try {
+            call(listener);
+        }
+        catch (error) {
+            console.error("[drift-beacon] Error in plugin listener:", error);
+        }
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The plugin API version this SDK describes, `major.minor`. It matches the package version's
+ * major and minor. Before 1.0 every minor version may break plugins.
+ */
+export declare const API_VERSION = "0.1";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,5 @@
+/**
+ * The plugin API version this SDK describes, `major.minor`. It matches the package version's
+ * major and minor. Before 1.0 every minor version may break plugins.
+ */
+export const API_VERSION = "0.1";

package/dist/vite.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Vite plugin for a Drift Beacon plugin package: `plugins: [driftBeacon()]`. It owns `root`, `base` and
+ * `build.outDir`. Typed as `{ name: string }` so it fits any Vite version's `plugins`.
+ */
+export declare function driftBeacon(): {
+    name: string;
+};
+//# sourceMappingURL=vite.d.ts.map