@qping/plugin-bus 0.1.0 → 0.3.0

package/dist/protocol.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Hand-written TypeScript protocol types for the plugin message bus v3. These MUST stay
+ * byte-for-byte aligned with the C# types in MyTools.Protocol (see the canonical fixtures in
+ * MyTools.Protocol.Test/Fixtures/*.json). The drift-prevention self-check
+ * (fixtures-selfcheck.mjs) encodes/decodes those fixtures through these types.
+ *
+ * Field names are camelCase on the wire (System.Text.Json camelCase policy on the C# side).
+ * Null fields are omitted on the wire (WhenWritingNull).
+ *
+ * Runtime constants mirror MyTools.Protocol (MessageKindWire, Routes, EndpointIds,
+ * ProtocolVersion.CurrentWire). Do not re-hardcode those strings in SDK source.
+ */
+export declare const MessageKind: {
+    readonly Request: "request";
+    readonly Response: "response";
+    readonly Event: "event";
+};
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+export declare const ErrorCode: {
+    readonly ProtocolMismatch: "ProtocolMismatch";
+    readonly HandshakeFailed: "HandshakeFailed";
+    readonly CapabilityNotDeclared: "CapabilityNotDeclared";
+    readonly CapabilityDenied: "CapabilityDenied";
+    readonly InvalidPayload: "InvalidPayload";
+    readonly MessageTooLarge: "MessageTooLarge";
+    readonly RouteNotFound: "RouteNotFound";
+    readonly RequestTimeout: "RequestTimeout";
+    readonly TooManyRequests: "TooManyRequests";
+    readonly TransportDisconnected: "TransportDisconnected";
+    readonly PluginUnavailable: "PluginUnavailable";
+    readonly InternalError: "InternalError";
+    readonly Cancelled: "Cancelled";
+    readonly RateLimited: "RateLimited";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare const ProtocolVersion = "3.0";
+export declare const EndpointIds: {
+    readonly NodeMain: "node-main";
+    readonly Host: "host";
+};
+export declare const Routes: {
+    readonly Bus: {
+        readonly Handshake: "bus.handshake";
+        readonly Ping: "bus.ping";
+        readonly Cancel: "bus.cancel";
+        readonly Subscribe: "bus.subscribe";
+        readonly Unsubscribe: "bus.unsubscribe";
+    };
+    readonly Prefix: {
+        readonly PluginCall: "plugin.call.";
+        readonly HostCall: "host.call.";
+        readonly PluginEvent: "plugin.event.";
+        readonly HostEvent: "host.event.";
+        readonly Diagnostics: "diagnostics.";
+    };
+    readonly PluginCall: {
+        readonly Initialize: "plugin.call.initialize";
+        readonly Search: "plugin.call.search";
+        readonly InvokeAction: "plugin.call.invokeAction";
+    };
+    readonly HostEvent: {
+        readonly Initialize: "host.event.initialize";
+        readonly Search: "host.event.search";
+        readonly Key: "host.event.key";
+        readonly DetailAction: "host.event.detailAction";
+        readonly LanguageChanged: "host.event.languageChanged";
+        readonly ThemeChanged: "host.event.themeChanged";
+        readonly InputActionCaptured: "host.event.inputActionCaptured";
+    };
+};
+export declare function pluginCallRoute(method: string): string;
+export declare function hostCallRoute(method: string): string;
+export declare function pluginEventRoute(subjectId: string): string;
+export interface BusError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+}
+/**
+ * The frozen Phase-1 envelope. All fields except correlationId/timeoutMs/error/payload are
+ * required; the optional ones are omitted on the wire when null.
+ */
+export interface Envelope {
+    version: string;
+    id: string;
+    correlationId?: string | null;
+    traceId: string;
+    sessionId: string;
+    pluginId: string;
+    entryId: string;
+    endpointId: string;
+    kind: MessageKind;
+    route: string;
+    timeoutMs?: number | null;
+    payload?: unknown;
+    error?: BusError | null;
+}
+/** Omit null/undefined-valued keys to match the C# WhenWritingNull behavior. */
+export declare function canonicalStringify(value: unknown): string;
+/** Parse + re-canonicalize, returning the canonical JSON string (stable key order via JSON.stringify). */
+export declare function canonicalize(json: string): string;

package/dist/protocol.mjs

