@types/serverless/plugins/aws/provider/awsProvider.d.ts

TypeScript definitions for serverless

import Serverless = require("../../../index");

declare namespace Aws {
    /*
        Types based on https://github.com/serverless/serverless/blob/master/docs/providers/aws/guide/serverless.yml.md
    */
    /**
     * Root configuration interface for a Serverless Framework service.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml
     * @example
     * ```yaml
     * service: my-service
     * frameworkVersion: '3'
     * provider:
     *   name: aws
     *   runtime: nodejs18.x
     * functions:
     *   hello:
     *     handler: handler.hello
     * ```
     */
    interface Serverless {
        /** Service name or configuration object */
        service: Service | string;
        /**
         * Enable loading environment variables from .env files.
         * @see https://www.serverless.com/framework/docs/environment-variables
         */
        useDotenv?: boolean | undefined;
        /**
         * Serverless Framework version constraint (e.g., '3', '>=2.0.0 <4.0.0').
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#frameworkversion
         */
        frameworkVersion?: string | undefined;
        /** Falls back to locally installed Serverless if available */
        enableLocalInstallationFallback?: boolean | undefined;
        /**
         * @deprecated Variables resolution mode - only relevant for v2 migrations
         */
        variablesResolutionMode?: "20210219" | "20210326" | undefined;
        /** How to handle unresolved variables: 'warn' logs, 'error' throws */
        unresolvedVariablesNotificationMode?: "warn" | "error" | undefined;
        /** How to handle deprecation warnings */
        deprecationNotificationMode?: "warn" | "warn:summary" | "error" | undefined;
        /**
         * Array of deprecation codes to suppress.
         * @example ['LAMBDA_HASHING_VERSION_V2']
         */
        disabledDeprecations?: string[] | undefined;
        /** Config validation strictness: 'warn', 'error', or 'off' */
        configValidationMode?: "warn" | "error" | "off" | undefined;
        /** AWS provider configuration */
        provider: Provider;
        /**
         * Packaging configuration for deployment artifacts.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/packaging
         */
        package?: Package | undefined;
        /**
         * Function definitions for the service.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions
         */
        functions?: Functions | undefined;
        /**
         * Lambda layer definitions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/layers
         */
        layers?: Layers | undefined;
        /**
         * CloudFormation resources to include.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/resources
         */
        resources?: Resources | undefined;
        /**
         * Plugins to extend Serverless functionality.
         * @example ['serverless-offline', 'serverless-webpack']
         */
        plugins?: string[] | undefined;
        /**
         * Serverless Dashboard organization name.
         * @see https://www.serverless.com/framework/docs/guides/dashboard
         */
        org?: string | undefined;
        /** Serverless Dashboard app name */
        app?: string | undefined;
        /** @deprecated Use 'org' instead */
        tenant?: string | undefined;
        /**
         * Custom variables accessible via ${self:custom.xxx}.
         * @example
         * ```yaml
         * custom:
         *   tableName: users-${self:provider.stage}
         *   webpack:
         *     webpackConfig: ./webpack.config.js
         * ```
         */
        custom?: Custom | undefined;
        /**
         * Stage-specific configuration for parameters, observability, and integrations.
         * @since v4
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/stages
         * @example
         * ```yaml
         * stages:
         *   default:
         *     params:
         *       tableName: my-table
         *   prod:
         *     params:
         *       tableName: my-prod-table
         * ```
         */
        stages?: Stages | undefined;
        /**
         * Native build configuration for TypeScript/JavaScript bundling.
         * @since v4
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/building
         * @remarks
         * **Migration Warning ⚠️:** If migrating from v3 and using bundler plugins
         * (e.g., serverless-webpack, serverless-esbuild, serverless-plugin-typescript),
         * disable the native build with `build: { esbuild: false }`.
         * The native build system may conflict with existing bundler plugins.
         * Note: `build: false` does NOT disable esbuild — `false?.esbuild` evaluates
         * to `undefined`, causing it to fall through to zero-config auto-detection.
         * @example
         * ```yaml
         * # Disable native esbuild when using legacy bundler plugins
         * build:
         *   esbuild: false
         *
         * # Or configure native esbuild
         * build:
         *   esbuild:
         *     bundle: true
         *     minify: true
         *     configFile: ./esbuild.config.js
         * ```
         */
        build?: string | Build | undefined;
        /**
         * Serverless Framework license key for v4+.
         * @since v4
         * @see https://www.serverless.com/framework/docs/guides/license-keys
         * @remarks This is a root-level property, not a provider property.
         * @example '${env:SERVERLESS_LICENSE_KEY}'
         */
        licenseKey?: string | undefined;
    }

    interface Service {
        name: string;
        /** @deprecated in favor of `kmsKeyArn` at the provider level  */
        awsKmsKeyArn?: string | undefined;
    }

    /**
     * API Gateway API key configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#setting-api-keys-for-your-rest-api
     */
    interface ApiKey {
        /** API key name */
        name: string;
        /** API key value (20-128 characters) */
        value: string;
        /** Description of the API key */
        description?: string | undefined;
        /** Customer ID for usage tracking */
        customerId?: string | undefined;
        /**
         * Whether the API key is enabled.
         * @default true
         */
        enabled?: boolean | undefined;
    }

