import type { Duration } from 'aws-cdk-lib';
import type * as lambda from 'aws-cdk-lib/aws-lambda';
/**
 * HTTP methods supported by API Gateway integration.
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
/**
 * Authentication types for HTTP endpoints (string convenience mode).
 *
 * Maps to appropriate CDK authorizer configurations:
 * - `none`: No authentication required
 * - `jwt`: JWT token validation (Cognito User Pools or custom)
 * - `iam`: AWS IAM signature validation
 * - `cognito`: Cognito User Pool authorizer
 * - `custom`: Custom Lambda authorizer
 *
 * For full configuration options, use {@link AuthConfig} object instead.
 */
export type AuthType = 'none' | 'jwt' | 'iam' | 'cognito' | 'custom';
/**
 * No authentication configuration.
 *
 * Use this to explicitly disable authentication for a route,
 * especially when a default authorizer is configured at the API level.
 *
 * @example
 * ```typescript
 * http: {
 *   method: 'GET',
 *   path: '/api/health',
 *   auth: { type: 'none' }  // Public endpoint
 * }
 * ```
 */
export interface AuthConfigNone {
    /** Discriminant property for type narrowing */
    type: 'none';
}
/**
 * IAM authorization configuration.
 *
 * Requires AWS IAM signature validation for requests.
 * Ideal for service-to-service calls within AWS.
 *
 * @example
 * ```typescript
 * http: {
 *   method: 'POST',
 *   path: '/api/internal/process',
 *   auth: { type: 'iam', name: 'InternalApiAuth' }
 * }
 * ```
 */
export interface AuthConfigIam {
    /** Discriminant property for type narrowing */
    type: 'iam';
    /** Optional name for the authorizer */
    name?: string;
}
/**
 * JWT authorization configuration.
 *
 * Validates JWT tokens from any OIDC-compliant identity provider.
 * Requires the issuer URL; audience validation is optional but recommended.
 *
 * @example
 * ```typescript
 * http: {
 *   method: 'GET',
 *   path: '/api/users',
 *   auth: {
 *     type: 'jwt',
 *     issuer: 'https://auth.example.com',
 *     audience: ['api.example.com'],
 *     identitySource: ['$request.header.Authorization']
 *   }
 * }
 * ```
 */
export interface AuthConfigJwt {
    /** Discriminant property for type narrowing */
    type: 'jwt';
    /** Optional name for the authorizer */
    name?: string;
    /**
     * JWT issuer URL (required).
     *
     * The URL of the identity provider that issues JWT tokens.
     * Must be a valid HTTPS URL for OIDC-compliant providers.
     *
     * @example 'https://auth.example.com'
     * @example 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx'
     */
    issuer: string;
    /**
     * Allowed audience values (optional but recommended).
     *
     * The audience claim(s) that must be present in the JWT token.
     * If provided, tokens without matching audience will be rejected.
     *
     * @example ['api.example.com']
     * @example ['client-id-1', 'client-id-2']
     */
    audience?: string[];
    /**
     * Identity sources for the token.
     *
     * Specifies where to extract the JWT token from the request.
     *
     * @default ['$request.header.Authorization']
     *
     * @example ['$request.header.Authorization']
     * @example ['$request.header.X-Custom-Auth']
     */
    identitySource?: string[];
}
/**
 * Cognito authorization configuration.
 *
 * Fast integration with Amazon Cognito User Pools.
 * Implemented as a JWT authorizer with Cognito-specific issuer.
 *
 * Provide either:
 * - `userPoolId` + `region` (issuer will be derived automatically)
 * - Explicit `issuer` URL
 *
 * @example Using userPoolId and region
 * ```typescript
 * http: {
 *   method: 'GET',
 *   path: '/api/profile',
 *   auth: {
 *     type: 'cognito',
 *     userPoolId: 'us-east-1_xxxxx',
 *     region: 'us-east-1',
 *     userPoolClientIds: ['client-id-1']
 *   }
 * }
 * ```
 *
 * @example Using explicit issuer
 * ```typescript
 * http: {
 *   method: 'GET',
 *   path: '/api/profile',
 *   auth: {
 *     type: 'cognito',
 *     issuer: 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx',
 *     audience: ['client-id-1']
 *   }
 * }
 * ```
 */
