@drift-beacon/plugin 0.1.0 → 0.2.0

package/dist/internal/actions.d.ts

@@ -1,35 +0,0 @@
-/**
- * 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/collection.d.ts

@@ -1,15 +0,0 @@
-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/compatibility.d.ts

@@ -1,26 +0,0 @@
-/**
- * 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

package/dist/internal/json-equal.d.ts

@@ -1,3 +0,0 @@
-/** Structural equality for JSON-shaped values such as data rows and storage items. */
-export declare function jsonEqual(a: unknown, b: unknown): boolean;
-//# sourceMappingURL=json-equal.d.ts.map

package/dist/internal/manifest.d.ts

@@ -1,51 +0,0 @@
-interface ConfigurationItemBase {
-    name: string;
-    title: string;
-    description?: string;
-    required?: boolean;
-}
-export interface StringConfigurationItem extends ConfigurationItemBase {
-    type: "string";
-    default?: string;
-    placeholder?: string;
-}
-export interface NumberConfigurationItem extends ConfigurationItemBase {
-    type: "number";
-    default?: number;
-    minimum?: number;
-    maximum?: number;
-}
-export interface BooleanConfigurationItem extends ConfigurationItemBase {
-    type: "boolean";
-    default?: boolean;
-}
-export interface DropdownConfigurationItem extends ConfigurationItemBase {
-    type: "dropdown";
-    default?: string;
-    data: ReadonlyArray<{
-        readonly title: string;
-        readonly value: string;
-    }>;
-}
-/** One setting declared in `manifest.json`; drives the settings form and config validation. */
-export type ConfigurationItem = StringConfigurationItem | NumberConfigurationItem | BooleanConfigurationItem | DropdownConfigurationItem;
-export interface PluginManifest {
-    id: string;
-    name: string;
-    version: string;
-    /** Plugin API version (`major.minor`) the plugin was built for. */
-    apiVersion: string;
-    description: string;
-    author: {
-        name: string;
-        email?: string;
-    };
-    category: "plugin" | "utility" | "ui";
-    icon: string;
-    configuration: readonly ConfigurationItem[];
-}
-export declare const isStableVersion: (value: unknown) => value is string;
-/** Throws a readable error when `manifest` is not a valid plugin manifest. Shared by the server and the pack tool. */
-export declare function validateManifest(manifest: unknown): asserts manifest is PluginManifest;
-export {};
-//# sourceMappingURL=manifest.d.ts.map

package/dist/internal/models.d.ts