@@ -1,4 +1,69 @@
 // src/protocol.ts
+var MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event"
+};
+var ErrorCode = {
+  ProtocolMismatch: "ProtocolMismatch",
+  HandshakeFailed: "HandshakeFailed",
+  CapabilityNotDeclared: "CapabilityNotDeclared",
+  CapabilityDenied: "CapabilityDenied",
+  InvalidPayload: "InvalidPayload",
+  MessageTooLarge: "MessageTooLarge",
+  RouteNotFound: "RouteNotFound",
+  RequestTimeout: "RequestTimeout",
+  TooManyRequests: "TooManyRequests",
+  TransportDisconnected: "TransportDisconnected",
+  PluginUnavailable: "PluginUnavailable",
+  InternalError: "InternalError",
+  Cancelled: "Cancelled",
+  RateLimited: "RateLimited"
+};
+var ProtocolVersion = "3.0";
+var EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host"
+};
+var Routes = {
+  Bus: {
+    Handshake: "bus.handshake",
+    Ping: "bus.ping",
+    Cancel: "bus.cancel",
+    Subscribe: "bus.subscribe",
+    Unsubscribe: "bus.unsubscribe"
+  },
+  Prefix: {
+    PluginCall: "plugin.call.",
+    HostCall: "host.call.",
+    PluginEvent: "plugin.event.",
+    HostEvent: "host.event.",
+    Diagnostics: "diagnostics."
+  },
+  PluginCall: {
+    Initialize: "plugin.call.initialize",
+    Search: "plugin.call.search",
+    InvokeAction: "plugin.call.invokeAction"
+  },
+  HostEvent: {
+    Initialize: "host.event.initialize",
+    Search: "host.event.search",
+    Key: "host.event.key",
+    DetailAction: "host.event.detailAction",
+    LanguageChanged: "host.event.languageChanged",
+    ThemeChanged: "host.event.themeChanged",
+    InputActionCaptured: "host.event.inputActionCaptured"
+  }
+};
+function pluginCallRoute(method) {
+  return method.startsWith(Routes.Prefix.PluginCall) ? method : `${Routes.Prefix.PluginCall}${method}`;
+}
+function hostCallRoute(method) {
+  return method.startsWith(Routes.Prefix.HostCall) ? method : `${Routes.Prefix.HostCall}${method}`;
+}
+function pluginEventRoute(subjectId) {
+  return subjectId.startsWith(Routes.Prefix.PluginEvent) ? subjectId : `${Routes.Prefix.PluginEvent}${subjectId}`;
+}
 function canonicalStringify(value) {
   return JSON.stringify(stripNulls(value));
 }
@@ -19,6 +84,14 @@ function canonicalize(json) {
   return canonicalStringify(JSON.parse(json));
 }
 export {
+  EndpointIds,
+  ErrorCode,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
   canonicalStringify,
-  canonicalize
+  canonicalize,
+  hostCallRoute,
+  pluginCallRoute,
+  pluginEventRoute
 };

package/dist/router.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Handler router for the Node SDK v3. Dispatches inbound plugin.call.* requests to registered
+ * handlers, auto-replies to bus.ping, and provides callHost() to invoke host.call.* capabilities
+ * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
+ */
+import { type Envelope } from "./protocol.ts";
+type Handler = (payload: unknown, context: {
+    sessionId: string;
+}) => Promise<unknown> | unknown;
+type Sender = (env: Envelope) => void;
+export declare const DefaultHostCallTimeoutMs = 30000;
+/** Remaining ms of the inbound plugin.call timeout, if currently inside a request. */
+export declare function remainingTimeoutMs(): number | undefined;
+export declare function resolveHostCallTimeoutMs(explicit?: number): number;
+export declare class HandlerRouter {
+    private handlers;
+    private pendingHostCalls;
+    private pluginId;
+    private entryId;
+    private sessionId;
+    private endpointId;
+    /** Injected transport send fn; tests can override `router.send` directly. */
+    send: Sender;
+    constructor(deps: {
+        send: Sender;
+    });
+    /** Sets the bound identity stamped on outbound messages (after handshake). */
+    setIdentity(ids: {
+        pluginId: string;
+        entryId: string;
+        sessionId: string;
+        endpointId: string;
+    }): void;
+    handle(route: string, handler: Handler): void;
+    /** Dispatches an inbound request/response. Returns once handled. */
+    dispatch(env: Envelope): Promise<void>;
+    /** Calls a host.call.* capability and resolves with the response payload. */
+    callHost(route: string, payload: unknown, timeoutMs?: number): Promise<unknown>;
+    private handleHostResponse;
+    private responseFor;
+    private errorResponseFor;
+}
+export {};