    /**
     * AWS provider configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml
     * @example
     * ```yaml
     * provider:
     *   name: aws
     *   runtime: nodejs18.x
     *   stage: ${opt:stage, 'dev'}
     *   region: us-east-1
     *   memorySize: 512
     *   timeout: 30
     *   environment:
     *     TABLE_NAME: ${self:custom.tableName}
     * ```
     */
    interface Provider {
        /** Must be 'aws' for AWS provider */
        name: "aws";
        /**
         * Default Lambda runtime for all functions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#runtime
         * @example 'nodejs18.x' | 'nodejs20.x' | 'python3.11' | 'java21'
         */
        runtime?: string | undefined;
        /**
         * Deployment stage name. Defaults to 'dev'.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/variables#referencing-cli-options
         * @example '${opt:stage, "dev"}'
         */
        stage?: string | undefined;
        /**
         * AWS region for deployment.
         * @see https://docs.aws.amazon.com/general/latest/gr/lambda-service.html
         * @example 'us-east-1' | 'eu-west-1' | 'ap-southeast-2'
         */
        region?: string | undefined;
        /**
         * Custom CloudFormation stack name. Defaults to service-stage.
         * @example 'my-custom-stack-name'
         */
        stackName?: string | undefined;
        /**
         * Custom API Gateway REST API name.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway
         */
        apiName?: string | undefined;
        /**
         * @deprecated No longer needed in v3+. Lambda hashing version for deployment.
         */
        lambdaHashingVersion?: number | undefined;

        /**
         * Custom WebSocket API name.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/websocket
         */
        websocketsApiName?: string | undefined;
        /**
         * WebSocket route selection expression.
         * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-route-keys-connect-disconnect.html
         * @default 'request.body.action'
         */
        websocketsApiRouteSelectionExpression?: string | undefined;
        /**
         * AWS credentials profile name from ~/.aws/credentials.
         * @example 'my-company-profile'
         */
        profile?: string | undefined;
        /**
         * Default memory size in MB for all functions (128-10240).
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#memory-size
         * @default 1024
         * @example 256 | 512 | 1024 | 2048
         */
        memorySize?: number | string | undefined;
        /**
         * Ephemeral storage size in MB for /tmp (512-10240).
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#ephemeral-storage
         * @default 512
         */
        ephemeralStorageSize?: number | string | undefined;
        /**
         * Reserved concurrent executions for all functions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#reserved-concurrency
         */
        reservedConcurrency?: number | string | undefined;
        /**
         * Default timeout in seconds for all functions (1-900).
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#timeout
         * @default 6
         */
        timeout?: number | string | undefined;
        /**
         * CloudWatch log retention in days.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#log-retention
         * @example 7 | 14 | 30 | 60 | 90 | 365
         */
        logRetentionInDays?: number | string | undefined;
        /**
         * S3 deployment bucket configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#deployment-bucket
         */
        deploymentBucket?: DeploymentBucket | undefined;
        /**
         * Prefix for deployment artifacts in S3 bucket.
         * @default 'serverless'
         */
        deploymentPrefix?: string | undefined;
        /**
         * @deprecated Use `iam.role` instead.
         * ARN of an existing IAM role for Lambda execution.
         */
        role?: string | undefined;
        /**
         * @deprecated Use `iam.role.permissionsBoundary` instead.
         */
        rolePermissionsBoundary?: string | undefined;
        /**
         * @deprecated Use `iam.role.statements` instead.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/iam
         */
        iamRoleStatements?: IamRoleStatement[] | undefined;
        /**
         * @deprecated Use `iam.role.managedPolicies` instead.
         */
        iamManagedPolicies?: string[] | undefined;
        /**
         * @deprecated Use `iam.deploymentRole` instead.
         * ARN of IAM role for CloudFormation to assume.
         */
        cfnRole?: string | undefined;
        /**
         * IAM configuration for Lambda execution and deployment roles.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/iam
         * @example
         * ```yaml
         * iam:
         *   role:
         *     statements:
         *       - Effect: Allow
         *         Action:
         *           - dynamodb:Query
         *         Resource: '*'
         * ```
         */
        iam?: IamSettings | undefined;
        /**
         * Whether to version Lambda functions. Set false for faster deploys.
         * @default true
         */
        versionFunctions?: boolean | undefined;
        /**
         * Default Lambda architecture.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#architecture
         * @default 'x86_64'
         */
        architecture?: "x86_64" | "arm64" | undefined;
        /**
         * Environment variables for all functions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#environment-variables
         * @example
         * ```yaml
         * environment:
         *   NODE_ENV: production
         *   TABLE_NAME: ${self:custom.tableName}
         * ```
         */
        environment?: Environment | string | undefined;
        /**
         * API Gateway endpoint type.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#configuring-endpoint-types
         * @default 'edge'
         */
        endpointType?: "regional" | "edge" | "private" | undefined;
        /**
         * API Gateway API keys configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#setting-api-keys-for-your-rest-api
         */
        apiKeys?: Array<ApiKey | string> | undefined;
        /**
         * REST API Gateway (v1) configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway
         */
        apiGateway?: ApiGateway | undefined;
        /**
         * Application Load Balancer configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/alb
         */
        alb?: Alb | undefined;
        /**
         * HTTP API Gateway (v2) configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api
         * @example
         * ```yaml
         * httpApi:
         *   cors: true
         *   authorizers:
         *     myAuthorizer:
         *       type: jwt
         *       identitySource: request.header.Authorization
         *       issuerUrl: https://cognito-idp.region.amazonaws.com/poolId
         *       audience:
         *         - myClientId
         * ```
         */
        httpApi?: HttpApi | undefined;
        /**
         * API Gateway usage plan configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#usage-plan
         */
        usagePlan?: UsagePlan | undefined;
        /**
         * Tags applied to the CloudFormation stack.
         * @example { Environment: 'production', Team: 'backend' }
         */
        stackTags?: Tags | undefined;
        /** CloudFormation stack policy statements */
        stackPolicy?: ResourcePolicy[] | undefined;
        /**
         * VPC configuration for all functions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#vpc-configuration
         * @example
         * ```yaml
         * vpc:
         *   securityGroupIds:
         *     - sg-12345678
         *   subnetIds:
         *     - subnet-12345678
         *     - subnet-87654321
         * ```
         */
        vpc?: string | Vpc | undefined;
        /**
         * SNS topic ARNs for CloudFormation stack notifications.
         * @example ['arn:aws:sns:us-east-1:123456789:my-topic']
         */
        notificationArns?: string[] | undefined;
        /** CloudFormation stack parameters */
        stackParameters?: StackParameters[] | undefined;
        /**
         * API Gateway resource policy for access control.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#resource-policy
         */
        resourcePolicy?: ResourcePolicy[] | undefined;
        /**
         * CloudFormation rollback configuration.
         * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-rollback-triggers.html
         */
        rollbackConfiguration?: RollbackConfiguration | undefined;
        /**
         * Tags applied to all Lambda functions.
         * @example { Project: 'my-project', CostCenter: 'engineering' }
         */
        tags?: Tags | undefined;
        /**
         * X-Ray tracing configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#aws-x-ray-tracing
         */
        tracing?: Tracing | undefined;
        /**
         * CloudWatch logging configuration.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#logs
         */
        logs?: Logs | undefined;
        /**
         * KMS key ARN for encrypting environment variables.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#kms-keys
         */
        kmsKeyArn?: string | undefined;
        /**
         * EventBridge configuration options.
         * @see https://www.serverless.com/framework/docs/providers/aws/events/event-bridge
         */
        eventBridge?: EventBridge | undefined;
        /**
         * Lambda layers to apply to all functions.
         * @see https://www.serverless.com/framework/docs/providers/aws/guide/layers
         * @example
         * ```yaml
         * layers:
         *   - arn:aws:lambda:region:account:layer:name:version
         *   - { Ref: MyLayerLambdaLayer }
         * ```
         */
        layers?: Array<string | Record<string, string>> | undefined;
    }

