/**
 * Framework Resource Provider Interface
 *
 * Port interface for resource creation following Hexagonal Architecture.
 * RuntimeInfraStack implements this interface as the Adapter.
 *
 * This interface defines the contract between the Declarative Infrastructure API
 * and the framework stacks (RuntimeInfraStack), ensuring all resource creation
 * flows through the framework abstraction layer.
 *
 * @module infra/interfaces
 *
 * Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8
 */
import type { IConstruct } from 'constructs';
import type * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import type * as sqs from 'aws-cdk-lib/aws-sqs';
import type * as sns from 'aws-cdk-lib/aws-sns';
import type * as s3 from 'aws-cdk-lib/aws-s3';
import type * as cognito from 'aws-cdk-lib/aws-cognito';
import type * as events from 'aws-cdk-lib/aws-events';
import type * as iam from 'aws-cdk-lib/aws-iam';
import type { Stage, ITableResourceEntity, IQueueResourceEntity, ITopicResourceEntity, IBucketResourceEntity, ICognitoResourceEntity, IEventBusResourceEntity, CrossStackReference } from '../../lib/runtime-web/types/declarative-api';
import type { RuntimeInfraResourceOptions } from './runtime-infra-resources.interface';
/**
 * Permission grant type with strict typing.
 *
 * Replaces string type for compile-time validation and IDE autocomplete.
 * - 'read': Read-only access (e.g., GetItem, Query, Scan for DynamoDB)
 * - 'write': Write-only access (e.g., PutItem, DeleteItem for DynamoDB)
 * - 'readWrite': Full read and write access
 *
 * @example
 * ```typescript
 * const options: TableCreationOptions = {
 *   grantType: 'read', // Type-safe, autocomplete available
 * };
 * ```
 *
 * Validates: Requirements 5.1
 */
export type GrantType = 'read' | 'write' | 'readWrite';
/**
 * DynamoDB stream view type with strict typing.
 *
 * Mirrors CDK StreamViewType enum for type safety without requiring CDK import.
 * - 'KEYS_ONLY': Only the key attributes of the modified item
 * - 'NEW_IMAGE': The entire item, as it appears after modification
 * - 'OLD_IMAGE': The entire item, as it appeared before modification
 * - 'NEW_AND_OLD_IMAGES': Both the new and old images of the item
 *
 * @example
 * ```typescript
 * const options: TableCreationOptions = {
 *   enableStream: true,
 *   streamViewType: 'NEW_AND_OLD_IMAGES', // Type-safe
 * };
 * ```
 *
 * Validates: Requirements 5.2
 */
export type StreamViewType = 'KEYS_ONLY' | 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES';
/**
 * Base options for resource creation.
 *
 * Common options shared by all resource creation methods.
 *
 * Validates: Requirements 2.8
 */
export interface ResourceCreationOptionsBase {
    /**
     * Whether to auto-grant Lambda role access.
     * @default true
     */
    readonly autoGrant?: boolean;
    /**
     * Permission level for auto-grant.
     * Uses strict union type for compile-time validation.
     * @default 'readWrite'
     */
    readonly grantType?: GrantType;
    /**
     * Additional tags to apply to the resource.
     * These are merged with default tags (Project, Stage, ManagedBy).
     */
    readonly tags?: Readonly<Record<string, string>>;
    /**
     * Whether to create CloudFormation outputs for cross-stack references.
     * @default true
     */
    readonly createOutputs?: boolean;
}
/**
 * Options for creating a DynamoDB table.
 *
 * Supports full CDK props passthrough with explicit override detection.
 * Override flags allow backward compatibility while enabling explicit control.
 *
 * @example
 * ```typescript
 * // Use framework defaults
 * const options: TableCreationOptions = {
 *   enableStream: true,
 *   streamViewType: 'NEW_AND_OLD_IMAGES',
 * };
 *
 * // Override framework name generation
 * const options: TableCreationOptions = {
 *   overrideName: true, // Use tableName from props instead of generated name
 * };
 * ```
 *
 * Validates: Requirements 2.1, 2.5, 4.6, 5.1, 5.2
 */
