/**
 * SSE (Server-Sent Events) streaming utilities for Hono.
 *
 * Provides generic helpers for creating SSE response streams
 * and a notification type aligned with JSON-RPC 2.0.
 *
 * @module
 */
import type { Context } from 'hono';
import { z } from 'zod';
import type { Logger } from '@fuzdev/fuz_util/log.js';
/**
 * Generic SSE stream controller interface.
 *
 * Transport-agnostic — works with any serializable type.
 */
export interface SseStream<T = unknown> {
    /** Send data to the client as a JSON SSE event. */
    send: (data: T) => void;
    /** Send a comment (for keep-alive pings). */
    comment: (text: string) => void;
    /** Close the stream. */
    close: () => void;
    /** Register a listener called when the stream closes (client disconnect or explicit close). */
    on_close: (fn: () => void) => void;
}
/**
 * Notification shape aligned with JSON-RPC 2.0.
 *
 * Uses `{method, params}` to match the JSON-RPC notification format.
 */
export interface SseNotification {
    /** Notification method name (e.g. 'run_created', 'host_updated'). */
    method: string;
    /** Method-specific payload. */
    params: unknown;
}
/**
 * Create an SSE response for a Hono context.
 *
 * Wraps Hono's `streamSSE` to provide a `{response, stream}` API
 * compatible with `SubscriberRegistry` push-based broadcasting.
 * The callback suspends via a promise that resolves on client disconnect
 * or explicit `close()`, keeping the stream alive for external sends.
 *
 * Uses `hono_stream.write()` directly (not `writeSSE`) to avoid
 * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
 *
 * @param log - logger for serialization and `on_close` listener errors
 * @returns object with the streaming `Response` and an `SseStream` controller
 */
export declare const create_sse_response: <T = unknown>(c: Context, log: Logger) => {
    response: Response;
    stream: SseStream<T>;
};
/** SSE comment sent on connect to flush headers through proxies. Exported for test assertions. */
export declare const SSE_CONNECTED_COMMENT = ": connected\n\n";
/** Spec for a push event — declares params schema, description, and channel. */
export interface EventSpec {
    /** Event method name, used as the JSON-RPC notification `method`. */
    method: string;
    /** Zod schema for the notification `params` payload. */
    params: z.ZodType;
    /** Human-readable description for surface output and docs. */
    description: string;
    /** Channel this event broadcasts on. Omit for cross-channel events. */
    channel?: string;
}
/**
 * Create a broadcaster that validates events in DEV mode.
 *
 * In DEV: warns on unknown methods and invalid params.
 * In production: passes through with zero overhead.
 *
 * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
 * @param event_specs - event specs to validate against
 * @param log - logger used to emit DEV warnings on unknown methods or param mismatches
 * @returns validated broadcaster wrapper (passthrough in production)
 */
export declare const create_validated_broadcaster: <T extends SseNotification>(broadcaster: {
    broadcast: (channel: string, data: T) => void;
}, event_specs: Array<EventSpec>, log: Logger) => {
    broadcast: (channel: string, data: T) => void;
};
//# sourceMappingURL=sse.d.ts.map