    /**
     * EventBridge provider-level configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/event-bridge
     */
    interface EventBridge {
        /**
         * Use CloudFormation for EventBridge rules instead of direct AWS API.
         * @default false
         */
        useCloudFormation?: boolean;
    }

    /**
     * IAM configuration for Lambda execution and deployment.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/iam
     * @example
     * ```yaml
     * iam:
     *   role:
     *     name: my-custom-role
     *     statements:
     *       - Effect: Allow
     *         Action:
     *           - s3:GetObject
     *         Resource: '*'
     *   deploymentRole: arn:aws:iam::123456789:role/deploy-role
     * ```
     */
    interface IamSettings {
        /**
         * Lambda execution role ARN or inline configuration.
         * @example 'arn:aws:iam::123456789:role/my-role'
         */
        role?: string | IamRole | undefined;
        /**
         * IAM role ARN for CloudFormation to assume during deployment.
         * @example 'arn:aws:iam::123456789:role/cloudformation-role'
         */
        deploymentRole?: string | undefined;
    }

    /**
     * Inline IAM role configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/iam#custom-iam-roles
     */
    interface IamRole {
        /** Custom name for the IAM role */
        name?: string | undefined;
        /**
         * ARN of the permissions boundary to attach.
         * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html
         */
        permissionBoundary?: string | undefined;
        /**
         * IAM policy statements for the role.
         * @example
         * ```yaml
         * statements:
         *   - Effect: Allow
         *     Action:
         *       - dynamodb:GetItem
         *       - dynamodb:PutItem
         *     Resource:
         *       - arn:aws:dynamodb:*:*:table/my-table
         * ```
         */
        statements?: IamRoleStatement[] | undefined;
        /**
         * ARNs of managed policies to attach.
         * @example ['arn:aws:iam::aws:policy/AmazonDynamoDBReadOnlyAccess']
         */
        managedPolicies?: string[] | undefined;
        /** Tags to apply to the IAM role */
        tags?: Tags | undefined;
    }