export interface TableCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Enable DynamoDB Streams.
     * @default false
     */
    readonly enableStream?: boolean;
    /**
     * Stream view type when streams are enabled.
     * Accepts both framework union type and CDK enum for flexibility.
     * @default dynamodb.StreamViewType.NEW_AND_OLD_IMAGES
     */
    readonly streamViewType?: StreamViewType | dynamodb.StreamViewType;
    /**
     * Enable Point-in-Time Recovery.
     * When set, overrides the stage-based default (true for prod, false otherwise).
     */
    readonly enablePitr?: boolean;
    /**
     * Enable Time-to-Live on the table.
     * Requires ttlAttributeName to be set.
     * @default false
     */
    readonly enableTtl?: boolean;
    /**
     * TTL attribute name (used when enableTtl is true).
     * The attribute must be of type Number and contain Unix epoch timestamps.
     */
    readonly ttlAttributeName?: string;
    /**
     * Override framework name generation.
     * When true, uses tableName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
    /**
     * Override framework removal policy.
     * When true, uses removalPolicy from props instead of stage-based default.
     * @default false
     */
    readonly overrideRemovalPolicy?: boolean;
    /**
     * Override framework PITR configuration.
     * When true, uses pointInTimeRecovery from props instead of stage-based default.
     * @default false
     */
    readonly overridePitr?: boolean;
    /**
     * Override framework encryption configuration.
     * When true, uses encryption from props instead of framework default.
     * @default false
     */
    readonly overrideEncryption?: boolean;
}
/**
 * Options for creating an SQS queue.
 *
 * Supports full CDK props passthrough with explicit override detection.
 *
 * @example
 * ```typescript
 * // Use framework defaults with DLQ
 * const options: QueueCreationOptions = {
 *   enableDlq: true,
 *   maxReceiveCount: 5,
 * };
 *
 * // Override framework name generation
 * const options: QueueCreationOptions = {
 *   overrideName: true, // Use queueName from props
 * };
 * ```
 *
 * Validates: Requirements 2.2, 2.5
 */
export interface QueueCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Enable Dead Letter Queue.
     * @default false
     */
    readonly enableDlq?: boolean;
    /**
     * Maximum receive count before sending to DLQ.
     * Only used when enableDlq is true.
     * @default 3
     */
    readonly maxReceiveCount?: number;
    /**
     * Override framework name generation.
     * When true, uses queueName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
    /**
     * Override framework removal policy.
     * When true, uses removalPolicy from props instead of stage-based default.
     * @default false
     */
    readonly overrideRemovalPolicy?: boolean;
}
/**
 * Options for creating an SNS topic.
 *
 * Supports full CDK props passthrough with explicit override detection.
 *
 * @example
 * ```typescript
 * // Use framework defaults with FIFO
 * const options: TopicCreationOptions = {
 *   fifo: true,
 * };
 *
 * // Override framework name generation
 * const options: TopicCreationOptions = {
 *   overrideName: true, // Use topicName from props
 * };
 * ```
 *
 * Validates: Requirements 1.4, 2.1, 2.5
 */
export interface TopicCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Enable FIFO topic.
     * @default false
     */
    readonly fifo?: boolean;
    /**
     * Override framework name generation.
     * When true, uses topicName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
}
/**
 * Options for creating an S3 bucket.
 *
 * Supports full CDK props passthrough with explicit override detection.
 *
 * @example
 * ```typescript
 * // Use framework defaults with website hosting
 * const options: BucketCreationOptions = {
 *   enableWebsite: true,
 *   versioned: true,
 * };
 *
 * // Override framework defaults
 * const options: BucketCreationOptions = {
 *   overrideName: true,
 *   overrideVersioning: true,
 * };
 * ```
 *
 * Validates: Requirements 2.4, 2.5
 */
export interface BucketCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Enable website hosting.
     * @default false
     */
    readonly enableWebsite?: boolean;
    /**
     * Enable versioning.
     * Defaults based on stage (true for prod).
     */
    readonly versioned?: boolean;
    /**
     * Override framework name generation.
     * When true, uses bucketName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
    /**
     * Override framework removal policy.
     * When true, uses removalPolicy from props instead of stage-based default.
     * @default false
     */
    readonly overrideRemovalPolicy?: boolean;
    /**
     * Override framework versioning configuration.
     * When true, uses versioned from props instead of stage-based default.
     * @default false
     */
    readonly overrideVersioning?: boolean;
    /**
     * Override framework encryption configuration.
     * When true, uses encryption from props instead of framework default.
     * @default false
     */
    readonly overrideEncryption?: boolean;
}
/**
 * Options for creating a Cognito User Pool.
 *
 * Supports full CDK props passthrough with explicit override detection.
 *
 * @example
 * ```typescript
 * // Use framework defaults with MFA
 * const options: UserPoolCreationOptions = {
 *   createClient: true,
 *   mfa: 'OPTIONAL',
 * };
 *
 * // Override framework name generation
 * const options: UserPoolCreationOptions = {
 *   overrideName: true, // Use userPoolName from props
 * };
 * ```
 *
 * Validates: Requirements 2.5
 */