@@ -1,62 +0,0 @@
-import type { ActivitiesApi, Activity, ActivityFilter, CategoriesApi, Category, Change, Session, SessionData, SessionFilter, SessionsApi } from "../types.ts";
-import type { Collection } from "./collection.ts";
-import type { ActivityRow, CategoryRow, SessionRow, WorkspaceRowChanges } from "./rows.ts";
-export interface WorkspaceCollections {
-    readonly activities: Collection<ActivityRow>;
-    readonly categories: Collection<CategoryRow>;
-    readonly sessions: Collection<SessionRow>;
-}
-/** Session operations. Each resolves with the session's row once the snapshot containing the result has arrived. */
-export interface SessionActions {
-    start(activityId: string): Promise<unknown>;
-    end(sessionId: string): Promise<unknown>;
-    mark(activityId: string): Promise<unknown>;
-    discard(sessionId: string): Promise<unknown>;
-}
-export interface ModelChanges {
-    readonly activities: readonly Change<Activity>[];
-    readonly categories: readonly Change<Category>[];
-    readonly sessions: readonly Change<Session>[];
-}
-/** The reads and actions of `ctx.activities`, `ctx.categories` and `ctx.sessions`. Contexts add the events. */
-export interface ModelApis {
-    readonly activities: Omit<ActivitiesApi, "onChange">;
-    readonly categories: Omit<CategoriesApi, "onChange">;
-    readonly sessions: Omit<SessionsApi, "onChange">;
-}
-export declare class WorkspaceModels {
-    #private;
-    readonly userId: string;
-    readonly rows: WorkspaceCollections;
-    constructor(options: {
-        readonly userId: string;
-        readonly rows: WorkspaceCollections;
-        readonly actions: SessionActions;
-    });
-    /** The reads and actions for `ctx`. */
-    apis(): ModelApis;
-    activity(id: string): Activity | undefined;
-    category(id: string): Category | undefined;
-    session(id: string): Session | undefined;
-    /** In the app's order: by category (uncategorized last), then `sortOrder`, then name. */
-    activities(filter?: ActivityFilter): readonly Activity[];
-    /** By `sortOrder`, then name. */
-    categories(): readonly Category[];
-    /** Newest first. */
-    sessions(filter?: SessionFilter): readonly Session[];
-    start(activityId: string): Promise<Session>;
-    end(sessionId: string): Promise<Session>;
-    mark(activityId: string): Promise<Session>;
-    discard(sessionId: string): Promise<void>;
-    /** Turn the row changes of a snapshot into model changes. Call it after the collections were replaced. */
-    update(changes: WorkspaceRowChanges): ModelChanges;
-    /**
-     * The model for a session the app sent outside a snapshot (a live event or an action result):
-     * the snapshot's model, or, when the row isn't in the snapshot, a removed model holding these values.
-     */
-    sessionFrom(row: SessionRow): Session;
-    activityRow(id: string): ActivityRow;
-    categoryRow(id: string): CategoryRow;
-    sessionData(id: string): SessionData;
-}
-//# sourceMappingURL=models.d.ts.map

package/dist/internal/package-layout.d.ts

@@ -1,21 +0,0 @@
-/**
- * The plugin package: `manifest.json`, `package.json`, `main/index.js` (plus chunks) and `ui/index.html`
- * (plus assets and the manifest icon). Shared by the pack tool and the server. Pure: the web app bundles
- * `/internal`, so no `node:` imports.
- */
-export declare const PACKAGE_LIMITS: {
-    readonly entries: 2000;
-    readonly fileBytes: number;
-    readonly totalBytes: number;
-    readonly archiveBytes: number;
-    readonly manifestBytes: number;
-};
-/** The `package.json` every package gets: main is ESM. */
-export declare const PACKAGE_JSON: {
-    readonly type: "module";
-    readonly private: true;
-};
-export declare const REQUIRED_FILES: readonly ["main/index.js", "ui/index.html"];
-/** manifest.json, package.json, main/** and ui/** (directories: main, ui and below). `name` has no trailing slash. */
-export declare const isPackagePath: (name: string, directory: boolean) => boolean;
-//# sourceMappingURL=package-layout.d.ts.map

package/dist/internal/protocol.d.ts