    /**
     * Key-value pairs for AWS resource tagging.
     * @example { Environment: 'production', Team: 'backend' }
     */
    interface Tags {
        [key: string]: string;
    }

    /**
     * IAM policy statement.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/iam
     * @example
     * ```yaml
     * - Effect: Allow
     *   Action:
     *     - dynamodb:Query
     *     - dynamodb:Scan
     *   Resource:
     *     - arn:aws:dynamodb:*:*:table/my-table
     *   Condition:
     *     StringEquals:
     *       aws:RequestTag/Environment: production
     * ```
     */
    interface IamRoleStatement {
        /** Allow or Deny the actions */
        Effect: "Allow" | "Deny";
        /** Optional statement ID */
        Sid?: string | undefined;
        /** Conditions for when the policy applies */
        Condition?: {
            [key: string]: any;
        } | undefined;
        /** Actions this statement applies to */
        Action?: string | string[] | { [key: string]: any } | undefined;
        /** Actions this statement does NOT apply to */
        NotAction?: string | string[] | { [key: string]: any } | undefined;
        /** Resources this statement applies to */
        Resource?: string | string[] | { [key: string]: any } | undefined;
        /** Resources this statement does NOT apply to */
        NotResource?: string | string[] | { [key: string]: any } | undefined;
    }

    /**
     * S3 deployment bucket configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#deployment-bucket
     * @example
     * ```yaml
     * deploymentBucket:
     *   name: my-deployment-bucket
     *   maxPreviousDeploymentArtifacts: 5
     *   blockPublicAccess: true
     *   serverSideEncryption: AES256
     * ```
     */
    interface DeploymentBucket {
        /**
         * Existing S3 bucket name for deployments.
         * @example 'my-company-deployments-${aws:region}'
         */
        name?: string | undefined;
        /**
         * Number of previous deployment artifacts to keep.
         * @default 5
         */
        maxPreviousDeploymentArtifacts?: number | string | undefined;
        /**
         * Block all public access to the bucket.
         * @default false
         */
        blockPublicAccess?: boolean | undefined;
        /**
         * Server-side encryption algorithm.
         * @example 'AES256' | 'aws:kms'
         */
        serverSideEncryption?: string | undefined;
        /** Skip automatic bucket policy setup */
        skipPolicySetup?: boolean | undefined;
        /** KMS key ID for SSE-KMS encryption */
        sseKMSKeyId?: string | undefined;
        /** SSE-C algorithm (for customer-provided keys) */
        sseCustomerAlgorithim?: string | undefined;
        /** Base64-encoded SSE-C key */
        sseCustomerKey?: string | undefined;
        /** MD5 digest of the SSE-C key */
        sseCustomerKeyMD5?: string | undefined;
        /** Tags to apply to the bucket */
        tags?: Tags | undefined;
    }

    /**
     * Environment variables map.
     * @example { NODE_ENV: 'production', TABLE_NAME: 'users' }
     */
    interface Environment {
        [key: string]: any;
    }

    /**
     * REST API Gateway (v1) configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway
     * @example
     * ```yaml
     * apiGateway:
     *   restApiId: abcd1234
     *   restApiRootResourceId: xyz789
     *   description: My REST API
     *   binaryMediaTypes:
     *     - 'image/png'
     *   minimumCompressionSize: 1024
     * ```
     */
    interface ApiGateway {
        /**
         * ID of an existing REST API to extend.
         * @example 'abcd1234xy'
         */
        restApiId?: string | undefined;
        /** Root resource ID of existing REST API */
        restApiRootResourceId?: string | undefined;
        /**
         * Map of resource paths to IDs for existing API.
         * @example { '/users': 'abc123', '/orders': 'def456' }
         */
        restApiResources?: {
            [key: string]: string;
        } | undefined;
        /** ID of existing WebSocket API */
        websocketApiId?: any;
        /**
         * Source for API key validation.
         * @default 'HEADER'
         */
        apiKeySourceType?: "HEADER" | "AUTHORIZER" | "header" | "authorizer" | undefined;
        /**
         * Minimum response size in bytes to compress (0-10485760).
         * @example 1024
         */
        minimumCompressionSize?: number | string | undefined;
        /** API description */
        description?: string | undefined;
        /**
         * MIME types to treat as binary.
         * @example ['image/*', 'application/pdf']
         */
        binaryMediaTypes?: string[] | undefined;
        /** Enable CloudWatch metrics for API Gateway */
        metrics?: boolean | undefined;
        /** Prefix API name with service name */
        shouldStartNameWithService?: boolean | undefined;
        /** API keys configuration */
        apiKeys?: Array<ApiKey | string> | undefined;
        /** Resource-based access policy */
        resourcePolicy?: ResourcePolicy[] | undefined;
        /** Usage plan configuration */
        usagePlan?: UsagePlan | undefined;
    }

