import { ApiCallback } from '../../../common/events';
import { DependencyLifecycle } from '../../types';
import { BaselineDependency } from '../../types/service-response-store';
import { IKosDataModel } from '../kosModel';
import { FlowControlOptions } from './kos-topic-handler-flow-control';
/**
 * Extended ApiCallback that includes wildcard capture data for handlers with trailing wildcards
 *
 * @kosService core.topic-handler
 * @kosApiLevel 12
 */
export interface ApiCallbackWithWildcard<T = string> extends ApiCallback<T> {
    /**
     * @kosApiLevel 8
     */
    wildcardCapture?: Record<string, string>;
}
/**
 * Zone 3: Parses wildcard segment from topic pattern and actual topic
 * @internal - exported for testing
 */
export declare function parseWildcardSegment(pattern: string, actualTopic: string, wildcardName?: string): Record<string, string>;
/**
 * Zone 3: Checks if topic pattern has trailing wildcard
 * @internal - exported for testing
 */
export declare function checkWildcardPattern(pattern: string): boolean;
/**
 * Configuration parameters for defining a Kos topic handler function within a Kos Data Model class.
 *
 * @typeparam Response - The type of the raw response payload received from the topic.
 * @typeparam Model - The type of the Kos Data Model to which the topic handler belongs.
 * @typeparam TransformedResponse - The type of the transformed response payload after applying the transformation function.
 *
 * @kosService core.topic-handler
 * @kosApiLevel 2
 */
