@bian-womp/spark-remote 0.2.82 → 0.2.83

package/lib/esm/src/transport/WebSocketConnector.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WebSocket event handlers for connection lifecycle events.
+ */
+export interface WebSocketHandlers {
+    onopen?: (ev: Event) => void;
+    onmessage?: (ev: MessageEvent) => void;
+    onerror?: (ev: Event) => void;
+    onclose?: (ev: CloseEvent) => void;
+}
+/**
+ * Parameters for establishing a WebSocket connection.
+ */
+export interface WebSocketConnectParams {
+    /**
+     * WebSocket URL (ws:// or wss://)
+     */
+    url: string;
+    /**
+     * Query parameters to append to the URL.
+     * Values are converted to strings; undefined/null values are filtered out.
+     */
+    params?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * If true, skip authentication (don't append token to URL).
+     */
+    noAuth?: boolean;
+}
+/**
+ * Generic WebSocket type that can be either browser WebSocket or Node.js WebSocket.
+ * This allows the connector to work in both environments.
+ */
+export type GenericWebSocket = WebSocket | {
+    readyState: number;
+    send(data: string | ArrayBuffer | Blob): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: Event) => void) | null;
+    onmessage: ((ev: MessageEvent) => void) | null;
+    onerror: ((ev: Event) => void) | null;
+    onclose: ((ev: CloseEvent) => void) | null;
+    on?(event: string, handler: () => void): void;
+    off?(event: string, handler: () => void): void;
+    ping?(): void;
+    terminate?(): void;
+};
+/**
+ * Interface for establishing WebSocket connections with optional authentication handling.
+ *
+ * This allows transports to delegate connection establishment to external systems
+ * that handle authentication, token refresh, and retry logic (e.g., runSocket in swan-frontend).
+ *
+ * The connector should:
+ * 1. Build the final URL with query parameters
+ * 2. Establish the WebSocket connection
+ * 3. Set up the provided event handlers
+ * 4. Return the WebSocket instance once connected
+ * 5. Handle authentication errors (e.g., 4401) and retry with refreshed tokens
+ *
+ * @param params Connection parameters (URL, query params, auth flag)
+ * @param handlers Event handlers to attach to the WebSocket
+ * @returns Promise resolving to the connected WebSocket instance
+ */
+export type WebSocketConnector = (params: WebSocketConnectParams, handlers: WebSocketHandlers) => Promise<GenericWebSocket>;
+//# sourceMappingURL=WebSocketConnector.d.ts.map

package/lib/esm/src/transport/WebSocketConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketConnector.d.ts","sourceRoot":"","sources":["../../../../src/transport/WebSocketConnector.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtE;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT;IACE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9C,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,SAAS,CAAC,IAAI,IAAI,CAAC;CACpB,CAAC;AAEN;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,iBAAiB,KACxB,OAAO,CAAC,gBAAgB,CAAC,CAAC"}

package/lib/esm/src/transport/WebSocketTransport.d.ts

@@ -1,5 +1,19 @@
 import type { Envelope } from "@bian-womp/spark-protocol";
 import type { Transport, TransportConnectOptions } from "./Transport";
+import type { WebSocketConnector } from "./WebSocketConnector";
+/**
+ * WebSocket transport connection options.
+ * Allows extensions to pass domain-specific parameters (e.g., flowId).
+ */
+export interface WebSocketTransportConnectOptions extends TransportConnectOptions {
+    /**
+     * Optional WebSocket connector for WebSocketTransport.
+     * If provided, WebSocketTransport will use this connector instead of
+     * creating WebSocket connections directly. This allows external systems
+     * to handle authentication, token refresh, and retry logic.
+     */
+    connector?: WebSocketConnector;
+}
 export declare class WebSocketTransport implements Transport {
     private ws?;
     private listeners;
@@ -12,10 +26,14 @@ export declare class WebSocketTransport implements Transport {
     private readonly PONG_TIMEOUT_MS;
     private onConnectionLost?;
     private pongHandler?;
+    private connector?;
     constructor(url: string, options?: {
         onConnectionLost?: () => void;
+        connector?: WebSocketConnector;
     });
-    connect(options?: TransportConnectOptions): Promise<void>;
+    connect(options?: WebSocketTransportConnectOptions): Promise<void>;
+    private connectWithConnector;
+    private connectDirect;
     private startHeartbeat;
     private stopHeartbeat;
     request<TReq = unknown, TRes = unknown>(msg: Envelope<TReq>): Promise<Envelope<TRes>>;

package/lib/esm/src/transport/WebSocketTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSocketTransport.d.ts","sourceRoot":"","sources":["../../../../src/transport/WebSocketTransport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAQtE,qBAAa,kBAAmB,YAAW,SAAS;IAClD,OAAO,CAAC,EAAE,CAAC,CAAY;IACvB,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,GAAG,CAAsB;IAEjC,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,gBAAgB,CAAC,CAAa;IACtC,OAAO,CAAC,WAAW,CAAC,CAAa;gBAErB,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE;IAK9D,OAAO,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8C/D,OAAO,CAAC,cAAc;IAmDtB,OAAO,CAAC,aAAa;IAgBf,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC1C,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAClB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAe1B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI;IAK/C,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAc7B"}
+{"version":3,"file":"WebSocketTransport.d.ts","sourceRoot":"","sources":["../../../../src/transport/WebSocketTransport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D;;;GAGG;AACH,MAAM,WAAW,gCACf,SAAQ,uBAAuB;IAC/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAOD,qBAAa,kBAAmB,YAAW,SAAS;IAClD,OAAO,CAAC,EAAE,CAAC,CAAY;IACvB,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,GAAG,CAAsB;IAEjC,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,gBAAgB,CAAC,CAAa;IACtC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAGrC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QACR,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;QAC9B,SAAS,CAAC,EAAE,kBAAkB,CAAC;KAChC;IAOG,OAAO,CAAC,OAAO,CAAC,EAAE,gCAAgC,GAAG,OAAO,CAAC,IAAI,CAAC;YAa1D,oBAAoB;YAkEpB,aAAa;IA+C3B,OAAO,CAAC,cAAc;IAmDtB,OAAO,CAAC,aAAa;IAgBf,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC1C,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAClB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAe1B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI;IAK/C,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAc7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bian-womp/spark-remote",
-  "version": "0.2.82",
+  "version": "0.2.83",
   "description": "Spark Remote - Remote execution engine for distributed graph processing",
   "license": "MIT",
   "type": "module",
@@ -48,8 +48,8 @@
     "typescript": "5.6.3"
   },
   "dependencies": {
-    "@bian-womp/spark-graph": "^0.2.82",
-    "@bian-womp/spark-protocol": "^0.2.82",
+    "@bian-womp/spark-graph": "^0.2.83",
+    "@bian-womp/spark-protocol": "^0.2.83",
     "ws": "^8.18.3"
   }
 }