    /**
     * Cognito User Pool authorizer for ALB.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/alb#cognito-authentication
     */
    interface CognitoAuthorizer {
        type: "cognito";
        /** ARN of the Cognito User Pool */
        userPoolArn: string;
        /** Cognito app client ID */
        userPoolClientId: string;
        /** Cognito User Pool domain */
        userPoolDomain: string;
        /** Allow unauthenticated requests to pass through */
        allowUnauthenticated?: boolean | undefined;
        /** Extra parameters for the authorization request */
        requestExtraParams?: {
            prompt?: string | undefined;
            redirect?: boolean | undefined;
        } | undefined;
        /** OAuth scopes to request */
        scope?: string | undefined;
        /** Name of the session cookie */
        sessionCookieName?: string | undefined;
        /** Session timeout in seconds */
        sessionTimeout?: number | string | undefined;
    }

    /**
     * OIDC authorizer for ALB.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/alb#oidc-authentication
     */
    interface OidcAuthorizer {
        type: "oidc";
        /** OIDC authorization endpoint URL */
        authorizationEndpoint: string;
        /** OIDC client ID */
        clientId: string;
        /** OIDC client secret (use SSM or secrets manager in production) */
        clientSecret?: string | undefined;
        /** Use existing client secret from Secrets Manager */
        useExistingClientSecret?: boolean | undefined;
        /** OIDC issuer identifier */
        issuer: string;
        /** OIDC token endpoint URL */
        tokenEndpoint: string;
        /** OIDC user info endpoint URL */
        userInfoEndpoint: string;
        /** Allow unauthenticated requests */
        allowUnauthenticated?: boolean | undefined;
        requestExtraParams?: {
            prompt?: string | undefined;
            redirect?: boolean | undefined;
        } | undefined;
        /** OAuth scopes to request */
        scope?: string | undefined;
        sessionCookieName?: string | undefined;
        sessionTimeout?: number | string | undefined;
    }

    /**
     * JWT authorizer for HTTP API.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api#jwt-authorizers
     * @example
     * ```yaml
     * authorizers:
     *   myJwtAuthorizer:
     *     identitySource: request.header.Authorization
     *     issuerUrl: https://cognito-idp.region.amazonaws.com/poolId
     *     audience:
     *       - myClientId
     * ```
     */
    interface JwtAuthorizer {
        /**
         * Identity source expression.
         * @example 'request.header.Authorization'
         */
        identitySource: string;
        /**
         * JWT issuer URL.
         * @example 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123'
         */
        issuerUrl: string;
        /** Valid audience values for the JWT */
        audience: string[];
    }

    /**
     * Lambda request authorizer for HTTP API.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api#lambda-request-authorizers
     */
    interface CustomAuthorizer {
        type: "request";
        /** Name of the authorizer function defined in this service */
        functionName?: string;
        /** ARN of an external authorizer function */
        functionArn?: string;
        /** Authorizer name */
        name?: string;
        /**
         * Cache TTL in seconds (0 to disable).
         * @default 0
         */
        resultTtlInSeconds?: number;
        /** Enable simple response format (true/false) */
        enableSimpleResponses?: boolean;
        /**
         * Payload format version.
         * @example '2.0'
         */
        payloadVersion?: string;
        /**
         * Identity sources for caching.
         * @example ['request.header.Authorization']
         */
        identitySource?: string[];
        /** Set true if authorizer is managed outside this service */
        managedExternally?: boolean;
    }

    /**
     * Map of authorizer definitions.
     * @example
     * ```yaml
     * authorizers:
     *   myAuth:
     *     type: jwt
     *     identitySource: request.header.Authorization
     *     issuerUrl: https://example.com
     *     audience:
     *       - myApp
     * ```
     */
    interface Authorizers {
        [key: string]: CognitoAuthorizer | OidcAuthorizer | JwtAuthorizer | CustomAuthorizer;
    }

    /**
     * Application Load Balancer configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/alb
     */
    interface Alb {
        /**
         * Prefix for target group names (max 6 chars).
         * @example 'myapp'
         */
        targetGroupPrefix?: string | undefined;
        /** Authorizer definitions for ALB */
        authorizers?: Authorizers | undefined;
    }

    /**
     * HTTP API CORS configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api#cors-setup
     * @example
     * ```yaml
     * cors:
     *   allowedOrigins:
     *     - https://example.com
     *   allowedHeaders:
     *     - Content-Type
     *     - Authorization
     *   allowedMethods:
     *     - GET
     *     - POST
     *   allowCredentials: true
     *   maxAge: 86400
     * ```
     */
    interface HttpApiCors {
        /**
         * Allowed origins.
         * @example ['https://example.com', 'https://app.example.com']
         */
        allowedOrigins: string[];
        /** Allowed request headers */
        allowedHeaders?: string[] | undefined;
        /** Allowed HTTP methods */
        allowedMethods?: string[] | undefined;
        /** Allow credentials (cookies, authorization headers) */
        allowCredentials?: boolean | undefined;
        /** Headers to expose in response */
        exposedResponseHeaders?: string[] | undefined;
        /**
         * Preflight cache max age in seconds.
         * @example 86400
         */
        maxAge?: number | undefined;
    }

