/**
 * @module websocket
 *
 * WebSocket client for real-time queue message subscriptions.
 *
 * Provides both a callback-based API ({@link createQueueWebSocket}) and an
 * async iterator API ({@link subscribeToQueue}) for receiving messages from
 * a queue in real time via WebSocket.
 *
 * @example Callback-based API
 * ```typescript
 * import { createQueueWebSocket } from '@agentuity/server';
 *
 * const connection = createQueueWebSocket({
 *     queueName: 'order-processing',
 *     baseUrl: 'https://catalyst.agentuity.cloud',
 *     onMessage: (message) => {
 *         console.log('Received:', message.id, message.payload);
 *     },
 *     onOpen: () => console.log('Connected'),
 *     onClose: (code, reason) => console.log('Closed:', code, reason),
 *     onError: (error) => console.error('Error:', error),
 * });
 *
 * // Later: close the connection
 * connection.close();
 * ```
 *
 * @example Resuming from a previous session
 * ```typescript
 * import { createQueueWebSocket } from '@agentuity/server';
 *
 * // Use a previously obtained clientId and lastOffset to resume
 * const connection = createQueueWebSocket({
 *     queueName: 'order-processing',
 *     baseUrl: 'https://catalyst.agentuity.cloud',
 *     clientId: previousClientId,
 *     lastOffset: previousOffset,
 *     onMessage: (message) => {
 *         console.log('Received:', message.id, message.payload);
 *     },
 * });
 * ```
 *
 * @example Async iterator API
 * ```typescript
 * import { subscribeToQueue } from '@agentuity/server';
 *
 * const controller = new AbortController();
 * for await (const message of subscribeToQueue({
 *     queueName: 'order-processing',
 *     baseUrl: 'https://catalyst.agentuity.cloud',
 *     signal: controller.signal,
 * })) {
 *     console.log('Received:', message.id, message.payload);
 * }
 * ```
 */
import { z } from 'zod';
import type { Message } from './types.ts';
/** Connection state for a queue WebSocket connection. */
export type QueueWebSocketState = 'connecting' | 'authenticating' | 'connected' | 'reconnecting' | 'closed';
/** Options for creating a queue WebSocket subscription. */
export declare const QueueWebSocketOptionsSchema: z.ZodObject<{
    queueName: z.ZodString;
    apiKey: z.ZodOptional<z.ZodString>;
    baseUrl: z.ZodString;
    onMessage: z.ZodCustom<(message: Message) => void, (message: Message) => void>;
    onOpen: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
    onClose: z.ZodOptional<z.ZodCustom<(code: number, reason: string) => void, (code: number, reason: string) => void>>;
    onError: z.ZodOptional<z.ZodCustom<(error: Error) => void, (error: Error) => void>>;
    autoReconnect: z.ZodOptional<z.ZodBoolean>;
    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
    reconnectDelayMs: z.ZodOptional<z.ZodNumber>;
    maxReconnectDelayMs: z.ZodOptional<z.ZodNumber>;
    clientId: z.ZodOptional<z.ZodString>;
    lastOffset: z.ZodOptional<z.ZodNumber>;
    orgId: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type QueueWebSocketOptions = z.infer<typeof QueueWebSocketOptionsSchema>;
/** Return type from {@link createQueueWebSocket}. */
export interface QueueWebSocketConnection {
    /** Close the WebSocket connection. Disables auto-reconnect. */
    close(): void;
    /** The current connection state. */
    readonly state: QueueWebSocketState;
    /** The client/subscription ID assigned by the server. Stable across reconnections. */
    readonly clientId: string | undefined;
    /** The offset of the last message processed. */
    readonly lastOffset: number | undefined;
}
/** Options for the async iterator queue subscription. */
export declare const SubscribeToQueueOptionsSchema: z.ZodObject<{
    queueName: z.ZodString;
    apiKey: z.ZodOptional<z.ZodString>;
    baseUrl: z.ZodString;
    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
    clientId: z.ZodOptional<z.ZodString>;
    lastOffset: z.ZodOptional<z.ZodNumber>;
    orgId: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type SubscribeToQueueOptions = z.infer<typeof SubscribeToQueueOptionsSchema>;
/**
 * Create a WebSocket connection to receive real-time messages from a queue.
 *
 * The connection handles authentication, automatic reconnection with exponential
 * backoff, and ping/pong keep-alive (handled automatically by the WebSocket
 * implementation).
 *
 * @param options - Configuration for the WebSocket connection
 * @returns A {@link QueueWebSocketConnection} handle for managing the connection
 * @throws {QueueError} If no API key is available
 * @throws {QueueValidationError} If the queue name is invalid
 *
 * @example
 * ```typescript
 * const connection = createQueueWebSocket({
 *     queueName: 'order-processing',
 *     baseUrl: 'https://catalyst.agentuity.cloud',
 *     onMessage: (message) => {
 *         console.log('Received:', message.id, message.payload);
 *     },
 * });
 *
 * // Later: close the connection
 * connection.close();
 * ```
 */
export declare function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSocketConnection;
/**
 * Subscribe to real-time messages from a queue via WebSocket.
 *
 * Returns an async iterator that yields messages as they arrive.
 * The connection is automatically managed (auth, reconnection, cleanup).
 *
 * @param options - Configuration for the subscription
 * @returns An async generator that yields {@link Message} objects
 * @throws {QueueError} If no API key is available
 * @throws {QueueValidationError} If the queue name is invalid
 *
 * @example
 * ```typescript
 * const controller = new AbortController();
 * for await (const message of subscribeToQueue({
 *     queueName: 'order-processing',
 *     baseUrl: 'https://catalyst.agentuity.cloud',
 *     signal: controller.signal,
 * })) {
 *     console.log('Received:', message.id, message.payload);
 * }
 * ```
 */
export declare function subscribeToQueue(options: SubscribeToQueueOptions): AsyncGenerator<Message, void, unknown>;
//# sourceMappingURL=websocket.d.ts.map