@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/event-emitter.js

@@ -1 +1,461 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.XBindEventEmitter=void 0,exports.createScopedEmitter=createScopedEmitter;const shared_1=require("../_deps/shared/index.js");class XBindEventEmitter{listeners=new Map;parent;disposed=!1;eventCounter=0;maxListeners=10;warningsEnabled=!0;constructor(e){this.parent=e}on(e,t,s={}){if(this.checkDisposed(),"function"!=typeof t)throw new Error("Listener must be a function");const r=this.listeners.get(e)??[],n={listener:t,once:s.once??!1,priority:s.priority??0};return r.push(n),r.sort((e,t)=>t.priority-e.priority),this.listeners.set(e,r),this.warningsEnabled&&this.maxListeners>0&&r.length>this.maxListeners&&console.warn(`[xBind EventEmitter] Possible memory leak detected: ${r.length} listeners for event '${e}'. Use emitter.setMaxListeners() to increase limit.`),this}once(e,t,s={}){return this.on(e,t,{...s,once:!0})}off(e,t){this.checkDisposed();const s=this.listeners.get(e);if(!s)return this;const r=s.filter(e=>e.listener!==t);return 0===r.length?this.listeners.delete(e):this.listeners.set(e,r),this}removeAllListeners(e){return this.checkDisposed(),e?this.listeners.delete(e):this.listeners.clear(),this}async emit(e,t,s={}){this.checkDisposed();const r={...t,eventId:s.eventId??this.generateEventId(),timestamp:(new Date).toISOString()},n=this.listeners.get(e);if(n&&n.length>0){const t=[...n];for(const n of t)try{if(await n.listener(r),n.once&&this.off(e,n.listener),s.stopPropagation)return(0,shared_1.ok)(void 0)}catch(t){return console.error(`[xBind EventEmitter] Error in listener for '${e}':`,t),(0,shared_1.err)("LISTENER_ERROR")}}return!1!==s.bubble&&this.parent?this.parent.emit(e,t,{...s,bubble:!0}):(0,shared_1.ok)(void 0)}hasListeners(e){const t=this.listeners.get(e);return void 0!==t&&t.length>0}listenerCount(e){const t=this.listeners.get(e);return t?.length??0}eventNames(){return Array.from(this.listeners.keys())}setMaxListeners(e){if(e<0||!Number.isInteger(e))throw new Error("Max listeners must be a non-negative integer");return this.maxListeners=e,this}getMaxListeners(){return this.maxListeners}setWarningsEnabled(e){return this.warningsEnabled=e,this}setParent(e){return this.parent=e,this}getParent(){return this.parent}waitFor(e,t){return new Promise((s,r)=>{let n;const i=e=>{n&&clearTimeout(n),s(e)};this.once(e,i),void 0!==t&&t>0&&(n=setTimeout(()=>{this.off(e,i),r(new Error(`Timeout waiting for event '${e}' after ${t}ms`))},t))})}dispose(){this.disposed=!0,this.listeners.clear(),this.parent=void 0}isDisposed(){return this.disposed}checkDisposed(){if(this.disposed)throw new Error("EventEmitter has been disposed")}generateEventId(){return`evt-${Date.now()}-${++this.eventCounter}`}}function createScopedEmitter(e,t){const s=new XBindEventEmitter(e),r=new Set(t);return{on:(e,t,n)=>{if(!r.has(e))throw new Error(`Event type '${String(e)}' not allowed in scoped emitter`);return s.on(e,t,n)},once:(e,t,n)=>{if(!r.has(e))throw new Error(`Event type '${String(e)}' not allowed in scoped emitter`);return s.once(e,t,n)},off:(e,t)=>s.off(e,t),emit:(e,t,n)=>r.has(e)?s.emit(e,t,n):Promise.resolve((0,shared_1.err)("INVALID_EVENT_TYPE")),hasListeners:e=>s.hasListeners(e),listenerCount:e=>s.listenerCount(e),dispose:()=>s.dispose()}}exports.XBindEventEmitter=XBindEventEmitter;
+"use strict";
+/**
+ * @module event-emitter
+ * Type-safe event emitter for xBind agent events.
+ *
+ * Provides event-driven architecture for agent lifecycle events:
+ * - message-sent: Emitted when a message is successfully sent
+ * - message-received: Emitted when a message is received
+ * - key-rotated: Emitted when encryption keys are rotated
+ * - error: Emitted when an error occurs
+ * - connection-status: Emitted when connection state changes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XBindEventEmitter = void 0;
+exports.createScopedEmitter = createScopedEmitter;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Type-safe event emitter for xBind agent events.
+ *
+ * Features:
+ * - Type-safe event names and payloads
+ * - Listener priority support
+ * - Once listeners
+ * - Event bubbling to parent emitters
+ * - Async listener support with error handling
+ * - Memory leak detection
+ *
+ * @example
+ * ```typescript
+ * const emitter = new XBindEventEmitter();
+ *
+ * // Register listener
+ * emitter.on('message-received', (event) => {
+ *   console.log('Received from:', event.senderDid);
+ * });
+ *
+ * // Register one-time listener
+ * emitter.once('connection-status', (event) => {
+ *   console.log('Status:', event.status);
+ * });
+ *
+ * // Emit event
+ * await emitter.emit('message-received', {
+ *   type: 'message-received',
+ *   timestamp: new Date().toISOString(),
+ *   eventId: '123',
+ *   senderDid: 'did:key:z6Mk...',
+ *   message: { payload: 'Hello' },
+ *   messageId: 'msg-1',
+ *   verified: true
+ * });
+ * ```
+ */
+class XBindEventEmitter {
+    listeners = new Map();
+    parent;
+    disposed = false;
+    eventCounter = 0;
+    /** Maximum listeners per event type before warning (0 = unlimited) */
+    maxListeners = 10;
+    /** Whether warnings are enabled */
+    warningsEnabled = true;
+    /**
+     * Create a new event emitter.
+     *
+     * @param parent - Optional parent emitter for event bubbling
+     */
+    constructor(parent) {
+        this.parent = parent;
+    }
+    /**
+     * Register an event listener.
+     *
+     * @param eventType - Event type to listen for
+     * @param listener - Listener function
+     * @param options - Listener options (priority, once)
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * emitter.on('error', (event) => {
+     *   console.error('Error:', event.message);
+     * }, { priority: 10 });
+     * ```
+     */
+    on(eventType, listener, options = {}) {
+        this.checkDisposed();
+        if (typeof listener !== 'function') {
+            throw new Error('Listener must be a function');
+        }
+        const listeners = this.listeners.get(eventType) ?? [];
+        const registered = {
+            listener: listener,
+            once: options.once ?? false,
+            priority: options.priority ?? 0,
+        };
+        listeners.push(registered);
+        // Sort by priority (highest first)
+        listeners.sort((a, b) => b.priority - a.priority);
+        this.listeners.set(eventType, listeners);
+        // Check for potential memory leaks
+        if (this.warningsEnabled && this.maxListeners > 0 && listeners.length > this.maxListeners) {
+            // eslint-disable-next-line no-console
+            console.warn(`[xBind EventEmitter] Possible memory leak detected: ${listeners.length} listeners for event '${eventType}'. ` +
+                `Use emitter.setMaxListeners() to increase limit.`);
+        }
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     * Listener is automatically removed after first invocation.
+     *
+     * @param eventType - Event type to listen for
+     * @param listener - Listener function
+     * @param options - Listener options (priority)
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * emitter.once('connection-status', (event) => {
+     *   console.log('First status change:', event.status);
+     * });
+     * ```
+     */
+    once(eventType, listener, options = {}) {
+        return this.on(eventType, listener, { ...options, once: true });
+    }
+    /**
+     * Remove an event listener.
+     *
+     * @param eventType - Event type
+     * @param listener - Listener function to remove
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * const handler = (event) => console.log(event);
+     * emitter.on('error', handler);
+     * emitter.off('error', handler);
+     * ```
+     */
+    off(eventType, listener) {
+        this.checkDisposed();
+        const listeners = this.listeners.get(eventType);
+        if (!listeners)
+            return this;
+        const filtered = listeners.filter(l => l.listener !== listener);
+        if (filtered.length === 0) {
+            this.listeners.delete(eventType);
+        }
+        else {
+            this.listeners.set(eventType, filtered);
+        }
+        return this;
+    }
+    /**
+     * Remove all listeners for an event type, or all listeners if no type specified.
+     *
+     * @param eventType - Optional event type (removes all if not specified)
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * emitter.removeAllListeners('error'); // Remove all error listeners
+     * emitter.removeAllListeners(); // Remove all listeners
+     * ```
+     */
+    removeAllListeners(eventType) {
+        this.checkDisposed();
+        if (eventType) {
+            this.listeners.delete(eventType);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+    /**
+     * Emit an event to all registered listeners.
+     * Listeners are called in priority order (highest first).
+     * Async listeners are awaited in sequence.
+     *
+     * @param eventType - Event type to emit
+     * @param event - Event payload
+     * @param options - Emission options (bubble, stopPropagation)
+     * @returns Result indicating success or first error encountered
+     *
+     * @example
+     * ```typescript
+     * await emitter.emit('error', {
+     *   type: 'error',
+     *   timestamp: new Date().toISOString(),
+     *   eventId: '123',
+     *   code: 'NETWORK_ERROR',
+     *   message: 'Connection failed',
+     *   context: 'transport'
+     * });
+     * ```
+     */
+    async emit(eventType, event, options = {}) {
+        this.checkDisposed();
+        // Add standard fields if not present
+        const fullEvent = {
+            ...event,
+            eventId: options.eventId ?? this.generateEventId(),
+            timestamp: new Date().toISOString(),
+        };
+        const listeners = this.listeners.get(eventType);
+        if (listeners && listeners.length > 0) {
+            // Create a copy to avoid issues if listeners modify the array
+            const listenersCopy = [...listeners];
+            for (const registered of listenersCopy) {
+                try {
+                    await registered.listener(fullEvent);
+                    // Remove once listeners
+                    if (registered.once) {
+                        this.off(eventType, registered.listener);
+                    }
+                    // Stop propagation if requested
+                    if (options.stopPropagation) {
+                        return (0, shared_1.ok)(undefined);
+                    }
+                }
+                catch (error) {
+                    // Log error but continue with other listeners
+                    // eslint-disable-next-line no-console
+                    console.error(`[xBind EventEmitter] Error in listener for '${eventType}':`, error);
+                    // Return first error encountered
+                    return (0, shared_1.err)('LISTENER_ERROR');
+                }
+            }
+        }
+        // Bubble to parent if requested
+        if (options.bubble !== false && this.parent) {
+            return this.parent.emit(eventType, event, { ...options, bubble: true });
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+    /**
+     * Check if there are any listeners for an event type.
+     *
+     * @param eventType - Event type to check
+     * @returns True if there are listeners
+     *
+     * @example
+     * ```typescript
+     * if (emitter.hasListeners('error')) {
+     *   await emitter.emit('error', errorEvent);
+     * }
+     * ```
+     */
+    hasListeners(eventType) {
+        const listeners = this.listeners.get(eventType);
+        return listeners !== undefined && listeners.length > 0;
+    }
+    /**
+     * Get the number of listeners for an event type.
+     *
+     * @param eventType - Event type
+     * @returns Number of listeners
+     *
+     * @example
+     * ```typescript
+     * const count = emitter.listenerCount('message-received');
+     * console.log(`${count} listeners registered`);
+     * ```
+     */
+    listenerCount(eventType) {
+        const listeners = this.listeners.get(eventType);
+        return listeners?.length ?? 0;
+    }
+    /**
+     * Get all registered event types.
+     *
+     * @returns Array of event types with active listeners
+     *
+     * @example
+     * ```typescript
+     * const events = emitter.eventNames();
+     * console.log('Active events:', events);
+     * ```
+     */
+    eventNames() {
+        return Array.from(this.listeners.keys());
+    }
+    /**
+     * Set the maximum number of listeners per event before warning.
+     * Use 0 for unlimited listeners.
+     *
+     * @param n - Maximum listeners (0 = unlimited)
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * emitter.setMaxListeners(20); // Allow up to 20 listeners
+     * emitter.setMaxListeners(0);  // Unlimited
+     * ```
+     */
+    setMaxListeners(n) {
+        if (n < 0 || !Number.isInteger(n)) {
+            throw new Error('Max listeners must be a non-negative integer');
+        }
+        this.maxListeners = n;
+        return this;
+    }
+    /**
+     * Get the maximum number of listeners per event.
+     *
+     * @returns Maximum listeners (0 = unlimited)
+     */
+    getMaxListeners() {
+        return this.maxListeners;
+    }
+    /**
+     * Enable or disable memory leak warnings.
+     *
+     * @param enabled - Whether warnings are enabled
+     * @returns This emitter for chaining
+     */
+    setWarningsEnabled(enabled) {
+        this.warningsEnabled = enabled;
+        return this;
+    }
+    /**
+     * Set the parent emitter for event bubbling.
+     *
+     * @param parent - Parent emitter (undefined to remove parent)
+     * @returns This emitter for chaining
+     *
+     * @example
+     * ```typescript
+     * const parent = new XBindEventEmitter();
+     * const child = new XBindEventEmitter();
+     * child.setParent(parent);
+     *
+     * parent.on('error', (event) => console.log('Parent received:', event));
+     * await child.emit('error', errorEvent, { bubble: true });
+     * ```
+     */
+    setParent(parent) {
+        this.parent = parent;
+        return this;
+    }
+    /**
+     * Get the parent emitter.
+     *
+     * @returns Parent emitter or undefined
+     */
+    getParent() {
+        return this.parent;
+    }
+    /**
+     * Wait for a specific event to be emitted.
+     * Returns a promise that resolves with the event payload.
+     *
+     * @param eventType - Event type to wait for
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to event or rejecting on timeout
+     *
+     * @example
+     * ```typescript
+     * const event = await emitter.waitFor('connection-status', 5000);
+     * console.log('Status changed to:', event.status);
+     * ```
+     */
+    waitFor(eventType, timeout) {
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            const handler = (event) => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                resolve(event);
+            };
+            this.once(eventType, handler);
+            if (timeout !== undefined && timeout > 0) {
+                timeoutId = setTimeout(() => {
+                    this.off(eventType, handler);
+                    reject(new Error(`Timeout waiting for event '${eventType}' after ${timeout}ms`));
+                }, timeout);
+            }
+        });
+    }
+    /**
+     * Dispose the event emitter and remove all listeners.
+     * After disposal, no events can be emitted and listeners cannot be registered.
+     *
+     * @example
+     * ```typescript
+     * emitter.dispose();
+     * ```
+     */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+        this.parent = undefined;
+    }
+    /**
+     * Check if the emitter has been disposed.
+     *
+     * @returns True if disposed
+     */
+    isDisposed() {
+        return this.disposed;
+    }
+    checkDisposed() {
+        if (this.disposed) {
+            throw new Error('EventEmitter has been disposed');
+        }
+    }
+    generateEventId() {
+        return `evt-${Date.now()}-${++this.eventCounter}`;
+    }
+}
+exports.XBindEventEmitter = XBindEventEmitter;
+/**
+ * Create a scoped event emitter that only emits specific event types.
+ * Useful for isolating event channels.
+ *
+ * @param parent - Parent emitter
+ * @param allowedEvents - Array of allowed event types
+ * @returns Scoped event emitter
+ *
+ * @example
+ * ```typescript
+ * const parent = new XBindEventEmitter();
+ * const errorOnly = createScopedEmitter(parent, ['error']);
+ *
+ * errorOnly.emit('error', errorEvent); // OK
+ * errorOnly.emit('message-sent', event); // TypeScript error
+ * ```
+ */
+function createScopedEmitter(parent, allowedEvents) {
+    const emitter = new XBindEventEmitter(parent);
+    const allowedSet = new Set(allowedEvents);
+    return {
+        on: (type, listener, options) => {
+            if (!allowedSet.has(type)) {
+                throw new Error(`Event type '${String(type)}' not allowed in scoped emitter`);
+            }
+            return emitter.on(type, listener, options);
+        },
+        once: (type, listener, options) => {
+            if (!allowedSet.has(type)) {
+                throw new Error(`Event type '${String(type)}' not allowed in scoped emitter`);
+            }
+            return emitter.once(type, listener, options);
+        },
+        off: (type, listener) => {
+            return emitter.off(type, listener);
+        },
+        emit: (type, event, options) => {
+            if (!allowedSet.has(type)) {
+                return Promise.resolve((0, shared_1.err)('INVALID_EVENT_TYPE'));
+            }
+            return emitter.emit(type, event, options);
+        },
+        hasListeners: (type) => emitter.hasListeners(type),
+        listenerCount: (type) => emitter.listenerCount(type),
+        dispose: () => emitter.dispose(),
+    };
+}

package/dist-standalone/cjs/gateway-state.js

@@ -1 +1,55 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.GatewayConnectionState=void 0;class GatewayConnectionState{connections=new Map;connect(e,n){this.connections.set(e,n),"function"==typeof n.on?n.on("close",()=>{this.connections.delete(e)}):n.addEventListener&&n.addEventListener("close",()=>{this.connections.delete(e)})}isOnline(e){return this.connections.has(e)}getSocket(e){return this.connections.get(e)??null}getOnlineDids(){return Array.from(this.connections.keys())}}exports.GatewayConnectionState=GatewayConnectionState;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayConnectionState = void 0;
+/**
+ * Gateway connection state manager.
+ *
+ * Online-only model: State evaporates immediately on disconnect.
+ * No 12-hour windows, no persistent state.
+ *
+ * Note: WebSocket type is runtime-dependent (browser WebSocket or 'ws' package).
+ */
+class GatewayConnectionState {
+    connections = new Map(); // did → socket
+    /**
+     * Register agent connection.
+     *
+     * @param did - DID of the connecting agent
+     * @param socket - WebSocket connection (browser or Node.js 'ws' package)
+     */
+    connect(did, socket) {
+        this.connections.set(did, socket);
+        // Handle close event (works for both browser and Node.js ws)
+        if (typeof socket.on === 'function') {
+            // Node.js 'ws' package style
+            socket.on('close', () => {
+                this.connections.delete(did); // Immediate evaporation
+            });
+        }
+        else if (socket.addEventListener) {
+            // Browser WebSocket style
+            socket.addEventListener('close', () => {
+                this.connections.delete(did);
+            });
+        }
+    }
+    /**
+     * Check if agent is currently online.
+     */
+    isOnline(did) {
+        return this.connections.has(did);
+    }
+    /**
+     * Get WebSocket for online agent (or null if offline).
+     */
+    getSocket(did) {
+        return this.connections.get(did) ?? null;
+    }
+    /**
+     * Get all online DIDs.
+     */
+    getOnlineDids() {
+        return Array.from(this.connections.keys());
+    }
+}
+exports.GatewayConnectionState = GatewayConnectionState;

package/dist-standalone/cjs/gateway-transport.js

@@ -1 +1,120 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.GatewayTransport=void 0;const shared_1=require("../_deps/shared/index.js");class GatewayTransport{apiKey;gateway;timeoutMs;fetchFn;pollIntervalMs;handlers=[];pollTimer=null;senderDid=null;constructor(e){this.apiKey=e.apiKey,this.gateway=e.gateway.replace(/\/$/,""),this.timeoutMs=e.timeoutMs??15e3,this.fetchFn=e.fetch??globalThis.fetch.bind(globalThis),this.pollIntervalMs=e.pollIntervalMs??0}async send(e,t){const s=`${this.gateway}/gateway/deliver`;try{const t=new AbortController,a=setTimeout(()=>t.abort(),this.timeoutMs),r=await this.fetchFn(s,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.apiKey}`},body:JSON.stringify(e),signal:t.signal});return clearTimeout(a),r.ok?(0,shared_1.ok)(void 0):(0,shared_1.err)(404===r.status?"RECIPIENT_UNREACHABLE":"SEND_FAILED")}catch(e){return e instanceof DOMException&&"AbortError"===e.name?(0,shared_1.err)("TIMEOUT"):(0,shared_1.err)("NETWORK_ERROR")}}onReceive(e){this.handlers.push(e)}startPolling(e){this.senderDid=e,this.pollIntervalMs>0&&!this.pollTimer&&(this.pollTimer=setInterval(()=>{this.poll()},this.pollIntervalMs))}dispose(){this.pollTimer&&(clearInterval(this.pollTimer),this.pollTimer=null),this.handlers=[]}async poll(){if(this.senderDid)try{const e=`${this.gateway}/gateway/messages/${encodeURIComponent(this.senderDid)}`,t=await this.fetchFn(e,{headers:{Authorization:`Bearer ${this.apiKey}`}});if(!t.ok)return;const s=await t.json();for(const e of s.messages){for(const t of this.handlers)t(e.envelope);await this.fetchFn(`${this.gateway}/gateway/ack/${e.id}`,{method:"POST",headers:{Authorization:`Bearer ${this.apiKey}`}})}}catch{}}}exports.GatewayTransport=GatewayTransport;
+"use strict";
+/**
+ * Gateway transport adapter for delivering envelopes to Xail inbox users.
+ *
+ * Sends envelopes via POST /gateway/deliver on the hosted gateway API.
+ * For agent-to-agent (M2M), use HttpsTransportAdapter with direct URLs.
+ * Optionally polls for incoming messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayTransport = void 0;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Transport adapter for the Xail Gateway.
+ *
+ * Sends envelopes via POST /gateway/deliver with API key auth.
+ * Optionally polls GET /gateway/messages/:did for incoming messages.
+ */
+class GatewayTransport {
+    apiKey;
+    gateway;
+    timeoutMs;
+    fetchFn;
+    pollIntervalMs;
+    handlers = [];
+    pollTimer = null;
+    senderDid = null;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.gateway = opts.gateway.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 15_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.pollIntervalMs = opts.pollIntervalMs ?? 0;
+    }
+    /**
+     * Send a signed envelope to a recipient via the gateway.
+     * @param envelope - The signed transport envelope.
+     * @param _recipientDid - Recipient DID (already in envelope.recipient).
+     * @returns Success or transport error.
+     */
+    async send(envelope, _recipientDid) {
+        const url = `${this.gateway}/gateway/deliver`;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                return (0, shared_1.err)(response.status === 404
+                    ? 'RECIPIENT_UNREACHABLE'
+                    : 'SEND_FAILED');
+            }
+            return (0, shared_1.ok)(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return (0, shared_1.err)('TIMEOUT');
+            }
+            return (0, shared_1.err)('NETWORK_ERROR');
+        }
+    }
+    /** Register a handler for incoming envelopes. */
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Start polling for incoming messages.
+     * Must be called after Agent.create() sets the sender DID.
+     * @param did - The agent's own DID for polling.
+     */
+    startPolling(did) {
+        this.senderDid = did;
+        if (this.pollIntervalMs > 0 && !this.pollTimer) {
+            this.pollTimer = setInterval(() => void this.poll(), this.pollIntervalMs);
+        }
+    }
+    /** Shut down the transport (stop polling, clear handlers). */
+    dispose() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.handlers = [];
+    }
+    /** Poll for incoming messages and dispatch to handlers. */
+    async poll() {
+        if (!this.senderDid)
+            return;
+        try {
+            const url = `${this.gateway}/gateway/messages/${encodeURIComponent(this.senderDid)}`;
+            const res = await this.fetchFn(url, {
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+            });
+            if (!res.ok)
+                return;
+            const data = (await res.json());
+            for (const msg of data.messages) {
+                for (const handler of this.handlers) {
+                    handler(msg.envelope);
+                }
+                // Ack delivery
+                await this.fetchFn(`${this.gateway}/gateway/ack/${msg.id}`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                });
+            }
+        }
+        catch {
+            // Silent failure — polling errors are non-fatal
+        }
+    }
+}
+exports.GatewayTransport = GatewayTransport;