    /**
     * HTTP API Gateway (v2) configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api
     * @example
     * ```yaml
     * httpApi:
     *   name: my-http-api
     *   cors: true
     *   metrics: true
     *   authorizers:
     *     myAuth:
     *       type: jwt
     *       issuerUrl: https://example.com
     *       audience:
     *         - myApp
     * ```
     */
    interface HttpApi {
        /** ID of an existing HTTP API to extend */
        id?: string | undefined;
        /** Custom name for the HTTP API */
        name?: string | undefined;
        /**
         * Payload format version.
         * @default '2.0'
         * @example '1.0' | '2.0'
         */
        payload?: string | undefined;
        /** CORS configuration (true for defaults, or detailed config) */
        cors?: boolean | HttpApiCors | undefined;
        /** Authorizer definitions */
        authorizers?: Authorizers | undefined;
        /** Apply provider-level tags to HTTP API */
        useProviderTags?: boolean | undefined;
        /** Enable CloudWatch metrics */
        metrics?: boolean | undefined;
        /** Disable the default execute-api endpoint */
        disableDefaultEndpoint?: boolean | undefined;
        /** Prefix name with service name */
        shouldStartNameWithService?: boolean | undefined;
    }

    /**
     * API Gateway usage plan quota configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#usage-plan
     */
    interface Quota {
        /** Maximum requests allowed in the period */
        limit?: number | string | undefined;
        /** Number of requests to subtract from limit at start */
        offset?: number | string | undefined;
        /**
         * Quota period.
         * @example 'DAY' | 'WEEK' | 'MONTH'
         */
        period?: string | undefined;
    }

    /**
     * API Gateway usage plan throttling configuration.
     */
    interface Throttle {
        /** Maximum concurrent requests */
        burstLimit?: number | string | undefined;
        /** Steady-state request rate (requests/second) */
        rateLimit?: number | string | undefined;
    }

    /**
     * API Gateway usage plan configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#usage-plan
     * @example
     * ```yaml
     * usagePlan:
     *   quota:
     *     limit: 1000
     *     period: DAY
     *   throttle:
     *     burstLimit: 100
     *     rateLimit: 50
     * ```
     */
    interface UsagePlan {
        /** Request quota limits */
        quota?: Quota | undefined;
        /** Request throttling limits */
        throttle?: Throttle | undefined;
    }

    /**
     * API Gateway resource policy statement.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#resource-policy
     * @example
     * ```yaml
     * - Effect: Allow
     *   Principal: '*'
     *   Action: execute-api:Invoke
     *   Resource:
     *     - execute-api:/*
     *   Condition:
     *     IpAddress:
     *       aws:SourceIp:
     *         - 10.0.0.0/8
     * ```
     */
    interface ResourcePolicy {
        Effect: "Allow" | "Deny";
        /** Who this policy applies to */
        Principal?: string | string[] | { [key: string]: any } | undefined;
        /** Actions this policy applies to */
        Action?: string | string[] | { [key: string]: any } | undefined;
        /** Resources this policy applies to */
        Resource?: string | string[] | { [key: string]: any } | undefined;
        /** Conditions for this policy */
        Condition?: {
            [key: string]: any;
        } | undefined;
    }

    /**
     * VPC configuration for Lambda functions.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#vpc-configuration
     * @example
     * ```yaml
     * vpc:
     *   securityGroupIds:
     *     - sg-12345678
     *   subnetIds:
     *     - subnet-12345678
     *     - subnet-87654321
     * ```
     */
    interface Vpc {
        /** Security group IDs for the Lambda ENIs */
        securityGroupIds: string[];
        /** Subnet IDs where Lambda ENIs are created */
        subnetIds: string[] | string;
    }

    /**
     * CloudFormation stack parameter.
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html
     */
    interface StackParameters {
        /** Parameter name */
        ParameterKey: string;
        /** Parameter value */
        ParameterValue: string;
    }

    /**
     * CloudFormation rollback trigger.
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-rollback-triggers.html
     */
    interface RollbackTrigger {
        /** ARN of the CloudWatch alarm or event rule */
        Arn: string;
        /** Type of trigger: 'AWS::CloudWatch::Alarm' */
        Type: string;
    }

    /**
     * CloudFormation rollback configuration.
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-rollback-triggers.html
     */
    interface RollbackConfiguration {
        /** Monitoring period in minutes */
        MonitoringTimeInMinutes: number | string;
        /** Rollback triggers */
        RollbackTriggers: RollbackTrigger[];
    }

    /**
     * X-Ray tracing configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#aws-x-ray-tracing
     * @example
     * ```yaml
     * tracing:
     *   apiGateway: true
     *   lambda: Active
     * ```
     */
    interface Tracing {
        /** Enable API Gateway X-Ray tracing */
        apiGateway: boolean;
        /**
         * Lambda tracing mode.
         * - 'Active': Lambda samples and records traces
         * - 'PassThrough': Lambda only records if upstream sampled
         */
        lambda?: "Active" | "PassThrough" | boolean | undefined;
    }

