@tx5dr/plugin-api 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,135 @@
+# @tx5dr/plugin-api
+
+Public plugin API for the [TX-5DR](https://github.com/boybook/tx-5dr) digital radio engine.
+
+Plugin authors should import from this package instead of reaching into internal monorepo packages. It provides TypeScript types for plugin definitions, runtime helpers, logbook sync providers, and the iframe Bridge SDK.
+
+## Installation
+
+```bash
+npm install --save-dev @tx5dr/plugin-api
+```
+
+## Quick Start
+
+### TypeScript
+
+```typescript
+import type { PluginDefinition, PluginContext } from '@tx5dr/plugin-api';
+
+const plugin: PluginDefinition = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  type: 'utility',
+  hooks: {
+    onDecode(messages, ctx) {
+      for (const msg of messages) {
+        ctx.log.debug('Decoded', { raw: msg.rawMessage });
+      }
+    },
+  },
+};
+
+export default plugin;
+```
+
+### JavaScript (with JSDoc types)
+
+```javascript
+/** @type {import('@tx5dr/plugin-api').PluginDefinition} */
+export default {
+  name: 'my-plugin',
+  version: '1.0.0',
+  type: 'utility',
+  hooks: {
+    onDecode(messages, ctx) {
+      for (const msg of messages) {
+        ctx.log.debug('Decoded', { raw: msg.rawMessage });
+      }
+    },
+  },
+};
+```
+
+## Exports
+
+| Subpath | Description |
+|---------|-------------|
+| `@tx5dr/plugin-api` | Core types: `PluginDefinition`, `PluginContext`, `PluginHooks`, helper interfaces, radio/message types |
+| `@tx5dr/plugin-api/testing` | Mock factories for unit testing: `createMockContext()`, `createMockSlotInfo()`, `createMockParsedMessage()` |
+| `@tx5dr/plugin-api/bridge` | Ambient type declarations for the iframe Bridge SDK (`window.tx5dr`) |
+
+## Bridge SDK Types
+
+Plugin iframe pages communicate with the host via the Bridge SDK (`window.tx5dr`), which is automatically injected by the host. To get IDE autocomplete for the Bridge SDK, add the type reference to your project:
+
+**tsconfig.json / jsconfig.json:**
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@tx5dr/plugin-api/bridge"]
+  }
+}
+```
+
+**Or per-file:**
+
+```javascript
+/// <reference types="@tx5dr/plugin-api/bridge" />
+
+tx5dr.invoke('getState').then(function(state) {
+  // Full autocomplete for tx5dr methods
+});
+```
+
+## CSS Design Tokens
+
+The host injects CSS custom properties (`--tx5dr-*`) into every iframe page. A reference copy is included in this package at `tokens.css` — copy it into your project for CSS autocomplete in your IDE:
+
+```bash
+cp node_modules/@tx5dr/plugin-api/tokens.css ./ui/
+```
+
+Then use the tokens in your plugin CSS:
+
+```css
+.container {
+  background: var(--tx5dr-bg-content);
+  color: var(--tx5dr-text);
+  border-radius: var(--tx5dr-radius-md);
+  padding: var(--tx5dr-spacing-md);
+  font-family: var(--tx5dr-font);
+}
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import {
+  createMockContext,
+  createMockSlotInfo,
+  createMockParsedMessage,
+} from '@tx5dr/plugin-api/testing';
+import plugin from './index.js';
+
+describe('my-plugin', () => {
+  it('processes decoded messages', () => {
+    const ctx = createMockContext();
+    const messages = [createMockParsedMessage({ rawMessage: 'CQ W1AW FN31' })];
+
+    plugin.hooks!.onDecode!(messages, ctx);
+
+    expect(ctx.log._calls.some(c => c.level === 'debug')).toBe(true);
+  });
+});
+```
+
+## Documentation
+
+For the full plugin system guide, see [docs/plugin-system.md](https://github.com/boybook/tx-5dr/blob/main/docs/plugin-system.md).
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -1,4 +1,5 @@
-import type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, BandAccess, UIBridge } from './helpers.js';
+import type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, BandAccess, UIBridge, PluginFileStore } from './helpers.js';
+import type { LogbookSyncRegistrar } from './sync.js';
 /**
  * Runtime services exposed to a plugin instance.
  *
@@ -60,7 +61,13 @@ export interface PluginContext {
      */
     readonly radio: RadioControl;
     /**
-     * Read-only access to logbook-derived history.
+     * Full logbook access — read-only queries, record writes and UI notifications.
+     *
+     * Provides the original read-only helpers (`hasWorked`, `hasWorkedDXCC`,
+     * `hasWorkedGrid`) plus advanced query (`queryQSOs`, `countQSOs`), write
+     * (`addQSO`, `updateQSO`) and notification (`notifyUpdated`) capabilities.
+     * Sync providers and other data-oriented plugins use the write methods to
+     * self-orchestrate their flow without host-side special handling.
      */
     readonly logbook: LogbookAccess;
     /**
@@ -68,9 +75,26 @@ export interface PluginContext {
      */
     readonly band: BandAccess;
     /**
-     * Bridge for pushing structured data into declarative plugin panels.
+     * Bridge for pushing structured data into declarative plugin panels and
+     * for communicating with custom iframe UI pages.
      */
     readonly ui: UIBridge;
+    /**
+     * Persistent binary file storage sandboxed to the plugin.
+     *
+     * Files are stored in the plugin data directory under a host-managed sandbox.
+     * Use this for binary assets such as certificates, images or cached data.
+     * For structured JSON data, prefer {@link PluginContext.store} instead.
+     */
+    readonly files: PluginFileStore;
+    /**
+     * Logbook sync registration entry point.
+     *
+     * Utility plugins that implement logbook synchronization call
+     * `ctx.logbookSync.register(provider)` during `onLoad` to register their
+     * sync provider. The host manages the provider lifecycle and UI integration.
+     */
+    readonly logbookSync: LogbookSyncRegistrar;
     /**
      * Permission-gated HTTP client.
      *

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,EACT,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;WAEG;QACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;WAEG;QACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzE"}

package/dist/definition.d.ts

@@ -1,4 +1,4 @@
-import type { PluginSettingDescriptor, PluginQuickAction, PluginQuickSetting, PluginPanelDescriptor, PluginPermission, PluginType } from '@tx5dr/contracts';
+import type { PluginSettingDescriptor, PluginQuickAction, PluginQuickSetting, PluginPanelDescriptor, PluginPermission, PluginType, PluginInstanceScope, PluginUIPageDescriptor } from '@tx5dr/contracts';
 import type { PluginContext } from './context.js';
 import type { PluginHooks } from './hooks.js';
 import type { StrategyRuntime } from './runtime.js';
@@ -91,6 +91,13 @@ export interface PluginDefinition {
      *   do not own the core automation state machine.
      */
     type: PluginType;
+    /**
+     * Controls whether the host creates one instance per operator or a single
+     * shared instance for the whole station.
+     *
+     * Defaults to `operator` when omitted.
+     */
+    instanceScope?: PluginInstanceScope;
     /**
      * Human-readable summary shown in plugin management UIs.
      *
@@ -132,8 +139,14 @@ export interface PluginDefinition {
     /**
      * Panel descriptors used to render plugin-owned UI sections.
      *
-     * Panels are declarative containers. Plugins push live data into them through
-     * {@link PluginContext.ui} rather than rendering custom frontend code.
+     * Structured panels (`key-value`, `table`, `log`, `chart`) receive live data
+     * through {@link PluginContext.ui.send}. Iframe panels (`component: 'iframe'`)
+     * render a custom HTML page and communicate via `invoke` / `onPush`.
+     *
+     * Each panel has a `slot` that controls where it renders: `'operator'` (the
+     * default, shown in the operator card) or `'automation'` (shown in the
+     * top-right automation popover). Panels may also declare a preferred
+     * `width`, such as `'full'`, so hosts can promote more important live panels.
      */
     panels?: PluginPanelDescriptor[];
     /**
@@ -146,6 +159,25 @@ export interface PluginDefinition {
     storage?: {
         scopes: ('global' | 'operator')[];
     };
+    /**
+     * Declares custom UI pages served from the plugin's static file directory.
+     *
+     * Pages are rendered inside an iframe by the host's `PluginIframeHost`
+     * component. The host automatically injects CSS design tokens and a
+     * communication bridge SDK. Plugins can use any web technology inside the
+     * iframe.
+     *
+     * Pages are declarative — they only define _what_ exists, not _where_ it is
+     * rendered. The rendering location is decided by consumers (e.g. a logbook
+     * sync host renders the page in a settings modal tab, while a future
+     * dashboard host may render it in a side panel).
+     */
+    ui?: {
+        /** Static file directory relative to the plugin root (default: 'ui'). */
+        dir?: string;
+        /** Registered custom UI pages. */
+        pages?: PluginUIPageDescriptor[];
+    };
     /**
      * Creates the strategy runtime for a `strategy` plugin.
      *

package/dist/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAA;KAAE,CAAC;IAEhD;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAAC;IAE5D;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAErC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAA;KAAE,CAAC;IAEhD;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,EAAE;QACH,yEAAyE;QACzE,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,kCAAkC;QAClC,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;KAClC,CAAC;IAEF;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAAC;IAE5D;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/dist/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedFT8Message, SlotInfo, SlotPack, QSORecord, FrameMessage, OperatorSlots, ModeDescriptor } from '@tx5dr/contracts';
+import type { ParsedFT8Message, SlotInfo, SlotPack, QSORecord, FrameMessage, OperatorSlots, ModeDescriptor, PermissionGrant } from '@tx5dr/contracts';
 import type { StrategyRuntimeSnapshot } from './runtime.js';
 /**
  * Simple persistent key-value store exposed to plugins.
@@ -25,6 +25,14 @@ export interface KVStore {
      * Returns a shallow snapshot of all stored entries in this scope.
      */
     getAll(): Record<string, unknown>;
+    /**
+     * Flushes pending writes to persistent storage.
+     *
+     * In normal operation the host flushes automatically. Call this explicitly
+     * only when you need to guarantee that recently written data survives a
+     * crash or restart (e.g. during a migration sequence).
+     */
+    flush(): Promise<void>;
 }
 /**
  * Structured logger dedicated to a plugin instance.
@@ -141,7 +149,71 @@ export interface RadioControl {
     setFrequency(freq: number): Promise<void>;
 }
 /**
- * Read-only helpers backed by the station logbook.
+ * Filter criteria for querying QSO records from the logbook.
+ *
+ * This type is defined in the plugin-api layer so plugins have no compile-time
+ * dependency on core internals. The host translates it to the storage layer's
+ * native query format.
+ */
+export interface QSOQueryFilter {
+    /** Match a specific callsign (exact match). */
+    callsign?: string;
+    /** Restrict to a time window (epoch ms). */
+    timeRange?: {
+        start: number;
+        end: number;
+    };
+    /** Restrict to a frequency window (Hz). */
+    frequencyRange?: {
+        min: number;
+        max: number;
+    };
+    /** Mode filter (e.g. 'FT8'). */
+    mode?: string;
+    /**
+     * QSL confirmation status filter.
+     * - `'confirmed'`: at least one platform confirmed
+     * - `'uploaded'`: at least one platform uploaded but not confirmed
+     * - `'none'`: not uploaded to any platform
+     */
+    qslStatus?: 'confirmed' | 'uploaded' | 'none';
+    /** Maximum number of records to return. */
+    limit?: number;
+    /** Number of records to skip (for pagination). */
+    offset?: number;
+    /** Sort direction. Defaults to descending (newest first). */
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * Callsign-bound view over a single logbook.
+ *
+ * The host resolves the concrete logbook lazily on each operation, which keeps
+ * the handle valid even if the underlying logbook is created or reloaded later.
+ */
+export interface CallsignLogbookAccess {
+    /** Normalized callsign that scopes this accessor. */
+    readonly callsign: string;
+    /** Returns the resolved logbook id, or null when no logbook exists yet. */
+    getLogBookId(): Promise<string | null>;
+    /** Queries QSO records matching the given filter. */
+    queryQSOs(filter: QSOQueryFilter): Promise<import('@tx5dr/contracts').QSORecord[]>;
+    /** Counts QSO records matching the given filter. */
+    countQSOs(filter?: QSOQueryFilter): Promise<number>;
+    /** Adds a new QSO record to this callsign's logbook. */
+    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<void>;
+    /** Updates partial fields of an existing QSO record. */
+    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<void>;
+    /** Returns current statistics for this callsign's logbook. */
+    getStatistics(): Promise<import('@tx5dr/contracts').LogBookStatistics | null>;
+    /** Notifies the frontend that this callsign's logbook changed. */
+    notifyUpdated(operatorId?: string): Promise<void>;
+}
+/**
+ * Full logbook access for plugins.
+ *
+ * Extends the original read-only helpers with query, write and notification
+ * capabilities so that sync providers can self-orchestrate their entire flow
+ * without host-side special handling.
  */
 export interface LogbookAccess {
     /** Checks whether the callsign has already been worked. */
@@ -150,6 +222,18 @@ export interface LogbookAccess {
     hasWorkedDXCC(dxccEntity: string): Promise<boolean>;
     /** Checks whether the Maidenhead grid has already been worked. */
     hasWorkedGrid(grid: string): Promise<boolean>;
+    /** Queries QSO records matching the given filter. */
+    queryQSOs(filter: QSOQueryFilter): Promise<import('@tx5dr/contracts').QSORecord[]>;
+    /** Counts QSO records matching the given filter. */
+    countQSOs(filter?: QSOQueryFilter): Promise<number>;
+    /** Returns a callsign-bound accessor suitable for global plugin instances. */
+    forCallsign(callsign: string): CallsignLogbookAccess;
+    /** Adds a new QSO record. Deduplication is the caller's responsibility. */
+    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<void>;
+    /** Updates partial fields of an existing QSO record (e.g. QSL status). */
+    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<void>;
+    /** Notifies the frontend to refresh logbook data (call after batch writes). */
+    notifyUpdated(): Promise<void>;
 }
 /**
  * Optional constraints used when asking the host for a quieter transmit offset.
@@ -219,5 +303,104 @@ export interface UIBridge {
      * Publishes new panel data for the given declarative panel id.
      */
     send(panelId: string, data: unknown): void;
+    /**
+     * Registers a handler for custom messages sent from iframe UI pages via the
+     * `bridge.invoke()` SDK method. The host routes incoming invoke requests to
+     * the handler and sends the return value back to the iframe.
+     *
+     * Only one handler can be registered per plugin instance. Calling this method
+     * again replaces the previous handler.
+     */
+    registerPageHandler(handler: PluginUIHandler): void;
+    /**
+     * Pushes a custom message to the specific page session.
+     *
+     * Prefer this API whenever the plugin already knows the target session id
+     * (for example from {@link PluginUIRequestContext.pageSessionId} or
+     * `requestContext.page.sessionId`).
+     */
+    pushToSession(pageSessionId: string, action: string, data?: unknown): void;
+    /**
+     * Lists active page sessions for the current plugin instance and page id.
+     *
+     * This is useful for background timers or sync completions that need to
+     * notify every open page tied to the same runtime instance.
+     */
+    listActivePageSessions(pageId: string): PluginUIPageSessionInfo[];
+    /**
+     * Pushes a custom message to an iframe UI page by page id.
+     *
+     * This compatibility helper only succeeds when exactly one active session of
+     * the current plugin instance matches the page id. If multiple sessions are
+     * open, the host throws `explicit_page_session_required`.
+     */
+    pushToPage(pageId: string, action: string, data?: unknown): void;
+}
+/**
+ * Handler for custom messages sent from iframe UI pages.
+ *
+ * Plugins register a handler via `ctx.ui.registerPageHandler()` to receive
+ * arbitrary invoke requests from their iframe-based UIs. The host acts as a
+ * transparent router — it does not inspect or interpret the action or data.
+ */
+export interface PluginUIHandler {
+    /**
+     * Called when the iframe sends an invoke request via `bridge.invoke(action, data)`.
+     *
+     * @param pageId - The page that sent the message.
+     * @param action - Developer-defined action identifier.
+     * @param data - Arbitrary payload from the iframe.
+     * @param requestContext - Host-authenticated page context, including any
+     * bound resource for this page session.
+     * @returns The response value sent back to the iframe.
+     */
+    onMessage(pageId: string, action: string, data: unknown, requestContext: PluginUIRequestContext): Promise<unknown>;
+}
+export interface PluginUIRequestUser {
+    readonly tokenId: string;
+    readonly role: 'viewer' | 'operator' | 'admin';
+    readonly operatorIds: string[];
+    readonly permissionGrants?: PermissionGrant[];
+}
+export interface PluginUIBoundResource {
+    readonly kind: 'callsign' | 'operator';
+    readonly value: string;
+}
+export type PluginUIInstanceTarget = {
+    readonly kind: 'global';
+} | {
+    readonly kind: 'operator';
+    readonly operatorId: string;
+};
+export interface PluginUIPageSessionInfo {
+    readonly sessionId: string;
+    readonly pageId: string;
+    readonly resource?: PluginUIBoundResource;
+}
+export interface PluginUIPageContext extends PluginUIPageSessionInfo {
+    push(action: string, data?: unknown): void;
+}
+export interface PluginUIRequestContext {
+    readonly pageSessionId: string;
+    readonly user: PluginUIRequestUser;
+    readonly resource?: PluginUIBoundResource;
+    readonly instanceTarget: PluginUIInstanceTarget;
+    readonly page: PluginUIPageContext;
+}
+/**
+ * Persistent binary file storage for plugins.
+ *
+ * Files are stored in a sandboxed directory under the plugin's data path. Path
+ * traversal outside the sandbox is rejected by the host.
+ */
+export interface PluginFileStore {
+    /** Writes (or overwrites) a file at the given path. */
+    write(path: string, data: Buffer): Promise<void>;
+    /** Reads a file. Returns `null` when the path does not exist. */
+    read(path: string): Promise<Buffer | null>;
+    /** Deletes a file. Returns `true` if the file existed and was removed. */
+    delete(path: string): Promise<boolean>;
+    /** Lists file paths under the given prefix (or all files when omitted). */
+    list(prefix?: string): Promise<string[]>;
 }
 //# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -25,9 +25,20 @@ export type { PluginContext } from './context.js';
 export type { PluginHooks, AutoCallProposal, AutoCallExecutionRequest, AutoCallExecutionPlan, ScoredCandidate, StrategyDecision, StrategyDecisionMeta, LastMessageInfo, } from './hooks.js';
 export type { StrategyRuntime, StrategyRuntimeContext, StrategyRuntimeSnapshot, StrategyRuntimeSlot, StrategyRuntimeSlotContentUpdate, } from './runtime.js';
 /** Host-provided helper interfaces available through {@link PluginContext}. */
-export type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, BandAccess, IdleTransmitFrequencyOptions, AutoTargetEligibilityReason, AutoTargetEligibilityDecision, UIBridge, } from './helpers.js';
+export type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, CallsignLogbookAccess, QSOQueryFilter, BandAccess, IdleTransmitFrequencyOptions, AutoTargetEligibilityReason, AutoTargetEligibilityDecision, UIBridge, PluginUIHandler, PluginUIRequestContext, PluginUIRequestUser, PluginUIBoundResource, PluginUIInstanceTarget, PluginUIPageSessionInfo, PluginUIPageContext, PluginFileStore, } from './helpers.js';
 /** Common radio/message/settings types re-exported for plugin author convenience. */
-export type { FT8Message, FT8MessageBase, FT8MessageCQ, FT8MessageCall, FT8MessageSignalReport, FT8MessageRogerReport, FT8MessageRRR, FT8MessageSeventyThree, FT8MessageFoxRR73, FT8MessageCustom, FT8MessageUnknown, ParsedFT8Message, LogbookAnalysis, SlotInfo, SlotPack, QSORecord, FrameMessage, ModeDescriptor, OperatorSlots, DxccStatus, TargetSelectionPriorityMode, PluginType, PluginPermission, PluginSettingType, PluginSettingDescriptor, PluginSettingScope, PluginQuickAction, PluginQuickSetting, PluginCapability, PluginPanelDescriptor, PluginPanelComponent, PluginSettingOption, PluginStorageScope, PluginStorageConfig, PluginManifest, PluginStatus, } from '@tx5dr/contracts';
+export type { FT8Message, FT8MessageBase, FT8MessageCQ, FT8MessageCall, FT8MessageSignalReport, FT8MessageRogerReport, FT8MessageRRR, FT8MessageSeventyThree, FT8MessageFoxRR73, FT8MessageCustom, FT8MessageUnknown, ParsedFT8Message, LogbookAnalysis, SlotInfo, SlotPack, QSORecord, FrameMessage, ModeDescriptor, OperatorSlots, DxccStatus, TargetSelectionPriorityMode, PluginType, PluginInstanceScope, PluginPermission, PluginSettingType, PluginSettingDescriptor, PluginSettingScope, PluginQuickAction, PluginQuickSetting, PluginCapability, PluginPanelDescriptor, PluginPanelComponent, PluginPanelWidth, PluginSettingOption, PluginStorageScope, PluginStorageConfig, PluginManifest, PluginStatus, PluginUIPageDescriptor, PluginUIConfig, } from '@tx5dr/contracts';
+/** Logbook sync provider interfaces. */
+export type { LogbookSyncProvider, LogbookSyncRegistrar, SyncAction, SyncTestResult, SyncUploadOptions, SyncUploadResult, SyncPreflightIssue, SyncUploadPreflightResult, SyncDownloadResult, SyncDownloadOptions, } from './sync.js';
 /** Stable runtime enum values commonly referenced by plugin implementations. */
 export { FT8MessageType } from './ft8-message-type.js';
+/** Utility functions for plugin authors. */
+export { normalizeCallsign } from './utils/callsign.js';
+/** ADIF (Amateur Data Interchange Format) utilities. */
+export { parseADIFContent, parseADIFRecord, parseADIFFields, convertQSOToADIF, generateADIFFile, formatADIFDate, formatADIFTime, parseADIFDateTime, } from './utils/adif.js';
+/** Plugin page scope path utilities. */
+export { getPluginPageScopePath, getPluginPageScopeSegments, } from './utils/page-scope.js';
+export type { PluginPageBoundResource } from './utils/page-scope.js';
+/** QSO text field utilities. */
+export { parseLegacyComment, resolveQsoComment, buildCommentFromMessageHistory, normalizeMessageHistory, } from './utils/qso-text-fields.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,uDAAuD;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,cAAc,CAAC;AAEtB,+EAA+E;AAC/E,YAAY,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACV,4BAA4B,EAC5B,2BAA2B,EAC3B,6BAA6B,EAC7B,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,qFAAqF;AACrF,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,EACV,2BAA2B,EAC3B,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,uDAAuD;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,cAAc,CAAC;AAEtB,+EAA+E;AAC/E,YAAY,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,4BAA4B,EAC5B,2BAA2B,EAC3B,6BAA6B,EAC7B,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,qFAAqF;AACrF,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,EACV,2BAA2B,EAC3B,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,wCAAwC;AACxC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAEnB,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,4CAA4C;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,wDAAwD;AACxD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,wCAAwC;AACxC,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE,gCAAgC;AAChC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,8BAA8B,EAC9B,uBAAuB,GACxB,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -21,4 +21,12 @@
  */
 /** Stable runtime enum values commonly referenced by plugin implementations. */
 export { FT8MessageType } from './ft8-message-type.js';
+/** Utility functions for plugin authors. */
+export { normalizeCallsign } from './utils/callsign.js';
+/** ADIF (Amateur Data Interchange Format) utilities. */
+export { parseADIFContent, parseADIFRecord, parseADIFFields, convertQSOToADIF, generateADIFFile, formatADIFDate, formatADIFTime, parseADIFDateTime, } from './utils/adif.js';
+/** Plugin page scope path utilities. */
+export { getPluginPageScopePath, getPluginPageScopeSegments, } from './utils/page-scope.js';
+/** QSO text field utilities. */
+export { parseLegacyComment, resolveQsoComment, buildCommentFromMessageHistory, normalizeMessageHistory, } from './utils/qso-text-fields.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA8EH,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0GH,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,4CAA4C;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,wDAAwD;AACxD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,wCAAwC;AACxC,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAG/B,gCAAgC;AAChC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,8BAA8B,EAC9B,uBAAuB,GACxB,MAAM,4BAA4B,CAAC"}