@qping/plugin-bus 0.1.0 → 0.3.0

package/dist/node.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Node-side plugin SDK: fluent `createPlugin()` over the v3 named-pipe message bus.
+ *
+ * Method names map to v3 routes:
+ *   initialize -> plugin.call.initialize
+ *   search     -> plugin.call.search
+ *   actions    -> plugin.call.invokeAction (dispatched by action id)
+ *   handle(name) -> plugin.call.<name>
+ *   publish    -> plugin.event.<subjectId>
+ *   hostCall   -> host.call.<method>
+ */
+import { type PluginHostEnv } from "./hostEnv.ts";
+import { type ActionDefinition } from "./actions.ts";
+export type { PluginHostEnv, PluginTheme } from "./hostEnv.ts";
+export { HostAction, Key, Modifiers, type ActionContext, type ActionDefinition, type ActionOutcome, type DetailRequest, type HostActionKind, type HostActionRequest, type Hotkey, type HotkeyKey, type HotkeyModifiers, type LocalizedText, type RunSpec, } from "./actions.ts";
+export type PluginContext = PluginHostEnv & {
+    action: string;
+    itemId: string;
+    query: string;
+};
+/** Payload of plugin.call.initialize. Host sends locale, theme, and the resolved message bag. */
+export type PluginInitializeParams = PluginHostEnv & {
+    messages: Record<string, string>;
+};
+/** Payload of plugin.call.search. */
+export type PluginSearchParams = PluginHostEnv & {
+    query: string;
+    mode: "global" | "plugin";
+};
+export type SearchIcon = {
+    kind: string;
+    value: string;
+};
+/**
+ * A search result row. Only `id`/`title`/`subtitle`/`priority`/`icon`/`actions` reach the host;
+ * any other field stays on the Node side and comes back as `context.item` when an action runs.
+ */
+export type SearchItem = {
+    id: string;
+    title: string;
+    subtitle?: string;
+    priority?: number;
+    icon?: SearchIcon;
+    /** Ids of registered actions, in display order. The first one is bound to Enter. */
+    actions?: string[];
+    [extra: string]: unknown;
+};
+export type SearchResult = {
+    items: SearchItem[];
+};
+type PluginInitializeHandler = (params: PluginInitializeParams) => unknown | Promise<unknown>;
+type PluginSearchHandler = (params: PluginSearchParams) => SearchResult | Promise<SearchResult>;
+type PluginHandler = (payload: any, context: PluginContext) => unknown | Promise<unknown>;
+export declare class Plugin {
+    #private;
+    initialize(handler: PluginInitializeHandler): this;
+    search(handler: PluginSearchHandler): this;
+    /**
+     * Registers every action this plugin offers. The list is sent to the host in the initialize
+     * response, so the host knows the ids, labels and hotkeys before any search runs; search items
+     * and the detail page then reference them by id only.
+     */
+    actions<TItem = any>(definitions: ActionDefinition<TItem>[]): this;
+    handle(action: string, handler: PluginHandler): this;
+    /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
+    publish(subjectId: string, payload?: unknown): void;
+    /** Calls a host.call.<method> capability and awaits the response.
+     *  `timeoutMs` defaults to the remaining timeout of the inbound plugin.call
+     *  (from a page `bus.call`) when inside a handler; otherwise 30s.
+     */
+    hostCall(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    /** Connects to the host pipe and begins dispatching. Must be called last. */
+    start(): Promise<void>;
+    /**
+     * Builds the v3 route map from the fluent registrations. Exposed for unit testing the mapping
+     * without connecting a pipe.
+     */
+    buildRoutes(): Record<string, (payload: any, context?: {
+        sessionId: string;
+    }) => unknown | Promise<unknown>>;
+    stop(): Promise<void>;
+}
+export declare function createPlugin(): Plugin;