export interface IKosTopicHandlerParams<Response = any, Model extends IKosDataModel = any, TransformedResponse = Response> {
    /**
     * The topic or array of topics to which the handler should respond.
     */
    topic: string | string[];
    /**
     * A conditional function that determines whether the handler should be invoked based on the received payload and the Kos Data Model instance.
     * If not provided, the handler will always be invoked when a matching topic is received.
     *
     * @param payload - The transformed payload received from the topic.
     * @param model - The Kos Data Model instance to which the topic handler belongs.
     * @returns `true` if the handler should be invoked, `false` otherwise.
     */
    condition?: (payload: TransformedResponse, model: Model, raw: Response) => boolean;
    /**
     * A transformation function that converts the raw response payload into a desired format.
     * If not provided, the payload will be used as is.
     *
     * @param payload - The raw response payload received from the topic.
     * @returns The transformed payload in the desired format.
     */
    transform?: (payload: Response) => TransformedResponse;
    /**
     * Indicates whether the topic handler should listen for WebSocket messages.
     * If set to `true`, the handler will be invoked when WebSocket messages with matching topics are received.
     * Default is `false`.
     */
    websocket?: boolean;
    /**
     * @internal
     */
    fos?: boolean;
    /**
     * @internal
     */
    bridge?: boolean;
    lifecycle?: DependencyLifecycle;
    /**
     * @internal
     */
    skipParse?: boolean;
    /**
     * @kosApiLevel 6
     */
    destinationAddress?: string;
    /**
     * When true, the `destinationAddress` value is used exactly as provided
     * and the transport will NOT fall back to `connId` from query parameters
     * or kosBridge. Use this when a subscription intentionally targets
     * a specific (or empty) destination regardless of the current device context.
     * @kosApiLevel 22
     */
    explicitDestination?: boolean;
    /**
     * Debounce events - only emit after a period of inactivity
     * @example debounce: 1000 // Wait 1 second after last event
     * @example debounce: { delay: 1000, discardIntermediate: true } // Only keep last value
     * @kosApiLevel 11
     */
    debounce?: number | {
        delay: number;
        /** If true, only keeps the last value. If false (default), accumulates all values */
        discardIntermediate?: boolean;
    };
    /**
     * Throttle events - limit emissions to once per interval
     * @example throttle: 500 // At most once every 500ms
     * @example throttle: { interval: 500, discardIntermediate: true } // Only keep first value in window
     * @kosApiLevel 11
     */
    throttle?: number | {
        interval: number;
        /** If true, only keeps the first value in window. If false (default), accumulates all values */
        discardIntermediate?: boolean;
    };
    /**
     * Buffer events and emit them as an array after time window or max size
     * @kosApiLevel 11
     */
    buffer?: {
        /** Time window to collect events (ms) */
        time: number;
        /** Maximum number of events to buffer */
        maxSize?: number;
    };
    /**
     * Filter events based on a predicate function
     * Note: This operates on the raw payload before transformation
     * @kosApiLevel 11
     */
    filter?: (payload: Response) => boolean;
    /**
     * Only handle the event once, then automatically unsubscribe
     * @kosApiLevel 11
     */
    once?: boolean;
    /**
     * Replay the last N events to new handlers
     * @kosApiLevel 11
     */
    replay?: {
        /** Number of events to remember and replay */
        bufferSize: number;
    };
    /**
     * Named wildcard capture for trailing /* patterns.
     * When enabled, the portion after the /* is parsed and passed to the handler.
     * You can optionally specify a name for the captured segment.
     *
     * @example
     * ```typescript
     * @kosTopicHandler({
     *   topic: "/config/system/*",
     *   websocket: true,
     *   wildcardName: "configPath"
     * })
     * handleConfigUpdate(payload: ConfigData, raw: ApiCallbackWithWildcard<any>) {
     *   // raw.wildcardCapture.configPath contains everything after "/config/system/"
     * }
     * ```
     * @kosApiLevel 12
     */
    wildcardName?: string;
    /**
     * Advanced flow control options using async iterators internally.
     * Enables sophisticated event processing patterns like batching, backpressure,
     * on-the-fly transforms, and rate limiting.
     *
     * @example
     * ```typescript
     * @kosTopicHandler({
     *   topic: 'sensor.data',
     *   websocket: true,
     *   flow: {
     *     batch: { size: 50, window: 1000 },
     *     transform: (events) => aggregateEvents(events),
     *     backpressure: { maxConcurrent: 3 }
     *   }
     * })
     * handleProcessedEvents(aggregatedData) {
     *   // Receives transformed, batched data with backpressure control
     * }
     * ```
     * @kosApiLevel 12
     */
    flow?: FlowControlOptions<Response, TransformedResponse>;
    /**
     * Baseline dependency configuration for baseline-delta race condition handling.
     * When specified, this handler will wait for the baseline service request to complete
     * before processing events, and will intelligently replay queued events based on
     * temporal comparison with the baseline request/response timing.
     *
     * @example
     * ```typescript
     * @kosTopicHandler({
     *   topic: TOPIC_INGREDIENT_UPDATE,
     *   websocket: true,
     *   lifecycle: DependencyLifecycle.READY,
     *   requiresBaseline: {
     *     path: PATH_INGREDIENTS,
     *     method: 'get',
     *     replayStrategy: 'after-request'
     *   }
     * })
     * handleIngredientUpdate(payload: IngredientUpdatePayload) {
     *   // Framework guarantees:
     *   // 1. Baseline loaded before this handler executes
     *   // 2. Queued events replayed with temporal filtering
     *   // 3. Only events newer than baseline are processed
     * }
     * ```
     * @kosApiLevel 15
     */
    requiresBaseline?: BaselineDependency;
}
/**
 * Decorator for defining a Kos topic handler function within a Kos Data Model class.
 *
 * @param params - An object containing configuration parameters for the topic handler.
 * @returns A decorator function.
 *
 * @example Basic usage:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'temperature/update',
 *   websocket: true
 * })
 * handleTemperature(payload: TemperatureData) { }
 * ```
 *
 * @example Debounced handling:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'rapid/updates',
 *   websocket: true,
 *   debounce: 1000 // Wait 1 second after last event
 * })
 * handleRapidUpdates(payload: UpdateData) { }
 * ```
 *
 * @example Buffered batch processing:
 * ```typescript
 * @kosTopicHandler({
 *   topic: 'log/entry',
 *   websocket: true,
 *   buffer: { time: 5000, maxSize: 100 }
 * })
 * handleLogBatch(entries: LogEntry[]) { }
 * ```
 *
 * @example Trailing wildcard with custom name:
 * ```typescript
 * @kosTopicHandler({
 *   topic: '/config/system/*',
 *   websocket: true,
 *   wildcardName: 'configPath'
 * })
 * handleConfigUpdate(payload: ConfigData, raw: ApiCallbackWithWildcard<any>) {
 *   // raw.wildcardCapture.configPath = "network/timeout" (everything after "/config/system/")
 * }
 * ```
 *
 * @example Trailing wildcard with PropKeys:
 * ```typescript
 * const DEVICE_ID = createPropKey<DeviceModel>('deviceId');
 *
 * @kosTopicHandler({
 *   topic: `/devices/${DEVICE_ID}/sensors/*`,
 *   websocket: true,
 *   wildcardName: 'sensorPath'
 * })
 * handleSensorEvent(payload: SensorData, raw: ApiCallbackWithWildcard<any>) {
 *   // raw.wildcardCapture.sensorPath = "temperature/reading" (everything after device-specific prefix)
 * }
 * ```
 * @category KOS Model Decorator
 * @kosService core.topic-handler
 * @kosApiLevel 2
 */
export declare function kosTopicHandler<Response = any, Model extends IKosDataModel = any, TransformedResponse = Response>(params: IKosTopicHandlerParams<Response, Model, TransformedResponse>): (target: any, _propertyKey: string, descriptor: PropertyDescriptor) => void;
type TopicHandler<T = any> = (this: any, payload: T) => void | Promise<void>;
/**
 * Zone 2: Applies functional enhancements to handler
 *
 * @kosService core.topic-handler
 * @kosApiLevel 15
 */
export declare function applyFunctionalEnhancements<T>(handler: TopicHandler<T>, enhancements: {
    debounce?: number | {
        delay: number;
        discardIntermediate?: boolean;
    };
    throttle?: number | {
        interval: number;
        discardIntermediate?: boolean;
    };
    buffer?: {
        time: number;
        maxSize?: number;
    };
    once?: boolean;
}): TopicHandler<T>;
export {};
//# sourceMappingURL=kosTopicHandler.d.ts.map