@agent-relay/sdk 2.1.5 → 2.1.6

package/dist/browser-client.d.ts

@@ -0,0 +1,212 @@
+/**
+ * BrowserRelayClient - Browser-compatible Agent Relay SDK Client
+ * @agent-relay/sdk
+ *
+ * A client designed for browser environments using WebSocket transport.
+ * Can also be used in Node.js with the WebSocket transport.
+ *
+ * Key differences from RelayClient:
+ * - Uses transport abstraction instead of direct socket access
+ * - No Node.js-specific dependencies (node:net, node:crypto)
+ * - Uses browser-compatible APIs (crypto.randomUUID, etc.)
+ */
+import type { Transport } from './transports/types.js';
+import { type AutoTransportOptions } from './transports/index.js';
+import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment } from '@agent-relay/protocol';
+export type BrowserClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
+export interface BrowserClientConfig {
+    /** Agent name */
+    agentName: string;
+    /** Entity type: 'agent' (default) or 'user' */
+    entityType?: EntityType;
+    /** CLI identifier (claude, codex, gemini, etc.) */
+    cli?: string;
+    /** Display name for human users */
+    displayName?: string;
+    /** Avatar URL for human users */
+    avatarUrl?: string;
+    /** Suppress console logging */
+    quiet?: boolean;
+    /** Auto-reconnect on disconnect */
+    reconnect?: boolean;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay (ms) */
+    reconnectDelayMs?: number;
+    /** Max reconnect delay (ms) */
+    reconnectMaxDelayMs?: number;
+    /** Transport options (WebSocket URL, socket path, etc.) */
+    transport?: AutoTransportOptions;
+    /**
+     * Pre-configured transport instance (alternative to transport options).
+     * NOTE: Auto-reconnection is NOT supported when using transportInstance.
+     * If reconnection is needed, use `transport` options instead, or handle
+     * reconnection manually by listening for state changes.
+     */
+    transportInstance?: Transport;
+}
+/**
+ * Browser-compatible request options.
+ */
+export interface BrowserRequestOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Optional structured data to include with the request */
+    data?: Record<string, unknown>;
+    /** Optional thread identifier */
+    thread?: string;
+    /** Message kind (default: 'message') */
+    kind?: PayloadKind;
+}
+/**
+ * Response from the request() method.
+ */
+export interface BrowserRequestResponse {
+    /** Sender of the response */
+    from: string;
+    /** Response body text */
+    body: string;
+    /** Optional structured data from the response */
+    data?: Record<string, unknown>;
+    /** The correlation ID used for this request/response */
+    correlationId: string;
+    /** Thread identifier if set */
+    thread?: string;
+    /** The full payload for advanced use cases */
+    payload: SendPayload;
+}
+/**
+ * BrowserRelayClient - A browser-compatible relay client.
+ *
+ * Uses WebSocket transport by default, making it compatible with browsers.
+ * Can also be used in Node.js for WebSocket-based connections.
+ *
+ * @example Browser usage
+ * ```typescript
+ * import { BrowserRelayClient } from '@agent-relay/sdk/browser';
+ *
+ * const client = new BrowserRelayClient({
+ *   agentName: 'MyAgent',
+ *   transport: {
+ *     wsUrl: 'wss://relay.example.com/ws',
+ *   },
+ * });
+ *
+ * await client.connect();
+ *
+ * client.onMessage = (from, payload) => {
+ *   console.log(`Message from ${from}: ${payload.body}`);
+ * };
+ *
+ * client.sendMessage('OtherAgent', 'Hello!');
+ * ```
+ */
+export declare class BrowserRelayClient {
+    private config;
+    private transport?;
+    private parser;
+    private _state;
+    private sessionId?;
+    private resumeToken?;
+    private reconnectAttempts;
+    private reconnectDelay;
+    private reconnectTimer?;
+    private _destroyed;
+    private dedupeCache;
+    private writeQueue;
+    private writeScheduled;
+    private pendingSyncAcks;
+    private pendingRequests;
+    onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
+    onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
+    onStateChange?: (state: BrowserClientState) => void;
+    onError?: (error: Error) => void;
+    constructor(config: BrowserClientConfig);
+    get state(): BrowserClientState;
+    get agentName(): string;
+    get currentSessionId(): string | undefined;
+    /**
+     * Connect to the relay daemon.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the relay daemon.
+     */
+    disconnect(): void;
+    /**
+     * Permanently destroy the client.
+     */
+    destroy(): void;
+    /**
+     * Send a message to another agent.
+     */
+    sendMessage(to: string, body: string, kind?: PayloadKind, data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean;
+    /**
+     * Send an ACK for a delivered message.
+     */
+    sendAck(payload: AckPayload): boolean;
+    /**
+     * Send a request to another agent and wait for their response.
+     */
+    request(to: string, body: string, options?: BrowserRequestOptions): Promise<BrowserRequestResponse>;
+    /**
+     * Respond to a request from another agent.
+     */
+    respond(correlationId: string, to: string, body: string, data?: Record<string, unknown>): boolean;
+    /**
+     * Broadcast a message to all agents.
+     */
+    broadcast(body: string, kind?: PayloadKind, data?: Record<string, unknown>): boolean;
+    /**
+     * Bind as a shadow to a primary agent.
+     */
+    bindAsShadow(primaryAgent: string, options?: {
+        speakOn?: SpeakOnTrigger[];
+        receiveIncoming?: boolean;
+        receiveOutgoing?: boolean;
+    }): boolean;
+    /**
+     * Unbind from a primary agent.
+     */
+    unbindAsShadow(primaryAgent: string): boolean;
+    /**
+     * Send log output to the daemon.
+     */
+    sendLog(data: string): boolean;
+    /**
+     * Join a channel.
+     */
+    joinChannel(channel: string, displayName?: string): boolean;
+    /**
+     * Leave a channel.
+     */
+    leaveChannel(channel: string, reason?: string): boolean;
+    /**
+     * Send a message to a channel.
+     */
+    sendChannelMessage(channel: string, body: string, options?: {
+        thread?: string;
+        mentions?: string[];
+        attachments?: MessageAttachment[];
+        data?: Record<string, unknown>;
+    }): boolean;
+    private setState;
+    private sendHello;
+    private send;
+    private flushWrites;
+    private handleData;
+    private processFrame;
+    private handleWelcome;
+    private handleDeliver;
+    private extractCorrelationId;
+    private handleChannelMessage;
+    private handleAck;
+    private handlePing;
+    private handleErrorFrame;
+    private handleDisconnect;
+    private handleError;
+    private rejectPendingSyncAcks;
+    private rejectPendingRequests;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=browser-client.d.ts.map

package/dist/browser-client.d.ts.map

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