/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

import { RouteHandler } from './routeHandler'
import { RouteSelector } from './routeSelector'
import { TurnState } from './turnState'

/**
 * Represents a route configuration for handling bot activities within an application.
 *
 * @typeParam TState - The type of turn state that extends TurnState, allowing for
 *                    type-safe access to custom state properties within route handlers
 *
 * @remarks
 * An AppRoute defines how incoming activities are matched and processed by combining
 * a selector function that determines when the route should be activated with a handler
 * function that processes the matched activities.
 *
 * @example
 * ```typescript
 * const echoRoute: AppRoute<MyTurnState> = {
 *   selector: (activity) => activity.type === 'message',
 *   handler: async (context, state) => {
 *     await context.sendActivity(`You said: ${context.activity.text}`);
 *   }
 * };
 * ```
 *
 */
export interface AppRoute<TState extends TurnState> {
  /**
   * The selector function used to determine if this route should handle the current activity.
   *
   * @remarks
   * This function is called for each incoming activity to determine if the route's handler
   * should be invoked. It receives the activity and returns a boolean indicating whether
   * this route should process the activity.
   */
  selector: RouteSelector;

  /**
   * The handler function that processes the activity if the selector matches.
   *
   * @remarks
   * This function contains the core logic for handling the matched activity. It receives
   * the turn context and state, allowing it to process the activity and respond appropriately.
   * The handler can be asynchronous and should return a promise that resolves when processing
   * is complete.
   */
  handler: RouteHandler<TState>;

  /**
   * Indicates whether this route is an agentic-only route.
   *
   * @default false
   *
   */
  isAgenticRoute?: boolean;

  /**
   * Indicates whether this route is an invoke route.
   *
   * @default false
   *
   * @remarks
   * Invoke routes are used for specific types of activities, such as messaging extensions,
   * adaptive card actions, or other invoke-based interactions. When set to true, this route
   * will be processed differently than regular message routes, typically with special
   * handling for invoke responses.
   *
   */
  isInvokeRoute?: boolean;

  /**
   * Optional rank of the route, used to determine the order in which routes are evaluated.
   *
   * 0 - number.MAX_VALUE. Ranks of the same value are evaluated in order of addition.
   */
  rank?: number;

  /**
   * Optional list of authorization handlers that this route requires.
   *
   * @remarks
   * If provided, the route will check for these authorization handlers before processing
   * the activity. Each string in the array should correspond to a registered authorization
   * handler name. All specified handlers must pass authorization checks before the route
   * handler is invoked.
   *
   * @example
   * ```typescript
   * authHandlers: ['oauth', 'admin-only']
   * ```
   *
   */
  authHandlers?: string[]
}