export interface UserPoolCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Create a user pool client.
     * @default true
     */
    readonly createClient?: boolean;
    /**
     * Client name (used when createClient is true).
     */
    readonly clientName?: string;
    /**
     * Enable self sign-up.
     * @default true
     */
    readonly selfSignUp?: boolean;
    /**
     * MFA configuration.
     * Uses strict union type for compile-time validation.
     * @default 'OFF'
     */
    readonly mfa?: 'OFF' | 'OPTIONAL' | 'REQUIRED';
    /**
     * Override framework name generation.
     * When true, uses userPoolName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
    /**
     * Override framework removal policy.
     * When true, uses removalPolicy from props instead of stage-based default.
     * @default false
     */
    readonly overrideRemovalPolicy?: boolean;
}
/**
 * Options for creating an EventBridge Event Bus.
 *
 * Supports full CDK props passthrough with explicit override detection.
 *
 * @example
 * ```typescript
 * // Use framework defaults with archiving
 * const options: EventBusCreationOptions = {
 *   enableArchive: true,
 *   archiveRetentionDays: 90,
 * };
 *
 * // Override framework name generation
 * const options: EventBusCreationOptions = {
 *   overrideName: true, // Use eventBusName from props
 * };
 * ```
 *
 * Validates: Requirements 2.6, 2.5
 */
export interface EventBusCreationOptions extends ResourceCreationOptionsBase {
    /**
     * Enable event archiving.
     * @default false
     */
    readonly enableArchive?: boolean;
    /**
     * Archive retention days (used when enableArchive is true).
     * @default 30
     */
    readonly archiveRetentionDays?: number;
    /**
     * Override framework name generation.
     * When true, uses eventBusName from props instead of generating framework-compliant name.
     * @default false
     */
    readonly overrideName?: boolean;
}
/**
 * Result type for resource creation methods.
 *
 * Returns both the CDK construct for direct access and the framework
 * entity wrapper for use with the Declarative API patterns.
 *
 * Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
 */
export interface FrameworkResourceResult<TConstruct extends IConstruct, TEntity> {
    /**
     * The CDK construct for direct access.
     * Use this when you need to configure additional CDK-specific settings.
     */
    readonly construct: TConstruct;
    /**
     * The framework entity wrapper.
     * Use this with Declarative API patterns (Repository, Observer, etc.).
     */
    readonly entity: TEntity;
    /**
     * CloudFormation outputs created for cross-stack references.
     * Empty array if createOutputs was false.
     */
    readonly outputs: readonly CrossStackReference[];
}
/**
 * Port interface for resource creation following Hexagonal Architecture.
 *
 * RuntimeInfraStack implements this interface as the Adapter, providing
 * resource creation methods that follow framework conventions:
 * - Consistent naming via resourceName()
 * - Default tags (Project, Stage, ManagedBy)
 * - Auto-grant permissions to lambdaRole
 * - CloudFormation outputs for cross-stack references
 * - Event publishing through Event_Bus_Mediator
 *
 * @example
 * ```typescript
 * // RuntimeInfraStack implements IFrameworkResourceProvider
 * const infraStack = new RuntimeInfraStack(app, 'Infra', {
 *   stage: 'dev',
 *   serviceName: 'my-service',
 * });
 *
 * // Use through InfrastructureContext
 * const context = createInfrastructureContext({
 *   infraStack,
 *   serviceName: 'my-service',
 *   stage: 'dev',
 * });
 *
 * // Create resources through factories (which delegate to provider)
 * const table = context.factories.dynamodb.createTable('users', {
 *   partitionKey: { name: 'userId', type: dynamodb.AttributeType.STRING },
 * });
 * ```
 *
 * Implements: Ports & Adapters (Hexagonal Architecture)
 * Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8
 */