@@ -1,96 +0,0 @@
-/**
- * Messages between a plugin UI (iframe) and the web app hosting it, over `postMessage`.
- *
- * The UI client ships inside every published UI bundle, so this protocol is frozen into
- * them: change it only additively within an API version. The UI opens with `hello`; nothing
- * else flows until the host answers `welcome` or `reject`.
- */
-import type { PluginErrorCode, PluginInfo, UserInfo, WorkspaceInfo } from "../types.ts";
-import type { WorkspaceRows } from "./rows.ts";
-/** Marks our messages so both sides ignore unrelated `postMessage` traffic (dev tools, HMR). */
-export declare const UI_CHANNEL = "drift-beacon-plugin";
-/** Workspace data sent to a UI, as rows. */
-export type UiData = WorkspaceRows;
-export type UiRequest = {
-    readonly method: "sessions.start";
-    readonly params: {
-        readonly activityId: string;
-    };
-} | {
-    readonly method: "sessions.end";
-    readonly params: {
-        readonly sessionId: string;
-    };
-} | {
-    readonly method: "sessions.mark";
-    readonly params: {
-        readonly activityId: string;
-    };
-} | {
-    readonly method: "sessions.discard";
-    readonly params: {
-        readonly sessionId: string;
-    };
-} | {
-    readonly method: "storage.set";
-    readonly params: {
-        readonly key: string;
-        readonly value: unknown;
-    };
-} | {
-    readonly method: "storage.remove";
-    readonly params: {
-        readonly key: string;
-    };
-};
-export type UiToHostMessage = {
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "hello";
-    readonly apiVersion: string;
-} | ({
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "request";
-    readonly id: string;
-} & UiRequest);
-export interface UiError {
-    readonly code: PluginErrorCode;
-    readonly message: string;
-}
-export type HostToUiMessage = {
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "welcome";
-    readonly apiVersion: string;
-    readonly plugin: PluginInfo;
-    readonly user: UserInfo;
-    readonly workspace: WorkspaceInfo;
-    readonly config: Readonly<Record<string, unknown>>;
-    readonly data: UiData;
-    readonly storage: Readonly<Record<string, unknown>>;
-} | {
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "reject";
-    readonly reason: string;
-}
-/** The app restarted its side of the connection; the UI answers with `hello` and gets a new `welcome`. */
- | {
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "reconnect";
-} | {
-    /** Replaces whichever parts are present. */
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "state";
-    readonly config?: Readonly<Record<string, unknown>>;
-    readonly data?: UiData;
-    readonly storage?: Readonly<Record<string, unknown>>;
-} | {
-    readonly channel: typeof UI_CHANNEL;
-    readonly type: "response";
-    readonly id: string;
-    readonly result?: unknown;
-    readonly error?: UiError;
-};
-export declare function isUiMessage(value: unknown): value is {
-    channel: typeof UI_CHANNEL;
-    type: string;
-};
-//# sourceMappingURL=protocol.d.ts.map

package/dist/internal/rows.d.ts

@@ -1,41 +0,0 @@
-/**
- * Workspace data as it travels from the app to plugins: to plugin hosts over IPC and to plugin
- * UIs over `postMessage`. Plugins never see rows; the model layer (`models.ts`) wraps them.
- */
-import type { ActivityData, CategoryData } from "../types.ts";
-export type ActivityRow = ActivityData;
-export type CategoryRow = CategoryData;
-export interface SessionRow {
-    readonly id: string;
-    readonly activityId: string;
-    readonly type: "span" | "point";
-    readonly status: "live" | "completed";
-    readonly memberIds: readonly string[];
-    /** ISO timestamp: when a span started, or when a point was marked. */
-    readonly startedAt: string;
-    /** ISO timestamp when a span ended; null while live and for points. */
-    readonly endedAt: string | null;
-}
-export interface WorkspaceRows {
-    readonly activities: readonly ActivityRow[];
-    readonly categories: readonly CategoryRow[];
-    readonly sessions: readonly SessionRow[];
-}
-/** One change to a collection of rows. */
-export type RowChange<T> = {
-    readonly type: "added";
-    readonly item: T;
-} | {
-    readonly type: "updated";
-    readonly item: T;
-    readonly previous: T;
-} | {
-    readonly type: "removed";
-    readonly item: T;
-};
-export interface WorkspaceRowChanges {
-    readonly activities: readonly RowChange<ActivityRow>[];
-    readonly categories: readonly RowChange<CategoryRow>[];
-    readonly sessions: readonly RowChange<SessionRow>[];
-}
-//# sourceMappingURL=rows.d.ts.map

package/dist/internal.d.ts