    /**
     * REST API CloudWatch logging configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#logs
     */
    interface RestApiLogs {
        /** Enable access logging */
        accessLogging?: boolean | undefined;
        /**
         * Custom access log format.
         * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html
         */
        format?: string | undefined;
        /** Enable execution logging */
        executionLogging?: boolean | undefined;
        /** Execution log level */
        level?: "INFO" | "ERROR" | undefined;
        /** Log full request/response data */
        fullExecutionData?: boolean | undefined;
        /** Custom IAM role ARN for logging */
        role?: string | undefined;
        /** Set true if role is managed externally */
        roleManagedExternally?: boolean | undefined;
    }

    /**
     * WebSocket API logging configuration.
     */
    interface WebsocketLogs {
        /** Log level */
        level?: "INFO" | "ERROR" | undefined;
    }

    /**
     * HTTP API logging configuration.
     */
    interface HttpApiLogs {
        /**
         * Custom access log format.
         * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-logging.html
         */
        format?: string | undefined;
    }

    /**
     * CloudWatch logging configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#logs
     * @example
     * ```yaml
     * logs:
     *   restApi:
     *     accessLogging: true
     *     executionLogging: true
     *     level: INFO
     *   httpApi: true
     *   frameworkLambda: true
     * ```
     */
    interface Logs {
        /** REST API Gateway logging (true for all, or detailed config) */
        restApi?: true | RestApiLogs | undefined;
        /** WebSocket API logging */
        websocket?: WebsocketLogs | undefined;
        /** HTTP API logging (true or detailed config) */
        httpApi?: boolean | HttpApiLogs | undefined;
        /** Enable logging for framework-internal Lambda */
        frameworkLambda?: boolean | undefined;
    }

    /**
     * Packaging configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/packaging
     * @example
     * ```yaml
     * package:
     *   patterns:
     *     - '!node_modules/**'
     *     - '!.git/**'
     *     - 'src/**'
     *   individually: true
     * ```
     */
    interface Package {
        /**
         * @deprecated Use `patterns` instead. Files to include.
         */
        include?: string[] | undefined;
        /**
         * @deprecated Use `patterns` instead. Files to exclude.
         */
        exclude?: string[] | undefined;
        /**
         * Glob patterns for including/excluding files.
         * Prefix with '!' to exclude.
         * @example ['!node_modules/**', 'src/**']
         */
        patterns?: string[] | undefined;
        /**
         * Exclude devDependencies from package.
         * @default true
         */
        excludeDevDependencies?: boolean | undefined;
        /**
         * Pre-built deployment artifact path.
         * @example '.serverless/my-artifact.zip'
         */
        artifact?: string | undefined;
        /**
         * Package each function separately.
         * @default false
         */
        individually?: boolean | undefined;
    }

    /**
     * Lambda destination configuration for async invocations.
     * @see https://www.serverless.com/framework/docs/providers/aws/guide/functions#destinations
     * @example
     * ```yaml
     * destinations:
     *   onSuccess: arn:aws:sqs:region:account:success-queue
     *   onFailure: arn:aws:sns:region:account:failure-topic
     * ```
     */
    interface Destinations {
        /** ARN of destination for successful invocations */
        onSuccess?: string | undefined;
        /** ARN of destination for failed invocations */
        onFailure?: string | undefined;
    }

    /**
     * REST API Gateway Lambda authorizer configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#http-endpoints-with-custom-authorizers
     */
    interface HttpAuthorizer {
        /** Authorizer function name or reference */
        name?: string | undefined;
        /** Authorizer function ARN */
        arn?: string | undefined;
        /**
         * Cache TTL in seconds (0 to disable).
         * @default 300
         */
        resultTtlInSeconds?: number | string | undefined;
        /**
         * Identity source header.
         * @default 'method.request.header.Authorization'
         */
        identitySource?: string | undefined;
        /** Regex to validate identity */
        identityValidationExpression?: string | undefined;
        /**
         * Authorizer type.
         * @example 'token' | 'request' | 'cognito_user_pools'
         */
        type?: string | undefined;
    }

    /**
     * REST API Gateway CORS configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#enabling-cors
     * @example
     * ```yaml
     * cors:
     *   origins:
     *     - https://example.com
     *   headers:
     *     - Content-Type
     *     - Authorization
     *   allowCredentials: true
     * ```
     */
    interface HttpCors {
        /**
         * Allowed origins (can use '*').
         * @example ['https://example.com'] | '*'
         */
        origins?: string | string[] | undefined;
        /** Allowed headers */
        headers?: string | string[] | undefined;
        /** Allow credentials */
        allowCredentials?: boolean | undefined;
        /** Preflight cache max age in seconds */
        maxAge?: number | undefined;
        /** Cache-Control header for preflight response */
        cacheControl?: string | undefined;
    }

    /**
     * Request parameter validation for REST API.
     */
    interface HttpRequestParametersValidation {
        /** Required query string parameters */
        querystrings?: { [key: string]: boolean } | undefined;
        /** Required headers */
        headers?: { [key: string]: boolean } | undefined;
        /** Required path parameters */
        paths?: { [key: string]: boolean } | undefined;
    }