export interface AuthConfigCognito {
    /** Discriminant property for type narrowing */
    type: 'cognito';
    /** Optional name for the authorizer */
    name?: string;
    /**
     * Cognito User Pool ID.
     *
     * Used with `region` to derive the issuer URL automatically.
     * Format: `{region}_{poolId}` (e.g., 'us-east-1_xxxxx')
     */
    userPoolId?: string;
    /**
     * AWS region for the User Pool.
     *
     * Used with `userPoolId` to derive the issuer URL.
     * Must match the region where the User Pool is deployed.
     */
    region?: string;
    /**
     * Explicit issuer URL.
     *
     * Alternative to `userPoolId` + `region`.
     * Format: `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`
     */
    issuer?: string;
    /**
     * User Pool App Client IDs for audience validation.
     *
     * The client IDs that are allowed to access this API.
     * Maps to the `audience` property of the JWT authorizer.
     */
    userPoolClientIds?: string[];
    /**
     * Explicit audience values.
     *
     * Alternative to `userPoolClientIds` for audience validation.
     */
    audience?: string[];
}
/**
 * Custom Lambda authorizer configuration.
 *
 * Implements custom authentication logic via a Lambda function.
 * Supports both simple (boolean) and IAM policy response formats.
 *
 * @example
 * ```typescript
 * http: {
 *   method: 'POST',
 *   path: '/api/admin/action',
 *   auth: {
 *     type: 'custom',
 *     authorizerLambda: myAuthorizerFunction,
 *     enableSimpleResponses: true,
 *     resultsCacheTtl: Duration.minutes(5),
 *     identitySource: ['$request.header.Authorization']
 *   }
 * }
 * ```
 */
export interface AuthConfigCustom {
    /** Discriminant property for type narrowing */
    type: 'custom';
    /** Optional name for the authorizer */
    name?: string;
    /**
     * Lambda function for authorization (required).
     *
     * The Lambda function that implements the authorization logic.
     * Must return either a simple boolean or an IAM policy document.
     */
    authorizerLambda: lambda.IFunction;
    /**
     * Identity sources for the authorization request.
     *
     * Specifies which request elements to pass to the authorizer.
     *
     * @default ['$request.header.Authorization']
     *
     * @example ['$request.header.Authorization']
     * @example ['$request.header.X-Api-Key', '$context.identity.sourceIp']
     */
    identitySource?: string[];
    /**
     * Enable simple boolean responses.
     *
     * When true, the authorizer Lambda can return a simple boolean
     * instead of a full IAM policy document.
     *
     * @default false
     */
    enableSimpleResponses?: boolean;
    /**
     * Cache TTL for authorization results.
     *
     * How long to cache the authorization decision for the same identity source.
     * Set to Duration.seconds(0) to disable caching.
     */
    resultsCacheTtl?: Duration;
    /**
     * Payload format version.
     *
     * Must be '2.0' for HTTP APIs (API Gateway v2).
     *
     * @default '2.0'
     */
    payloadVersion?: '2.0';
}
/**
 * Discriminated union of all authorization configurations.
 *
 * Use this type for detailed authorization configuration.
 * The `type` property serves as the discriminant for type narrowing.
 *
 * @example Type narrowing
 * ```typescript
 * function processAuth(auth: AuthConfig) {
 *   switch (auth.type) {
 *     case 'none':
 *       // auth is AuthConfigNone
 *       break;
 *     case 'jwt':
 *       // auth is AuthConfigJwt, auth.issuer is available
 *       console.log(auth.issuer);
 *       break;
 *     case 'cognito':
 *       // auth is AuthConfigCognito
 *       break;
 *     case 'custom':
 *       // auth is AuthConfigCustom, auth.authorizerLambda is available
 *       break;
 *   }
 * }
 * ```
 */
export type AuthConfig = AuthConfigNone | AuthConfigIam | AuthConfigJwt | AuthConfigCognito | AuthConfigCustom;
/**
 * CORS configuration for HTTP endpoints.
 *
 * Provides fine-grained control over Cross-Origin Resource Sharing settings.
 * Used when cors: true and corsConfig is provided in HttpIntegration.
 */