package/dist/search.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns whether every character in `pattern` occurs in `target` in the same order.
+ * Matching is case-insensitive and characters do not need to be adjacent.
+ *
+ * @example isSubsequence("gthb", "GitHub") // true
+ */
+export declare function isSubsequence(pattern: string, target: string): boolean;

package/dist/search.mjs

@@ -0,0 +1,17 @@
+// src/search.ts
+function isSubsequence(pattern, target) {
+  if (!pattern) return true;
+  if (!target) return false;
+  const needle = pattern.toLowerCase();
+  const haystack = target.toLowerCase();
+  let patternIndex = 0;
+  for (let targetIndex = 0; targetIndex < haystack.length && patternIndex < needle.length; targetIndex += 1) {
+    if (haystack[targetIndex] === needle[patternIndex]) {
+      patternIndex += 1;
+    }
+  }
+  return patternIndex === needle.length;
+}
+export {
+  isSubsequence
+};

package/dist/transport.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Node-side named-pipe transport for the v3 message bus. Connects to the host's pipe server
+ * (created by NamedPipeTransport on the C# side), runs an incremental FrameDecoder read loop,
+ * and sends length-prefixed frames. Mirrors MyTools.Host.Transports.NamedPipeTransport.
+ */
+import { type Envelope } from "./protocol.ts";
+type MessageHandler = (env: Envelope) => void;
+type DisconnectHandler = () => void;
+export declare class NodeTransport {
+    private socket;
+    private messageHandlers;
+    private disconnectHandlers;
+    private closed;
+    onMessage(handler: MessageHandler): () => void;
+    onDisconnect(handler: DisconnectHandler): void;
+    get isConnected(): boolean;
+    /** Connects to a Windows named pipe (\\.\pipe\<name>). */
+    connect(pipePath: string): Promise<void>;
+    /** Serializes an envelope to a length-prefixed frame and writes it. */
+    send(env: Envelope): void;
+    close(): Promise<void>;
+    private handleDisconnect;
+}
+export {};

package/dist/webClient.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v3 Web SDK: speaks protocol envelopes over chrome.webview.postMessage.
+ * Host stamps identity; the page does not supply plugin/entry/session ids.
+ *
+ * Connections start with bus.handshake. Subsequent plugin.call.* envelopes use the
+ * negotiated version. call("refresh") is sent as plugin.call.refresh.
+ */
+import { mytoolsI18n } from "./i18n.ts";
+import type { MyToolsThemePayload } from "./webTypes.ts";
+export { mytoolsI18n } from "./i18n.ts";
+export { renderHotkeyKeycaps } from "./hotkeyKeycaps.ts";
+export { HostEvents } from "./webTypes.ts";
+export type { MyToolsHostActionDefinition, MyToolsHostDetailActionPayload, MyToolsHostInitializePayload, MyToolsHostKeyPayload, MyToolsHostSearchPayload, MyToolsInputActionCapturedPayload, MyToolsLanguageChangedPayload, MyToolsThemeChangedPayload, MyToolsThemePayload, } from "./webTypes.ts";
+export interface WebBusClient {
+    /** Sends plugin.call.<method>. Bare names are prefixed; full routes are left as-is. */
+    call<T = unknown>(method: string, payload?: unknown, timeoutMs?: number): Promise<T>;
+    on<T = unknown>(route: string, handler: (payload: T) => void): () => void;
+    i18n: typeof mytoolsI18n;
+    theme: typeof mytoolsTheme;
+    close(): void;
+}
+declare const mytoolsTheme: {
+    current: string;
+    apply(payload: MyToolsThemePayload): void;
+};
+/**
+ * Creates a Web bus client. Registers the message listener immediately so host
+ * events that arrive before `on()` are buffered and replayed.
+ *
+ * Handshake is required before call(). Page scripts are bundled as IIFE, so this
+ * function is synchronous; handshake runs in the background and gates call().
+ */
+export declare function createWebBusClient(options?: {
+    timeoutMs?: number;
+}): WebBusClient;