@@ -1,17 +0,0 @@
-/**
- * Platform-only entry used by the plugin host, the web app and the server. Not part of the plugin API.
- * Public entries never import this file; SDK modules may import `internal/*` directly. Publishing drops
- * only its export key.
- */
-export * from "./dev.ts";
-export type { PluginAction } from "./internal/actions.ts";
-export { Collection } from "./internal/collection.ts";
-export { type ApiCompatibility, type ApiVersion, checkApiCompatibility, parseApiVersion, SUPPORTED_API_VERSIONS, } from "./internal/compatibility.ts";
-export { jsonEqual } from "./internal/json-equal.ts";
-export { type BooleanConfigurationItem, type ConfigurationItem, type DropdownConfigurationItem, isStableVersion, type NumberConfigurationItem, type PluginManifest, type StringConfigurationItem, validateManifest, } from "./internal/manifest.ts";
-export { type ModelApis, type ModelChanges, type SessionActions, type WorkspaceCollections, WorkspaceModels, } from "./internal/models.ts";
-export { isPackagePath, PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.ts";
-export * from "./internal/protocol.ts";
-export type { ActivityRow, CategoryRow, RowChange, SessionRow, WorkspaceRowChanges, WorkspaceRows, } from "./internal/rows.ts";
-export type { PluginErrorCode } from "./types.ts";
-//# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -1,13 +0,0 @@
-/**
- * Platform-only entry used by the plugin host, the web app and the server. Not part of the plugin API.
- * Public entries never import this file; SDK modules may import `internal/*` directly. Publishing drops
- * only its export key.
- */
-export * from "./dev.js";
-export { Collection } from "./internal/collection.js";
-export { checkApiCompatibility, parseApiVersion, SUPPORTED_API_VERSIONS, } from "./internal/compatibility.js";
-export { jsonEqual } from "./internal/json-equal.js";
-export { isStableVersion, validateManifest, } from "./internal/manifest.js";
-export { WorkspaceModels, } from "./internal/models.js";
-export { isPackagePath, PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.js";
-export * from "./internal/protocol.js";

package/dist/pack.d.ts

@@ -1,24 +0,0 @@
-export interface PackResult {
-    readonly id: string;
-    readonly version: string;
-    readonly tag: string;
-    readonly asset: string;
-    readonly archivePath: string;
-}
-/**
- * Zip the package in `dir` into `<outDir>/<id>.zip`: its manifest, a generated `package.json`, and `main/**`
- * and `ui/**`. Anything else in `dir` (the dev marker, its `package.json`) is left out. Never runs plugin code.
- */
-export declare function packDirectory(dir: string, outDir: string): Promise<PackResult>;
-export interface PackOptions {
-    /** Where the zip goes. Default `<root>/releases`. */
-    readonly out?: string;
-}
-/**
- * Build a release of the plugin package at `root`: prepare, typecheck main and UI with the package's own
- * TypeScript, `vite build` into a fresh temp folder with the package's own Vite, then `packDirectory`. The
- * package's `dist/` is never read or written. Everything printed meanwhile goes to stderr, so a caller's
- * stdout carries only the result.
- */
-export declare function pack(root: string, options?: PackOptions): Promise<PackResult>;
-//# sourceMappingURL=pack.d.ts.map

package/dist/prepare.d.ts

@@ -1,28 +0,0 @@
-import { type PluginManifest } from "./internal/manifest.ts";
-export interface PrepareOptions {
-    /**
-     * Throw on manifest problems (dev, build and pack). When false (`dbplugin prepare`, run on install), warn
-     * and leave `.drift-beacon/` as it was, so a manifest typo never fails `pnpm install`.
-     */
-    readonly strict: boolean;
-}
-/** A package's `manifest.json`: parsed and checked, with its bytes. */
-export interface LoadedManifest {
-    readonly manifest: PluginManifest;
-    readonly bytes: Buffer;
-}
-/**
- * Generate `<root>/.drift-beacon/` from the manifest, and return the manifest (`loadManifest`). Files are
- * rewritten only when their content changes.
- */
-export declare function prepare(root: string, options: {
-    readonly strict: true;
-}): LoadedManifest;
-export declare function prepare(root: string, options: PrepareOptions): LoadedManifest | null;
-/**
- * `<root>/manifest.json`, the one read of a manifest in the SDK (dev, build, prepare and pack): a regular
- * file within the package limit, valid, and for an `apiVersion` this SDK runs (the server's check). The
- * error names the file.
- */
-export declare function loadManifest(root: string): LoadedManifest;
-//# sourceMappingURL=prepare.d.ts.map