@tx5dr/plugin-api 1.0.0

package/dist/helpers.d.ts

@@ -0,0 +1,223 @@
+import type { ParsedFT8Message, SlotInfo, SlotPack, QSORecord, FrameMessage, OperatorSlots, ModeDescriptor } from '@tx5dr/contracts';
+import type { StrategyRuntimeSnapshot } from './runtime.js';
+/**
+ * Simple persistent key-value store exposed to plugins.
+ *
+ * Values are serialized by the host. Keep payloads reasonably small and prefer
+ * plain JSON-compatible data for maximum portability.
+ */
+export interface KVStore {
+    /**
+     * Reads a stored value.
+     *
+     * When the key is missing, the provided `defaultValue` is returned instead.
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Persists a value under the given key.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Removes a stored key and its value.
+     */
+    delete(key: string): void;
+    /**
+     * Returns a shallow snapshot of all stored entries in this scope.
+     */
+    getAll(): Record<string, unknown>;
+}
+/**
+ * Structured logger dedicated to a plugin instance.
+ *
+ * Messages should be concise and machine-friendly because they may appear in
+ * both backend logs and operator-facing diagnostics.
+ */
+export interface PluginLogger {
+    /** Writes a verbose diagnostic message. */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Writes a lifecycle or informational message. */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Writes a warning that does not stop plugin execution. */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Writes an error with optional structured details or an exception object. */
+    error(message: string, error?: unknown): void;
+}
+/**
+ * Host-managed named timers for plugin code.
+ */
+export interface PluginTimers {
+    /**
+     * Starts or replaces a named interval timer.
+     *
+     * When the timer fires, the host invokes {@link PluginHooks.onTimer} with the
+     * same id.
+     */
+    set(id: string, intervalMs: number): void;
+    /** Clears a named timer if it exists. */
+    clear(id: string): void;
+    /** Clears all timers owned by the current plugin instance. */
+    clearAll(): void;
+}
+/**
+ * Control surface for the active operator instance.
+ *
+ * This interface lets plugins inspect operator state and request host-managed
+ * actions such as starting automation, calling a target or notifying the UI.
+ */
+export interface OperatorControl {
+    /** Unique operator identifier used by the host. */
+    readonly id: string;
+    /** Whether this operator is currently transmitting or otherwise armed. */
+    readonly isTransmitting: boolean;
+    /** Configured callsign of the operator/station. */
+    readonly callsign: string;
+    /** Configured grid locator of the operator/station. */
+    readonly grid: string;
+    /** Current audio offset frequency in Hz within the passband. */
+    readonly frequency: number;
+    /** Active digital mode descriptor, for example FT8 or FT4. */
+    readonly mode: ModeDescriptor;
+    /** Current transmit cycle selection where `0` is even and `1` is odd. */
+    readonly transmitCycles: number[];
+    /** Current automation runtime snapshot visible to the operator UI. */
+    readonly automation: StrategyRuntimeSnapshot | null;
+    /** Enables transmission/automation for the current operator. */
+    startTransmitting(): void;
+    /** Disables transmission/automation for the current operator. */
+    stopTransmitting(): void;
+    /**
+     * Requests that the operator call the specified target station.
+     *
+     * Passing `lastMessage` helps the host preserve the triggering context.
+     */
+    call(callsign: string, lastMessage?: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    }): void;
+    /**
+     * Updates the operator's transmit cycle preference.
+     *
+     * Pass a single value or an array to support alternating or multi-cycle modes.
+     */
+    setTransmitCycles(cycles: number | number[]): void;
+    /**
+     * Checks whether this operator has previously worked the given callsign.
+     */
+    hasWorkedCallsign(callsign: string): Promise<boolean>;
+    /**
+     * Checks whether another operator with the same station identity is already
+     * working the target callsign.
+     */
+    isTargetBeingWorkedByOthers(targetCallsign: string): boolean;
+    /**
+     * Records a completed QSO through the host logbook pipeline.
+     */
+    recordQSO(record: QSORecord): void;
+    /**
+     * Pushes updated slot text content to the frontend operator view.
+     */
+    notifySlotsUpdated(slots: OperatorSlots): void;
+    /**
+     * Pushes a strategy state change notification to the frontend operator view.
+     */
+    notifyStateChanged(state: string): void;
+}
+/**
+ * Read/write access to radio state that is safe for plugins.
+ */
+export interface RadioControl {
+    /** Current tuned radio frequency in Hz. */
+    readonly frequency: number;
+    /** Human-readable current band label, for example `20m`. */
+    readonly band: string;
+    /** Whether the radio transport is currently connected. */
+    readonly isConnected: boolean;
+    /**
+     * Requests a frequency change.
+     *
+     * The host remains responsible for serializing hardware access and enforcing
+     * any safety or capability constraints.
+     */
+    setFrequency(freq: number): Promise<void>;
+}
+/**
+ * Read-only helpers backed by the station logbook.
+ */
+export interface LogbookAccess {
+    /** Checks whether the callsign has already been worked. */
+    hasWorked(callsign: string): Promise<boolean>;
+    /** Checks whether the DXCC entity has already been worked. */
+    hasWorkedDXCC(dxccEntity: string): Promise<boolean>;
+    /** Checks whether the Maidenhead grid has already been worked. */
+    hasWorkedGrid(grid: string): Promise<boolean>;
+}
+/**
+ * Optional constraints used when asking the host for a quieter transmit offset.
+ */
+export interface IdleTransmitFrequencyOptions {
+    /** Slot identifier to analyze. Defaults to the latest available slot when omitted. */
+    slotId?: string;
+    /** Inclusive lower bound in Hz within the passband. */
+    minHz?: number;
+    /** Inclusive upper bound in Hz within the passband. */
+    maxHz?: number;
+    /** Guard bandwidth in Hz to keep around occupied frequencies. */
+    guardHz?: number;
+}
+/**
+ * Reason codes returned by the host when evaluating whether a decoded target
+ * should be eligible for automatic CQ-style replies.
+ */
+export type AutoTargetEligibilityReason = 'non_cq_message' | 'plain_cq' | 'missing_callsign_identity' | 'missing_target_identity' | 'unsupported_activity_token' | 'unsupported_callback_token' | 'continent_match' | 'continent_mismatch' | 'dx_match' | 'dx_same_continent' | 'entity_match' | 'entity_mismatch' | 'unknown_modifier';
+/**
+ * Structured result returned by the host for automatic-target eligibility
+ * checks.
+ */
+export interface AutoTargetEligibilityDecision {
+    /** Whether the host would currently allow automation to react to the target. */
+    eligible: boolean;
+    /** Machine-friendly explanation of the decision. */
+    reason: AutoTargetEligibilityReason;
+    /** Directed CQ modifier/token extracted from the message, when present. */
+    modifier?: string;
+}
+/**
+ * Read-only access to the current decode environment.
+ */
+export interface BandAccess {
+    /**
+     * Returns the active CQ-like callers known in the current slot context.
+     */
+    getActiveCallers(): ParsedFT8Message[];
+    /**
+     * Returns the latest slot pack snapshot, or `null` if no slot has been
+     * processed yet.
+     */
+    getLatestSlotPack(): SlotPack | null;
+    /**
+     * Asks the host to recommend a quieter transmit audio offset for the current
+     * decode environment.
+     *
+     * Returns `null` when the host cannot evaluate the slot or when no suitable
+     * idle window is found.
+     */
+    findIdleTransmitFrequency(options?: IdleTransmitFrequencyOptions): number | null;
+    /**
+     * Evaluates whether the given decoded message is eligible for automatic
+     * target selection under the host's built-in CQ modifier rules.
+     *
+     * This lets third-party plugins reuse the same directed-CQ policy that the
+     * host applies to standard autocall and auto-reply flows.
+     */
+    evaluateAutoTargetEligibility(message: ParsedFT8Message): AutoTargetEligibilityDecision;
+}
+/**
+ * Minimal bridge for sending structured data to plugin panels in the frontend.
+ */
+export interface UIBridge {
+    /**
+     * Publishes new panel data for the given declarative panel id.
+     */
+    send(panelId: string, data: unknown): void;
+}
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,cAAc,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEnD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,mDAAmD;IACnD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,4DAA4D;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1C,yCAAyC;IACzC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,8DAA8D;IAC9D,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAEpD,gEAAgE;IAChE,iBAAiB,IAAI,IAAI,CAAC;IAE1B,iEAAiE;IACjE,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC;IAE1F;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAEnD;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD;;;OAGG;IACH,2BAA2B,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7D;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEnC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAE/C;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,8DAA8D;IAC9D,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,kEAAkE;IAClE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GACnC,gBAAgB,GAChB,UAAU,GACV,2BAA2B,GAC3B,yBAAyB,GACzB,4BAA4B,GAC5B,4BAA4B,GAC5B,iBAAiB,GACjB,oBAAoB,GACpB,UAAU,GACV,mBAAmB,GACnB,cAAc,GACd,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,2BAA2B,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,gBAAgB,IAAI,gBAAgB,EAAE,CAAC;IAEvC;;;OAGG;IACH,iBAAiB,IAAI,QAAQ,GAAG,IAAI,CAAC;IAErC;;;;;;OAMG;IACH,yBAAyB,CAAC,OAAO,CAAC,EAAE,4BAA4B,GAAG,MAAM,GAAG,IAAI,CAAC;IAEjF;;;;;;OAMG;IACH,6BAA6B,CAAC,OAAO,EAAE,gBAAgB,GAAG,6BAA6B,CAAC;CACzF;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5C"}

