tywrap 0.1.2 → 0.2.1

package/dist/runtime/bridge-protocol.js

@@ -0,0 +1,247 @@
+/**
+ * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ *
+ * Combines BoundedContext + SafeCodec + Transport into a single base class
+ * that handles all cross-boundary concerns:
+ * - Lifecycle management (init/dispose state machine)
+ * - Request/response encoding with validation
+ * - Transport-agnostic message passing
+ * - Bounded execution (timeout, retry, abort)
+ *
+ * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import { BoundedContext } from './bounded-context.js';
+import { SafeCodec } from './safe-codec.js';
+import { PROTOCOL_ID } from './transport.js';
+// =============================================================================
+// BRIDGE PROTOCOL BASE CLASS
+// =============================================================================
+/**
+ * BridgeProtocol combines BoundedContext + SafeCodec + Transport
+ * into a unified abstraction for all JS<->Python communication.
+ *
+ * This class provides:
+ * - Automatic transport lifecycle management
+ * - Request encoding with guardrails (special float rejection, key validation)
+ * - Response decoding with Arrow support
+ * - Full RuntimeExecution interface implementation
+ *
+ * Subclasses should:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @example
+ * ```typescript
+ * class NodeBridge extends BridgeProtocol {
+ *   constructor(options: NodeBridgeOptions) {
+ *     const transport = new ProcessIO(options);
+ *     super({ transport, defaultTimeoutMs: options.timeout });
+ *   }
+ * }
+ * ```
+ */
+export class BridgeProtocol extends BoundedContext {
+    /** Codec instance for validation and serialization */
+    codec;
+    /** Transport instance for message passing */
+    transport;
+    /** Default timeout for operations in milliseconds */
+    defaultTimeoutMs;
+    /** Counter for generating unique request IDs */
+    requestId = 0;
+    /**
+     * Create a new BridgeProtocol instance.
+     *
+     * @param options - Configuration options including transport and codec settings
+     */
+    constructor(options) {
+        super();
+        this.codec = new SafeCodec(options.codec);
+        this.transport = options.transport;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
+        // Track the transport for automatic cleanup during dispose
+        this.trackResource(this.transport);
+    }
+    // ===========================================================================
+    // LIFECYCLE
+    // ===========================================================================
+    /**
+     * Initialize the protocol.
+     *
+     * Initializes the underlying transport. Subclasses can override this
+     * to add additional initialization logic, but must call super.doInit().
+     */
+    async doInit() {
+        await this.transport.init();
+    }
+    /**
+     * Dispose the protocol.
+     *
+     * The transport is tracked as a resource and will be disposed automatically
+     * by BoundedContext. Subclasses can override this to add additional cleanup,
+     * but should not need to dispose the transport manually.
+     */
+    async doDispose() {
+        // Transport is tracked and will be disposed by BoundedContext
+        // Subclasses can override to add additional cleanup
+    }
+    // ===========================================================================
+    // MESSAGE SENDING
+    // ===========================================================================
+    /**
+     * Send a protocol message and receive a typed response.
+     *
+     * This method:
+     * 1. Generates a unique request ID
+     * 2. Encodes the request with validation (special float rejection, etc.)
+     * 3. Sends via transport with timeout/abort support
+     * 4. Decodes and validates the response
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    async sendMessage(message, options) {
+        const fullMessage = {
+            ...message,
+            id: this.generateId(),
+            protocol: PROTOCOL_ID,
+        };
+        return this.execute(async () => {
+            // 1. Encode request (validates args)
+            const encoded = this.codec.encodeRequest(fullMessage);
+            // 2. Send via transport
+            const responseStr = await this.transport.send(encoded, options?.timeoutMs ?? this.defaultTimeoutMs, options?.signal);
+            // 3. Decode response (validates result)
+            return this.codec.decodeResponse(responseStr);
+        }, options);
+    }
+    /**
+     * Async version that uses decodeResponseAsync for Arrow support.
+     *
+     * Use this method when the response may contain encoded DataFrames,
+     * ndarrays, or other Arrow-encoded data structures.
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python with Arrow decoding applied
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    async sendMessageAsync(message, options) {
+        const fullMessage = {
+            ...message,
+            id: this.generateId(),
+            protocol: PROTOCOL_ID,
+        };
+        return this.execute(async () => {
+            // 1. Encode request (validates args)
+            const encoded = this.codec.encodeRequest(fullMessage);
+            // 2. Send via transport
+            const responseStr = await this.transport.send(encoded, options?.timeoutMs ?? this.defaultTimeoutMs, options?.signal);
+            // 3. Decode response with Arrow support
+            return this.codec.decodeResponseAsync(responseStr);
+        }, options);
+    }
+    /**
+     * Generate a unique request ID.
+     *
+     * Returns a monotonically increasing integer that ensures uniqueness
+     * within a process lifetime.
+     */
+    generateId() {
+        return ++this.requestId;
+    }
+    // ===========================================================================
+    // RUNTIME EXECUTION INTERFACE
+    // ===========================================================================
+    /**
+     * Call a Python function.
+     *
+     * @param module - Python module path (e.g., 'numpy', 'mypackage.submodule')
+     * @param functionName - Function name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The function result
+     */
+    async call(module, functionName, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'call',
+            params: {
+                module,
+                functionName,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Instantiate a Python class.
+     *
+     * @param module - Python module path containing the class
+     * @param className - Class name to instantiate
+     * @param args - Positional constructor arguments
+     * @param kwargs - Keyword constructor arguments
+     * @returns A handle to the created instance
+     */
+    async instantiate(module, className, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'instantiate',
+            params: {
+                module,
+                className,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Call a method on a Python instance.
+     *
+     * @param handle - Instance handle returned from instantiate()
+     * @param methodName - Method name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The method result
+     */
+    async callMethod(handle, methodName, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'call_method',
+            params: {
+                handle,
+                methodName,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Dispose a Python instance.
+     *
+     * Releases the instance handle on the Python side, allowing
+     * the object to be garbage collected.
+     *
+     * @param handle - Instance handle to dispose
+     */
+    async disposeInstance(handle) {
+        await this.sendMessageAsync({
+            method: 'dispose_instance',
+            params: {
+                handle,
+            },
+        });
+    }
+}
+//# sourceMappingURL=bridge-protocol.js.map

package/dist/runtime/bridge-protocol.js.map

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

package/dist/runtime/disposable.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Disposable interface for resources that need cleanup.
+ *
+ * This interface enables the BoundedContext resource tracking system
+ * to automatically dispose of owned resources when the context is disposed.
+ */
+/**
+ * Interface for resources that require explicit cleanup.
+ */
+export interface Disposable {
+    /**
+     * Release resources held by this object.
+     * This method should be idempotent (safe to call multiple times).
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Type guard to check if a value implements the Disposable interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has a dispose method
+ */
+export declare function isDisposable(value: unknown): value is Disposable;
+/**
+ * Safely dispose a value if it implements Disposable.
+ * Does nothing if the value is not disposable.
+ *
+ * @param value - The value to dispose
+ * @returns Promise that resolves when disposal is complete
+ */
+export declare function safeDispose(value: unknown): Promise<void>;
+/**
+ * Dispose multiple resources, collecting any errors.
+ * All resources will be attempted even if some fail.
+ *
+ * @param resources - Iterable of Disposable resources
+ * @returns Array of errors that occurred during disposal (empty if all succeeded)
+ */
+export declare function disposeAll(resources: Iterable<Disposable>): Promise<Error[]>;
+//# sourceMappingURL=disposable.d.ts.map

package/dist/runtime/disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../src/runtime/disposable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAYlF"}

package/dist/runtime/disposable.js

@@ -0,0 +1,49 @@
+/**
+ * Disposable interface for resources that need cleanup.
+ *
+ * This interface enables the BoundedContext resource tracking system
+ * to automatically dispose of owned resources when the context is disposed.
+ */
+/**
+ * Type guard to check if a value implements the Disposable interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has a dispose method
+ */
+export function isDisposable(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.dispose === 'function');
+}
+/**
+ * Safely dispose a value if it implements Disposable.
+ * Does nothing if the value is not disposable.
+ *
+ * @param value - The value to dispose
+ * @returns Promise that resolves when disposal is complete
+ */
+export async function safeDispose(value) {
+    if (isDisposable(value)) {
+        await value.dispose();
+    }
+}
+/**
+ * Dispose multiple resources, collecting any errors.
+ * All resources will be attempted even if some fail.
+ *
+ * @param resources - Iterable of Disposable resources
+ * @returns Array of errors that occurred during disposal (empty if all succeeded)
+ */
+export async function disposeAll(resources) {
+    const errors = [];
+    for (const resource of resources) {
+        try {
+            await resource.dispose();
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=disposable.js.map

package/dist/runtime/disposable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.js","sourceRoot":"","sources":["../../src/runtime/disposable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAQ,KAAoB,CAAC,OAAO,KAAK,UAAU,CACpD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAc;IAC9C,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,SAA+B;IAC9D,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/runtime/http-io.d.ts

@@ -0,0 +1,91 @@
+/**
+ * HTTP Transport for BridgeProtocol.
+ *
+ * Provides stateless HTTP POST-based communication with a Python server.
+ * Each request is independent - no connection state is maintained.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import type { Transport } from './transport.js';
+/**
+ * Configuration options for HttpIO transport.
+ */
+export interface HttpIOOptions {
+    /** Base URL for the Python server (e.g., 'http://localhost:8000') */
+    baseURL: string;
+    /** Additional headers to include in each request */
+    headers?: Record<string, string>;
+    /** Default timeout in milliseconds. Default: 30000 (30 seconds) */
+    defaultTimeoutMs?: number;
+}
+/**
+ * HTTP-based transport for BridgeProtocol.
+ *
+ * This transport sends protocol messages as HTTP POST requests to a Python
+ * server. It is stateless - each request is independent and the transport
+ * is always ready after construction.
+ *
+ * Features:
+ * - Stateless design (init/dispose are no-ops)
+ * - Timeout handling via AbortController
+ * - External signal support for cancellation
+ * - Proper error classification
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpIO({ baseURL: 'http://localhost:8000' });
+ * await transport.init(); // No-op but follows Transport contract
+ *
+ * const response = await transport.send(
+ *   JSON.stringify({ id: '1', type: 'call', module: 'math', functionName: 'sqrt', args: [16] }),
+ *   5000
+ * );
+ *
+ * await transport.dispose(); // Marks as disposed
+ * ```
+ */
+export declare class HttpIO implements Transport {
+    private readonly baseURL;
+    private readonly headers;
+    private readonly defaultTimeoutMs;
+    private _isDisposed;
+    constructor(options: HttpIOOptions);
+    /**
+     * Initialize the transport.
+     *
+     * HTTP is stateless, so this is a no-op. The transport is ready
+     * immediately after construction.
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the transport.
+     *
+     * Marks the transport as disposed. Subsequent send() calls will fail.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Whether the transport is ready to send messages.
+     *
+     * Returns true unless dispose() has been called.
+     */
+    get isReady(): boolean;
+    /**
+     * Send a message to the Python server and wait for the response.
+     *
+     * @param message - The JSON-encoded protocol message to send
+     * @param timeoutMs - Timeout in milliseconds (0 = no timeout, negative = use default)
+     * @param signal - Optional AbortSignal for external cancellation
+     * @returns The raw response string (JSON-encoded ProtocolResponse)
+     *
+     * @throws BridgeDisposedError if the transport has been disposed
+     * @throws BridgeTimeoutError if the operation times out or is aborted
+     * @throws BridgeExecutionError if the server returns a non-2xx status
+     * @throws BridgeProtocolError if the response cannot be read
+     */
+    send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>;
+    /**
+     * Safely read response body as text, returning empty string on failure.
+     */
+    private safeReadText;
+}
+//# sourceMappingURL=http-io.d.ts.map

package/dist/runtime/http-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-io.d.ts","sourceRoot":"","sources":["../../src/runtime/http-io.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,MAAO,YAAW,SAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,aAAa;IAclC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAMD;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAuGrF;;OAEG;YACW,YAAY;CAO3B"}

package/dist/runtime/http-io.js

@@ -0,0 +1,195 @@
+/**
+ * HTTP Transport for BridgeProtocol.
+ *
+ * Provides stateless HTTP POST-based communication with a Python server.
+ * Each request is independent - no connection state is maintained.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import { BridgeDisposedError, BridgeExecutionError, BridgeProtocolError, BridgeTimeoutError, } from './errors.js';
+// =============================================================================
+// HTTP TRANSPORT
+// =============================================================================
+/**
+ * HTTP-based transport for BridgeProtocol.
+ *
+ * This transport sends protocol messages as HTTP POST requests to a Python
+ * server. It is stateless - each request is independent and the transport
+ * is always ready after construction.
+ *
+ * Features:
+ * - Stateless design (init/dispose are no-ops)
+ * - Timeout handling via AbortController
+ * - External signal support for cancellation
+ * - Proper error classification
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpIO({ baseURL: 'http://localhost:8000' });
+ * await transport.init(); // No-op but follows Transport contract
+ *
+ * const response = await transport.send(
+ *   JSON.stringify({ id: '1', type: 'call', module: 'math', functionName: 'sqrt', args: [16] }),
+ *   5000
+ * );
+ *
+ * await transport.dispose(); // Marks as disposed
+ * ```
+ */
+export class HttpIO {
+    baseURL;
+    headers;
+    defaultTimeoutMs;
+    _isDisposed = false;
+    constructor(options) {
+        // Normalize URL - remove trailing slash
+        this.baseURL = options.baseURL.replace(/\/$/, '');
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        };
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
+    }
+    // ===========================================================================
+    // LIFECYCLE
+    // ===========================================================================
+    /**
+     * Initialize the transport.
+     *
+     * HTTP is stateless, so this is a no-op. The transport is ready
+     * immediately after construction.
+     */
+    async init() {
+        // HTTP is stateless - nothing to initialize
+    }
+    /**
+     * Dispose the transport.
+     *
+     * Marks the transport as disposed. Subsequent send() calls will fail.
+     */
+    async dispose() {
+        this._isDisposed = true;
+    }
+    /**
+     * Whether the transport is ready to send messages.
+     *
+     * Returns true unless dispose() has been called.
+     */
+    get isReady() {
+        return !this._isDisposed;
+    }
+    // ===========================================================================
+    // SEND
+    // ===========================================================================
+    /**
+     * Send a message to the Python server and wait for the response.
+     *
+     * @param message - The JSON-encoded protocol message to send
+     * @param timeoutMs - Timeout in milliseconds (0 = no timeout, negative = use default)
+     * @param signal - Optional AbortSignal for external cancellation
+     * @returns The raw response string (JSON-encoded ProtocolResponse)
+     *
+     * @throws BridgeDisposedError if the transport has been disposed
+     * @throws BridgeTimeoutError if the operation times out or is aborted
+     * @throws BridgeExecutionError if the server returns a non-2xx status
+     * @throws BridgeProtocolError if the response cannot be read
+     */
+    async send(message, timeoutMs, signal) {
+        if (this._isDisposed) {
+            throw new BridgeDisposedError('Transport has been disposed');
+        }
+        // Determine effective timeout
+        // 0 = no timeout (per interface contract), negative = use default
+        const effectiveTimeout = timeoutMs === 0 ? 0 : timeoutMs > 0 ? timeoutMs : this.defaultTimeoutMs;
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        let timeoutId;
+        // Set up timeout if enabled
+        if (effectiveTimeout > 0) {
+            timeoutId = setTimeout(() => {
+                controller.abort();
+            }, effectiveTimeout);
+        }
+        // Handle external signal - abort our controller when external aborts
+        const externalAbortHandler = () => {
+            controller.abort();
+        };
+        if (signal) {
+            // Check if already aborted
+            if (signal.aborted) {
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+                throw new BridgeTimeoutError('Operation aborted');
+            }
+            signal.addEventListener('abort', externalAbortHandler, { once: true });
+        }
+        try {
+            const response = await fetch(this.baseURL, {
+                method: 'POST',
+                headers: this.headers,
+                body: message,
+                signal: controller.signal,
+            });
+            // Handle non-2xx status codes
+            if (!response.ok) {
+                const errorBody = await this.safeReadText(response);
+                throw new BridgeExecutionError(`HTTP ${response.status}: ${errorBody || response.statusText}`, { code: `HTTP_${response.status}` });
+            }
+            // Read response body
+            const responseText = await response.text();
+            return responseText;
+        }
+        catch (error) {
+            // Handle abort errors (timeout or external signal)
+            if (error instanceof Error && error.name === 'AbortError') {
+                // Determine if it was timeout or external abort
+                if (signal?.aborted) {
+                    throw new BridgeTimeoutError('Operation aborted');
+                }
+                throw new BridgeTimeoutError(`Request timed out after ${effectiveTimeout}ms`);
+            }
+            // Re-throw bridge errors as-is
+            if (error instanceof BridgeTimeoutError ||
+                error instanceof BridgeExecutionError ||
+                error instanceof BridgeProtocolError) {
+                throw error;
+            }
+            // Wrap network errors
+            if (error instanceof TypeError) {
+                // fetch throws TypeError for network failures
+                throw new BridgeExecutionError(`Network error: ${error.message}`, { cause: error });
+            }
+            // Wrap unknown errors
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new BridgeExecutionError(`Request failed: ${errorMessage}`, {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        finally {
+            // Clean up timeout
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            // Clean up external signal listener
+            if (signal) {
+                signal.removeEventListener('abort', externalAbortHandler);
+            }
+        }
+    }
+    // ===========================================================================
+    // HELPERS
+    // ===========================================================================
+    /**
+     * Safely read response body as text, returning empty string on failure.
+     */
+    async safeReadText(response) {
+        try {
+            return await response.text();
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=http-io.js.map

package/dist/runtime/http-io.js.map

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