import { type RecoilState, type RecoilValue } from 'recoil';
import { type WebSocketClientInterface } from '../../api';
import { type RequestExtras } from '../../api/http';
import { type GlobalTaskContext, type StreamVariable } from '../../types';
/**
 * Stream event types as sent from the server
 */
export type StreamEventType = 'add' | 'remove' | 'clear' | 'replace' | 'json_snapshot' | 'json_patch' | 'reconnect' | 'error';
/**
 * Stream event as received from SSE
 */
export interface StreamEvent {
    type: StreamEventType;
    data: unknown;
}
/**
 * State of a stream connection.
 * 'loading' is the initial state before first data arrives.
 */
export type StreamStatus = 'loading' | 'connected' | 'reconnecting' | 'error' | 'closed';
/**
 * Internal state for a stream variable atom
 */
export interface StreamState {
    /**
     * The accumulated data from stream events.
     * For keyed mode (key_accessor set): Record<key, item>
     * For custom mode: any shape set by snapshot/patch
     */
    data: unknown;
    /** Current connection status */
    status: StreamStatus;
    /** Error message if status is 'error' */
    error?: string;
}
/**
 * Extract a key from an item using the key_accessor path.
 *
 * @param item Item to extract key from
 * @param keyAccessor Dot-separated path to the key property (e.g., 'id' or 'data.id')
 * @returns The key value, or undefined if not found
 */
export declare function extractKey(item: unknown, keyAccessor: string): string | number | undefined;
/**
 * Apply a stream event to the current state.
 *
 * @param currentState Current accumulated state
 * @param event Stream event to apply
 * @param keyAccessor Key accessor path for keyed mode (null for custom mode)
 * @returns New state after applying the event
 */
export declare function applyStreamEvent(currentState: StreamState, event: StreamEvent, keyAccessor: string | null): StreamState;
/**
 * Get the exposed value from stream state.
 * For keyed mode, converts the internal Record to an array (values in insertion order).
 *
 * @param state Stream state
 * @param keyAccessor Key accessor (null for custom mode)
 * @returns The value to expose to components
 */
export declare function getStreamValue(state: StreamState, keyAccessor: string | null): unknown;
/**
 * Calculate exponential backoff delay.
 */
export declare function getBackoffDelay(retryCount: number): number;
/**
 * Parameters for stream atom, serialized as JSON string for atom key.
 * Contains everything needed to start the SSE connection.
 */
export interface StreamAtomParams {
    /** StreamVariable uid */
    uid: string;
    /** Resolved dependency values to send to server */
    resolvedValues: unknown[];
    /** Original variables array (for normalization) */
    variables: unknown[];
    /** Key accessor for keyed mode */
    keyAccessor: string | null;
    /** Request extras (headers, etc.) */
    extras: RequestExtras;
}
export declare function serializeAtomParams(params: StreamAtomParams): string;
export declare function deserializeAtomParams(key: string): StreamAtomParams;
/**
 * Callback interface for stream connection events.
 */
interface StreamConnectionCallbacks {
    /** Called when first data arrives - resolves the initial Promise */
    onFirstData: (state: StreamState) => void;
    /** Called for subsequent data updates */
    onUpdate: (state: StreamState) => void;
    /** Called on error after max retries */
    onError: (error: string) => void;
}
/**
 * Start an SSE connection for a stream variable.
 *
 * @param params Stream atom params (contains uid, resolved values, etc.)
 * @param callbacks Callbacks for stream events
 * @returns Object with cleanup function and AbortController
 */
declare function startStreamConnection(params: StreamAtomParams, callbacks: StreamConnectionCallbacks): {
    cleanup: () => void;
    controller: AbortController;
};
/**
 * Get or create a stream variable atom for the given params.
 * The atom has effects that manage the SSE connection lifecycle.
 * Uses Recoil's atomFamily internal caching - no external registry needed.
 *
 * @param atomKey Serialized StreamAtomParams
 * @returns Recoil atom for stream state
 */
export declare function getOrCreateStreamVariableAtom(atomKey: string): RecoilState<StreamState>;
/**
 * Get or register selector for a StreamVariable.
 * Handles nested resolution if 'nested' is set.
 *
 * Layer 3 of 3.
 *
 * @param variable StreamVariable definition
 * @param client WebSocket client (for resolving dependencies)
 * @param taskContext Global task context
 * @param extras Request extras
 * @returns Recoil selector that resolves to the stream value
 */
export declare function getOrRegisterStreamVariable(variable: StreamVariable, client: WebSocketClientInterface, taskContext: GlobalTaskContext, extras: RequestExtras): RecoilValue<unknown>;
/**
 * Internal exports for testing
 */
export declare const _internal: {
    streamAtomFamily: (param: string) => RecoilState<StreamState>;
    getBackoffDelay: typeof getBackoffDelay;
    serializeAtomParams: typeof serializeAtomParams;
    deserializeAtomParams: typeof deserializeAtomParams;
    startStreamConnection: typeof startStreamConnection;
};
export {};
//# sourceMappingURL=stream-variable.d.ts.map