package/dist/helpers.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":""}

package/dist/hooks.d.ts

@@ -0,0 +1,204 @@
+import type { ParsedFT8Message, SlotInfo, QSORecord, FrameMessage } from '@tx5dr/contracts';
+import type { PluginContext } from './context.js';
+/**
+ * Candidate message plus an accumulated ranking score.
+ *
+ * The host constructs this shape before invoking
+ * {@link PluginHooks.onScoreCandidates}. Each scoring plugin may adjust the
+ * numeric `score`, then the host uses the final values to rank target stations.
+ */
+export interface ScoredCandidate extends ParsedFT8Message {
+    /**
+     * Relative desirability assigned by the scoring pipeline.
+     *
+     * Higher values are preferred. Plugins may add or subtract from the incoming
+     * score, which means scoring logic composes naturally across multiple utility
+     * plugins.
+     */
+    score: number;
+}
+/**
+ * Decision returned from {@link StrategyRuntime.decide}.
+ *
+ * The shape is intentionally extensible so future API revisions can add new
+ * control signals without breaking existing plugins.
+ */
+export interface StrategyDecision {
+    /**
+     * Requests that the host stop transmitting and leave the active QSO flow.
+     *
+     * During a late re-decision (`meta.isReDecision === true`), the host treats
+     * this as an immediate abort request for the operator's in-flight
+     * transmission. In other words, `stop: true` means both:
+     * - stop the operator's automation/runtime state; and
+     * - interrupt the operator's current audio/PTT contribution right away.
+     */
+    stop?: boolean;
+}
+/**
+ * Metadata describing why a strategy decision is being evaluated.
+ */
+export interface StrategyDecisionMeta {
+    /**
+     * Indicates that the host is re-processing a late decode during the same TX
+     * window rather than advancing to a brand-new decision cycle.
+     *
+     * Strategy runtimes can use this to avoid double-counting timeouts or other
+     * one-shot transitions.
+     */
+    isReDecision?: boolean;
+}
+/**
+ * Pairing of a received frame and its slot metadata.
+ *
+ * This is commonly passed back into strategy/runtime APIs when a plugin wants
+ * to remember which exact message triggered a target selection.
+ */
+export interface LastMessageInfo {
+    /** Original frame as received from the decoder or playback pipeline. */
+    message: FrameMessage;
+    /** Slot timing metadata for the frame. */
+    slotInfo: SlotInfo;
+}
+/**
+ * Declarative automatic-call request proposed by a utility plugin.
+ *
+ * Utility plugins should prefer returning this shape from
+ * {@link PluginHooks.onAutoCallCandidate} instead of directly invoking
+ * `ctx.operator.call(...)` inside broadcast hooks. This lets the host arbitrate
+ * between multiple simultaneous auto-call plugins in a deterministic way.
+ */
+export interface AutoCallProposal {
+    /** Target callsign that should be called next. */
+    callsign: string;
+    /** Optional arbitration priority; higher values win. */
+    priority?: number;
+    /** Optional triggering frame context used to preserve slot alignment. */
+    lastMessage?: LastMessageInfo;
+}
+/**
+ * Immutable metadata about the automatic-call proposal that won arbitration.
+ */
+export interface AutoCallExecutionRequest {
+    /** Plugin name that produced the winning proposal. */
+    sourcePluginName: string;
+    /** Target callsign chosen by the arbitration step. */
+    callsign: string;
+    /** Slot that is currently being processed when the autocall starts. */
+    slotInfo: SlotInfo;
+    /**
+     * Source receive slot that produced the accepted proposal.
+     *
+     * Execution-stage plugins should prefer this slot when they need to inspect
+     * the decode environment that triggered the autocall, such as picking a
+     * quieter transmit offset from the previous RX slot.
+     */
+    sourceSlotInfo?: SlotInfo;
+    /** Optional triggering frame context preserved from the proposal stage. */
+    lastMessage?: LastMessageInfo;
+}
+/**
+ * Host-managed execution plan for an accepted automatic-call proposal.
+ *
+ * Utility plugins may refine this plan in
+ * {@link PluginHooks.onConfigureAutoCallExecution}. The host then applies the
+ * merged plan before calling the active strategy runtime.
+ */
+export interface AutoCallExecutionPlan {
+    /**
+     * Optional transmit audio offset to apply before starting the automatic call.
+     */
+    audioFrequency?: number;
+}
+/**
+ * Hook collection implemented by a plugin.
+ *
+ * Hooks fall into three broad categories:
+ * - pipeline hooks transform candidate lists before target selection;
+ * - strategy-only hooks steer the active automation runtime;
+ * - broadcast hooks observe lifecycle events and side effects.
+ *
+ * Hooks should be quick and defensive. A misbehaving plugin can delay the whole
+ * decode pipeline, so expensive work should be throttled, cached or deferred.
+ */
+export interface PluginHooks {
+    /**
+     * Proposes an automatic call target while the operator is idle.
+     *
+     * The host collects proposals from all active utility plugins, resolves
+     * conflicts deterministically, and then triggers at most one host-managed
+     * `requestCall(...)` action for the winning proposal.
+     */
+    onAutoCallCandidate?(slotInfo: SlotInfo, messages: ParsedFT8Message[], ctx: PluginContext): AutoCallProposal | null | undefined | Promise<AutoCallProposal | null | undefined>;
+    /**
+     * Refines how an accepted automatic-call proposal should be executed.
+     *
+     * The host runs this as a utility-plugin pipeline after proposal
+     * arbitration. Each plugin receives the current execution plan and may return
+     * an updated copy. This is the preferred place to centralize execution
+     * policies such as pre-call frequency selection.
+     */
+    onConfigureAutoCallExecution?(request: AutoCallExecutionRequest, plan: AutoCallExecutionPlan, ctx: PluginContext): AutoCallExecutionPlan | null | undefined | Promise<AutoCallExecutionPlan | null | undefined>;
+    /**
+     * Filters candidate target messages before the scoring phase.
+     *
+     * The returned array feeds into the next plugin in the utility pipeline. As a
+     * safety mechanism, returning an empty array when the input was non-empty is
+     * treated by the host as an accidental full drop and may be ignored.
+     */
+    onFilterCandidates?(candidates: ParsedFT8Message[], ctx: PluginContext): ParsedFT8Message[] | Promise<ParsedFT8Message[]>;
+    /**
+     * Adjusts ranking scores for the current candidate list.
+     *
+     * Implementations typically add bonuses or penalties based on DXCC, signal
+     * quality, duplicate history or custom operator preferences.
+     */
+    onScoreCandidates?(candidates: ScoredCandidate[], ctx: PluginContext): ScoredCandidate[] | Promise<ScoredCandidate[]>;
+    /**
+     * Broadcast at the start of every slot with the slot metadata and decoded
+     * messages already associated with that slot.
+     */
+    onSlotStart?(slotInfo: SlotInfo, messages: ParsedFT8Message[], ctx: PluginContext): void;
+    /**
+     * Broadcast whenever decoded messages become available.
+     *
+     * This fires even when the operator is idle, which makes it a good place for
+     * monitoring, trigger detection and passive analytics.
+     */
+    onDecode?(messages: ParsedFT8Message[], ctx: PluginContext): void;
+    /**
+     * Broadcast when the host locks onto a target and a QSO officially starts.
+     */
+    onQSOStart?(info: {
+        targetCallsign: string;
+        grid?: string;
+    }, ctx: PluginContext): void;
+    /**
+     * Broadcast after a QSO has been completed and recorded.
+     */
+    onQSOComplete?(record: QSORecord, ctx: PluginContext): void;
+    /**
+     * Broadcast when an in-progress QSO terminates unsuccessfully.
+     */
+    onQSOFail?(info: {
+        targetCallsign: string;
+        reason: string;
+    }, ctx: PluginContext): void;
+    /**
+     * Broadcast when a named timer created through {@link PluginContext.timers}
+     * fires.
+     */
+    onTimer?(timerId: string, ctx: PluginContext): void;
+    /**
+     * Broadcast when the user clicks one of the plugin's declared quick actions.
+     */
+    onUserAction?(actionId: string, payload: unknown, ctx: PluginContext): void;
+    /**
+     * Broadcast after one or more persisted plugin settings have changed.
+     *
+     * The `changes` object contains only the updated keys and their new resolved
+     * values.
+     */
+    onConfigChange?(changes: Record<string, unknown>, ctx: PluginContext): void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

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

package/dist/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stable public development surface for TX-5DR plugins.
+ *
+ * Plugin authors should import from this package instead of reaching into
+ * internal monorepo packages. The package intentionally combines:
+ * - plugin-specific contracts such as {@link PluginDefinition};
+ * - runtime helper interfaces such as {@link PluginContext};
+ * - a curated subset of shared radio/message types re-exported from
+ *   `@tx5dr/contracts`.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * import type { PluginDefinition, PluginContext } from '@tx5dr/plugin-api';
+ * ```
+ *
+ * ```js
+ * /** @type {import('@tx5dr/plugin-api').PluginDefinition} *\/
+ * export default { ... };
+ * ```
+ */
+/** Core plugin definition and lifecycle interfaces. */
+export type { PluginDefinition } from './definition.js';
+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';
+/** 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';
+/** Stable runtime enum values commonly referenced by plugin implementations. */
+export { FT8MessageType } from './ft8-message-type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Stable public development surface for TX-5DR plugins.
+ *
+ * Plugin authors should import from this package instead of reaching into
+ * internal monorepo packages. The package intentionally combines:
+ * - plugin-specific contracts such as {@link PluginDefinition};
+ * - runtime helper interfaces such as {@link PluginContext};
+ * - a curated subset of shared radio/message types re-exported from
+ *   `@tx5dr/contracts`.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * import type { PluginDefinition, PluginContext } from '@tx5dr/plugin-api';
+ * ```
+ *
+ * ```js
+ * /** @type {import('@tx5dr/plugin-api').PluginDefinition} *\/
+ * export default { ... };
+ * ```
+ */
+/** Stable runtime enum values commonly referenced by plugin implementations. */
+export { FT8MessageType } from './ft8-message-type.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/runtime.d.ts

@@ -0,0 +1,116 @@
+import type { ParsedFT8Message, FrameMessage, SlotInfo } from '@tx5dr/contracts';
+import type { StrategyDecision, StrategyDecisionMeta } from './hooks.js';
+/**
+ * Logical FT8 transmit slot identifiers used by the built-in automation model.
+ *
+ * These labels correspond to the six sequential transmit messages in a typical
+ * FT8 QSO flow and are used for status snapshots and UI updates.
+ */
+export type StrategyRuntimeSlot = 'TX1' | 'TX2' | 'TX3' | 'TX4' | 'TX5' | 'TX6';
+/**
+ * Mutable strategy context maintained by the host/runtime pair.
+ *
+ * This object captures the operator's current conversation target and selected
+ * radio metadata. Strategy implementations can patch it incrementally through
+ * {@link StrategyRuntime.patchContext}.
+ */
+export interface StrategyRuntimeContext {
+    /** Currently selected target callsign, if any. */
+    targetCallsign?: string;
+    /** Grid locator reported by the target station, if known. */
+    targetGrid?: string;
+    /** Signal report sent to the target station. */
+    reportSent?: number;
+    /** Signal report received from the target station. */
+    reportReceived?: number;
+    /** Actual RF/audio frequency being used for the active QSO. */
+    actualFrequency?: number;
+}
+/**
+ * Serializable snapshot of the strategy runtime.
+ *
+ * The host forwards this structure to operator-facing UI so users can inspect
+ * the current automation state without coupling the UI to strategy internals.
+ */
+export interface StrategyRuntimeSnapshot {
+    /** Stable or semi-stable state identifier chosen by the strategy runtime. */
+    currentState: string;
+    /** Text currently queued or associated with each logical transmit slot. */
+    slots?: Partial<Record<StrategyRuntimeSlot, string>>;
+    /** Current conversation metadata tracked by the runtime. */
+    context?: StrategyRuntimeContext;
+    /** Optional list of user-visible next states, modes or branch hints. */
+    availableSlots?: string[];
+}
+/**
+ * Describes a slot text mutation emitted by the strategy runtime.
+ */
+export interface StrategyRuntimeSlotContentUpdate {
+    /** Logical slot whose rendered content should be updated. */
+    slot: StrategyRuntimeSlot;
+    /** Human-readable content for the slot, usually an FT8 message template. */
+    content: string;
+}
+/**
+ * Active controller for a `strategy` plugin.
+ *
+ * The host delegates core automation flow to this runtime. A strategy runtime is
+ * expected to be lightweight, synchronous where possible and deterministic with
+ * respect to the incoming slot/decode stream.
+ */
+export interface StrategyRuntime {
+    /**
+     * Re-evaluates the current automation state using the latest decoded messages.
+     *
+     * Return `{ stop: true }` to ask the host to stop transmitting. During a
+     * late re-decision (`meta.isReDecision === true`), the host also immediately
+     * aborts the operator's current live transmission contribution. Any other
+     * decision fields can be added in future API revisions, so plugins should
+     * return an object rather than a bare boolean.
+     */
+    decide(messages: ParsedFT8Message[], meta?: StrategyDecisionMeta): Promise<StrategyDecision> | StrategyDecision;
+    /**
+     * Returns the exact text that should be transmitted next, or `null` when no
+     * transmission should be queued.
+     */
+    getTransmitText(): string | null;
+    /**
+     * Requests that the runtime initiate or resume a call to a target station.
+     *
+     * The optional `lastMessage` provides the frame that triggered the call, which
+     * is useful when reacting to a specific CQ or completion signal.
+     */
+    requestCall(callsign: string, lastMessage?: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    }): void;
+    /**
+     * Produces a serializable runtime snapshot for diagnostics and UI.
+     */
+    getSnapshot(): StrategyRuntimeSnapshot;
+    /**
+     * Applies a partial update to the runtime context.
+     */
+    patchContext(patch: Partial<StrategyRuntimeContext>): void;
+    /**
+     * Switches the runtime to a specific logical transmit slot/state.
+     */
+    setState(state: StrategyRuntimeSlot): void;
+    /**
+     * Updates the human-readable content associated with a logical slot.
+     */
+    setSlotContent(update: StrategyRuntimeSlotContentUpdate): void;
+    /**
+     * Clears transient state and returns the runtime to an idle baseline.
+     *
+     * The optional `reason` is intended for logging or diagnostics only.
+     */
+    reset(reason?: string): void;
+    /**
+     * Optional notification that a transmission has just been queued by the host.
+     *
+     * Use this to mirror queued text into internal state when needed.
+     */
+    onTransmissionQueued?(transmission: string): void;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,6DAA6D;IAC7D,IAAI,EAAE,mBAAmB,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,MAAM,CACJ,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;IAEhD;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;;OAKG;IACH,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,GAC1D,IAAI,CAAC;IAER;;OAEG;IACH,WAAW,IAAI,uBAAuB,CAAC;IAEvC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAE3C;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,gCAAgC,GAAG,IAAI,CAAC;IAE/D;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;;OAIG;IACH,oBAAoB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACnD"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":""}