    /**
     * Request validation configuration for REST API.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway#request-validation
     */
    interface HttpRequestValidation {
        /** Parameter validation */
        parameters?: HttpRequestParametersValidation | undefined;
        /**
         * Request body schemas by content type.
         * @example { 'application/json': { type: 'object', properties: { name: { type: 'string' } } } }
         */
        schemas?: { [key: string]: Record<string, unknown> } | undefined;
    }

    /**
     * REST API Gateway event configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/apigateway
     * @example
     * ```yaml
     * events:
     *   - http:
     *       path: users/{id}
     *       method: get
     *       cors: true
     *       authorizer: myAuthorizer
     * ```
     */
    interface Http {
        /**
         * URL path for the endpoint.
         * @example 'users/{id}'
         */
        path: string;
        /**
         * HTTP method.
         * @example 'get' | 'post' | 'put' | 'delete' | 'any'
         */
        method: string;
        /** CORS configuration (true for defaults) */
        cors?: boolean | HttpCors | undefined;
        /** Require API key for access */
        private?: boolean | undefined;
        /** Enable async Lambda invocation */
        async?: boolean | undefined;
        /** Authorizer configuration */
        authorizer?: HttpAuthorizer | string | undefined;
        /** Request validation */
        request?: HttpRequestValidation | undefined;
        /**
         * Integration type.
         * @default 'lambda'
         */
        integration?: "lambda" | "mock" | undefined;
    }

    /**
     * HTTP API authorizer reference by name.
     */
    interface NamedHttpApiEventAuthorizer {
        /** Name of authorizer defined in httpApi.authorizers */
        name: string;
        /** OAuth scopes required */
        scopes?: string[] | undefined;
    }

    /**
     * HTTP API authorizer reference by ID.
     */
    interface IdRefHttpApiEventAuthorizer {
        /** ID of external authorizer */
        id: string;
        /** OAuth scopes required */
        scopes?: string[] | undefined;
    }

    /**
     * HTTP API Gateway event configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/http-api
     * @example
     * ```yaml
     * events:
     *   - httpApi:
     *       path: /users/{id}
     *       method: GET
     *       authorizer:
     *         name: myAuth
     * ```
     */
    interface HttpApiEvent {
        /**
         * HTTP method.
         * @example 'GET' | 'POST' | 'PUT' | 'DELETE' | '*'
         */
        method: string;
        /**
         * URL path.
         * @example '/users/{id}'
         */
        path: string;
        /** Authorizer configuration */
        authorizer?: NamedHttpApiEventAuthorizer | IdRefHttpApiEventAuthorizer | undefined;
    }

    /**
     * WebSocket API authorizer configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/websocket#routes-and-authorizers
     */
    interface WebsocketAuthorizer {
        /** Authorizer function name */
        name?: string | undefined;
        /** Authorizer function ARN */
        arn?: string | undefined;
        /** Identity sources for caching */
        identitySource?: string[] | undefined;
    }

    /**
     * WebSocket API event configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/websocket
     * @example
     * ```yaml
     * events:
     *   - websocket:
     *       route: $connect
     *       authorizer: myAuth
     *   - websocket:
     *       route: sendMessage
     * ```
     */
    interface Websocket {
        /**
         * WebSocket route key.
         * @example '$connect' | '$disconnect' | '$default' | 'sendMessage'
         */
        route: string;
        /** Route response selection expression */
        routeResponseSelectionExpression?: string | undefined;
        /** Authorizer configuration */
        authorizer?: WebsocketAuthorizer | undefined;
    }

    /**
     * S3 event filter rule.
     */
    interface S3Rule {
        /** Object key prefix filter */
        prefix?: string | undefined;
        /** Object key suffix filter */
        suffix?: string | undefined;
    }

    /**
     * S3 event configuration.
     * @see https://www.serverless.com/framework/docs/providers/aws/events/s3
     * @example
     * ```yaml
     * events:
     *   - s3:
     *       bucket: my-bucket
     *       event: s3:ObjectCreated:*
     *       rules:
     *         - prefix: uploads/
     *         - suffix: .jpg
     * ```
     */
    interface S3 {
        /** S3 bucket name */
        bucket: string;
        /**
         * S3 event type.
         * @example 's3:ObjectCreated:*' | 's3:ObjectRemoved:*'
         */
        event: string;
        /** Event filter rules */
        rules?: S3Rule[] | undefined;
        /** Set true if bucket already exists */
        existing?: boolean | undefined;
    }

    /**
     * Event input payload.
     */
    interface Input {
        [key: string]: any;
    }

    /**
     * EventBridge/CloudWatch input transformer.
     * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-transform-target-input.html
     */
    interface InputTransformer {
        /**
         * Map of JSON path expressions to variable names.
         * @example { 'instance': '$.detail.instance-id' }
         */
        inputPathsMap: { [key: string]: string };
        /**
         * Template for the transformed input.
         * @example '{"instance": <instance>}'
         */
        inputTemplate: string;
    }

    /**
     * Schedule event configuration (EventBridge Scheduler).
     * @see https://www.serverless.com/framework/docs/providers/aws/events/schedule
     * @example
     * ```yaml