export interface CorsConfig {
    /**
     * Allowed origins for CORS requests.
     *
     * **Examples**:
     * - `['*']`: Allow all origins (development only)
     * - `['https://myapp.com']`: Specific domain
     * - `['https://myapp.com', 'https://staging.myapp.com']`: Multiple domains
     *
     * @default ['*'] in dev, specific domains in staging/prod
     */
    allowOrigins?: string[];
    /**
     * Allowed HTTP methods for CORS requests.
     *
     * **Examples**:
     * - `['GET', 'POST']`: Specific methods
     * - `['*']`: All methods
     *
     * @default All methods used by registered Lambda endpoints
     */
    allowMethods?: HttpMethod[] | ['*'];
    /**
     * Allowed headers for CORS requests.
     *
     * **Common headers**:
     * - `Content-Type`: For JSON/form data
     * - `Authorization`: For auth tokens
     * - `X-Requested-With`: For AJAX requests
     *
     * @default ['Content-Type', 'Authorization', 'X-Requested-With']
     */
    allowHeaders?: string[];
    /**
     * Whether to allow credentials (cookies, auth headers) in CORS requests.
     *
     * **Important**: Cannot be true when allowOrigins includes '*'
     *
     * @default false
     */
    allowCredentials?: boolean;
    /**
     * Maximum age (seconds) for CORS preflight cache.
     *
     * How long browsers can cache the CORS preflight response.
     *
     * @default 86400 (24 hours)
     */
    maxAge?: number;
    /**
     * Headers exposed to the client in CORS responses.
     *
     * **Common exposed headers**:
     * - `X-Request-ID`: For request tracking
     * - `X-RateLimit-*`: For rate limiting info
     *
     * @default []
     */
    exposeHeaders?: string[];
}
/**
 * HTTP integration configuration for Lambda endpoints.
 *
 * Defines how a Lambda function is exposed as an HTTP endpoint through
 * API Gateway. Provides high-level configuration that maps to CDK constructs.
 */
export interface HttpIntegration {
    /**
     * HTTP method for the endpoint.
     *
     * @example
     * ```typescript
     * method: 'POST'  // For creating resources
     * method: 'GET'   // For retrieving data
     * method: 'PUT'   // For updating resources
     * ```
     */
    method: HttpMethod;
    /**
     * URL path for the endpoint.
     *
     * **Path Parameters**: Use `{param}` syntax for dynamic segments
     * **Examples**:
     * - `/api/users`: Static path
     * - `/api/users/{id}`: Path with parameter
     * - `/api/users/{id}/orders/{orderId}`: Multiple parameters
     *
     * @example
     * ```typescript
     * path: '/api/payments/charge'
     * path: '/api/users/{userId}/payments'
     * ```
     */
    path: string;
    /**
     * Authentication configuration for the endpoint.
     *
     * The framework supports two configuration modes:
     *
     * **String mode (convenience)**: Use `AuthType` string for simple cases
     * - `'none'`: Public endpoint, no authentication
     * - Other values require full `AuthConfig` object
     *
     * **Object mode (full configuration)**: Use `AuthConfig` for detailed settings
     * - `{ type: 'none' }`: Explicit no authentication
     * - `{ type: 'jwt', issuer: '...', audience: [...] }`: JWT validation
     * - `{ type: 'iam' }`: AWS IAM signature validation
     * - `{ type: 'cognito', userPoolId: '...', region: '...' }`: Cognito integration
     * - `{ type: 'custom', authorizerLambda: fn }`: Custom Lambda authorizer
     *
     * @default 'none'
     *
     * @example String mode (convenience)
     * ```typescript
     * auth: 'none'  // Public endpoint
     * ```
     *
     * @example JWT authorization
     * ```typescript
     * auth: {
     *   type: 'jwt',
     *   issuer: 'https://auth.example.com',
     *   audience: ['api.example.com']
     * }
     * ```
     *
     * @example Cognito authorization
     * ```typescript
     * auth: {
     *   type: 'cognito',
     *   userPoolId: 'us-east-1_xxxxx',
     *   region: 'us-east-1',
     *   userPoolClientIds: ['client-id']
     * }
     * ```
     *
     * @example IAM authorization
     * ```typescript
     * auth: { type: 'iam' }
     * ```
     *
     * @example Custom Lambda authorizer
     * ```typescript
     * auth: {
     *   type: 'custom',
     *   authorizerLambda: myAuthFunction,
     *   enableSimpleResponses: true
     * }
     * ```
     */
    auth?: AuthType | AuthConfig;
    /**
     * Enable CORS for the endpoint.
     *
     * **Simple CORS**: Set to `true` for default CORS configuration
     * **Custom CORS**: Set to `true` and provide `corsConfig` for fine-grained control
     *
     * @default true
     *
     * @example
     * ```typescript
     * cors: true  // Enable with defaults
     * ```
     */
    cors?: boolean;
    /**
     * Detailed CORS configuration.
     *
     * **Required**: `cors` must be `true` for this to take effect
     * **Optional**: If omitted, uses sensible defaults based on stage
     *
     * @see {@link CorsConfig}
     *
     * @example
     * ```typescript
     * corsConfig: {
     *   allowOrigins: ['https://myapp.com'],
     *   allowMethods: ['GET', 'POST'],
     *   allowHeaders: ['Content-Type', 'Authorization'],
     *   allowCredentials: true,
     *   maxAge: 3600
     * }
     * ```
     */
    corsConfig?: CorsConfig;
}
