/**
 * Voice-call observer real-time stream.
 *
 * The voice agent ("agent-engine") exposes a per-call WebSocket that emits
 * the live timeline of a call: transcripts (user + agent), emotion / empathy
 * frames, latency markers, tool invocations, navigation timing, and lifecycle
 * events (start / end / participant join / leave).
 *
 * This resource is the canonical SDK consumer for that stream. Before it
 * existed, every developer-console-style app re-implemented the loop by hand
 * — different idle thresholds, missing close-code handling for the long list
 * of voice-specific 4xxx codes (4001 unauthorized, 4003 forbidden, 4029 rate
 * limit, 4100 token expired), and inconsistent reconnect backoff.
 *
 * The implementation composes {@link createReconnectingWebSocket} with a
 * lightweight ``ObserverSSEEvent`` parser. Frames that don't deserialize or
 * lack a recognized ``type`` discriminator are dropped — the stream remains
 * forward-compatible with new event types added on the server before the SDK
 * spec snapshot picks them up.
 *
 * @see ConversationsResource.subscribeTextStream for the analogous text-stream
 *   helper.
 */
import { type ReconnectingWebSocketError, type ReconnectingWebSocketHandle, type ReconnectingWebSocketReconnectReason, type ReconnectingWebSocketState, type WebSocketFactory } from '../core/reconnecting-websocket.js';
import { type PlatformFetch } from '../core/openapi-client.js';
import type { components } from '../generated/api.js';
import { WorkspaceScopedResource } from './base.js';
/**
 * Discriminated union of every observer stream event variant. Members carry
 * their own ``type`` literal — narrow with ``switch (event.type)``.
 */
export type ObserverSSEEvent = components['schemas']['ObserverSSEEvent'];
/** Discriminator literal for {@link ObserverSSEEvent} members. */
export type ObserverSSEEventType = ObserverSSEEvent['type'];
/** Auth subprotocol pair for the observer WebSocket. */
export type ObserverAuthProtocols = readonly ['auth', string];
/** Options for {@link ObserversResource.subscribe}. */
export interface ObserverSubscribeOptions {
    /**
     * The Twilio Call SID (``CA…``) identifying the call to observe. The
     * server returns 4004 if the call is unknown — most often a race in test
     * suites where the call hasn't been registered yet.
     */
    callSid: string;
    /**
     * Bearer token for ``Sec-WebSocket-Protocol: auth, <token>``. If the
     * token contains characters that aren't valid in a WebSocket subprotocol
     * the helper throws ``ConfigurationError`` synchronously — the wire
     * protocol cannot carry it and a runtime failure mid-call would be much
     * harder to diagnose.
     */
    token: string;
    /**
     * Full observer URL override. Defaults to
     * ``${agentBaseUrl}/v1/{workspace_id}/observers/{call_sid}/ws`` with
     * ``http`` mapped to ``ws`` and ``https`` mapped to ``wss``. The override
     * must be an absolute ws/wss URL with no query string or fragment — SDK-
     * managed query params are appended by the helper.
     */
    observerUrl?: string;
    /** Cancellation signal — aborting closes the connection. */
    signal?: AbortSignal;
    /** Fired once per typed event delivered by the server. */
    onEvent: (event: ObserverSSEEvent) => void;
    /** Fired on each lifecycle transition. */
    onStateChange?: (state: ReconnectingWebSocketState) => void;
    /**
     * Fired just before each reconnect attempt with the planned delay, the
     * close code that triggered the reconnect (or ``undefined`` for the first
     * attempt after a watchdog-driven close), and a coarse ``reason``
     * (``idle_watchdog`` / ``rate_limited`` / ``transient``) for tailoring the
     * reconnect banner copy.
     */
    onReconnect?: (info: {
        attempt: number;
        delayMs: number;
        closeCode: number | undefined;
        reason: ReconnectingWebSocketReconnectReason;
    }) => void;
    /**
     * Fired exactly once on terminal failure (auth rejected, reconnect
     * budget exhausted, abort, or one of the terminal close codes 4001 /
     * 4003 / 4100 / 4403). Will not fire on ordinary disconnect-and-reconnect.
     */
    onError?: (error: ReconnectingWebSocketError) => void;
    /** Idle watchdog (ms). Defaults to 60s for voice-call streams. */
    idleTimeoutMs?: number;
    /** Initial reconnect backoff (ms). Defaults to 1000. */
    initialDelayMs?: number;
    /** Cap on reconnect backoff (ms). Defaults to 30_000. */
    maxDelayMs?: number;
    /** Reconnect budget. Defaults to 10. */
    maxReconnects?: number;
    /** Custom WebSocket factory — primarily for tests. */
    webSocketFactory?: WebSocketFactory;
}
/**
 * Build browser WebSocket subprotocols for the observer stream.
 *
 * Identical wire format to the text-stream subprotocol pair —
 * ``Sec-WebSocket-Protocol: auth, <token>`` — but exposed as its own
 * function so consumers do not have to reason about cross-resource sharing
 * and so the SDK can evolve the auth scheme independently per stream.
 *
 * @security The returned tuple contains the raw bearer token. Do not log,
 *   persist, serialize, or otherwise expose this value.
 */
export declare function observerAuthProtocols(token: string): ObserverAuthProtocols;
/**
 * Voice-call observer resource.
 *
 * @example
 * ```ts
 * const handle = client.observers.subscribe({
 *   callSid: 'CAxxx',
 *   token: bearerToken,
 *   onEvent: (event) => {
 *     switch (event.type) {
 *       case 'agent_transcript_delta':
 *         renderAgentDelta(event.text)
 *         break
 *       case 'user_transcript':
 *         renderUserTurn(event.text)
 *         break
 *       case 'session_end':
 *         showSummary(event)
 *         break
 *     }
 *   },
 *   onError: (err) => console.error('observer terminal:', err.reason),
 * })
 *
 * // Later, to stop:
 * handle.close()
 * await handle.done
 * ```
 */
export declare class ObserversResource extends WorkspaceScopedResource {
    private readonly agentBaseUrl;
    constructor(client: PlatformFetch, workspaceId: string, agentBaseUrl?: string);
    /**
     * Subscribe to the live observer stream for a call.
     *
     * Returns a {@link ReconnectingWebSocketHandle} that resolves
     * ``handle.done`` when the stream terminates (consumer-aborted, terminal
     * close code, or reconnect budget exhausted). Errors are surfaced through
     * ``onError``; the promise never rejects.
     */
    subscribe(options: ObserverSubscribeOptions): ReconnectingWebSocketHandle;
}
//# sourceMappingURL=observers.d.ts.map