export interface IFrameworkResourceProvider {
    /**
     * Service name for resource naming.
     * Used as prefix in resource names: {serviceName}-{name}-{region}-{stage}
     */
    readonly serviceName: string;
    /**
     * Deployment stage.
     * Determines environment-specific defaults (removal policy, encryption, etc.).
     */
    readonly stage: Stage;
    /**
     * Lambda execution role for auto-grant.
     * Resources are automatically granted permissions to this role when autoGrant is true.
     */
    readonly lambdaRole: iam.IRole;
    /**
     * Static S3 bucket from the infrastructure stack.
     * Available for use by the Declarative API.
     */
    readonly staticBucket: s3.IBucket;
    /**
     * Generate resource name following framework conventions.
     *
     * Pattern: {serviceName}-{name}-{regionSignature}-{stage}
     *
     * @param options - Resource naming options
     * @returns The generated resource name
     *
     * @example
     * ```typescript
     * const name = provider.resourceName({
     *   name: 'users',
     *   serviceName: 'my-service',
     *   stage: 'dev',
     *   region: 'us-east-1',
     * });
     * // Returns: 'my-service-users-ue1-dev'
     * ```
     */
    resourceName(options: RuntimeInfraResourceOptions): string;
    /**
     * Create a DynamoDB table with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Auto-grant to lambdaRole (when autoGrant is true)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the table (used in naming)
     * @param props - DynamoDB table properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.1
     */
    createTable<TProps extends dynamodb.TableProps>(id: string, props: TProps, options?: TableCreationOptions): FrameworkResourceResult<dynamodb.Table, ITableResourceEntity>;
    /**
     * Create an SQS queue with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Auto-grant to lambdaRole (when autoGrant is true)
     * - DLQ creation (when enableDlq is true)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the queue (used in naming)
     * @param props - SQS queue properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.2
     */
    createQueue<TProps extends sqs.QueueProps>(id: string, props: TProps, options?: QueueCreationOptions): FrameworkResourceResult<sqs.Queue, IQueueResourceEntity>;
    /**
     * Create an SNS topic with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Auto-grant to lambdaRole (when autoGrant is true)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the topic (used in naming)
     * @param props - SNS topic properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.3
     */
    createTopic<TProps extends sns.TopicProps>(id: string, props: TProps, options?: TopicCreationOptions): FrameworkResourceResult<sns.Topic, ITopicResourceEntity>;
    /**
     * Create an S3 bucket with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Auto-grant to lambdaRole (when autoGrant is true)
     * - Stage-specific configuration (versioning, removal policy)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the bucket (used in naming)
     * @param props - S3 bucket properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.4
     */
    createBucket<TProps extends s3.BucketProps>(id: string, props: TProps, options?: BucketCreationOptions): FrameworkResourceResult<s3.Bucket, IBucketResourceEntity>;
    /**
     * Create a Cognito User Pool with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Client creation (when createClient is true)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the user pool (used in naming)
     * @param props - Cognito user pool properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.5
     */
    createUserPool<TProps extends cognito.UserPoolProps>(id: string, props: TProps, options?: UserPoolCreationOptions): FrameworkResourceResult<cognito.UserPool, ICognitoResourceEntity>;
    /**
     * Create an EventBridge Event Bus with framework conventions.
     *
     * Applies:
     * - Framework naming via resourceName()
     * - Default tags (Project, Stage, ManagedBy)
     * - Archive configuration (when enableArchive is true)
     * - CloudFormation outputs (when createOutputs is true)
     * - ResourceCreatedEvent publishing
     *
     * @param id - Logical ID for the event bus (used in naming)
     * @param props - EventBridge event bus properties
     * @param options - Framework creation options
     * @returns Result containing CDK construct and framework entity
     *
     * Validates: Requirements 2.6
     */
    createEventBus<TProps extends events.EventBusProps>(id: string, props: TProps, options?: EventBusCreationOptions): FrameworkResourceResult<events.EventBus, IEventBusResourceEntity>;
}
/**
 * Type guard to check if an object implements IFrameworkResourceProvider.
 *
 * @param obj - Object to check
 * @returns True if the object implements IFrameworkResourceProvider
 */
export declare function isFrameworkResourceProvider(obj: unknown): obj is IFrameworkResourceProvider;
