@stacksjs/ts-cloud-types 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -0,0 +1,1242 @@
+/**
+ * Queue configuration presets for common use cases
+ * Use these to quickly configure queues with sensible defaults
+ *
+ * @example Basic usage
+ * import { QueuePresets } from '@stacksjs/ts-cloud-types'
+ *
+ * queues: {
+ *   jobs: QueuePresets.backgroundJobs,
+ *   orders: QueuePresets.fifo,
+ *   events: QueuePresets.highThroughput,
+ * }
+ *
+ * @example With Lambda trigger
+ * queues: {
+ *   orders: {
+ *     ...QueuePresets.backgroundJobs,
+ *     trigger: { functionName: 'processOrders' },
+ *   },
+ * }
+ *
+ * @example With monitoring
+ * queues: {
+ *   critical: {
+ *     ...QueuePresets.monitored,
+ *     alarms: {
+ *       ...QueuePresets.monitored.alarms,
+ *       notificationEmails: ['ops@example.com'],
+ *     },
+ *   },
+ * }
+ */
+export declare const QueuePresets: {
+  backgroundJobs: QueueItemConfig
+  fifo: QueueItemConfig
+  highThroughput: QueueItemConfig
+  delayed: QueueItemConfig
+  longRunning: QueueItemConfig
+  monitored: QueueItemConfig
+  lambdaOptimized: QueueItemConfig
+  fanOut: QueueItemConfig
+};
+/**
+ * Realtime configuration presets
+ *
+ * @example Serverless presets
+ * import { RealtimePresets } from '@stacksjs/ts-cloud-types'
+ * realtime: RealtimePresets.serverless.production
+ *
+ * @example Server presets (ts-broadcasting)
+ * realtime: RealtimePresets.server.production
+ */
+export declare const RealtimePresets: {
+  serverless: {
+    development: RealtimeConfig
+    production: RealtimeConfig
+    notifications: RealtimeConfig
+  }
+  server: {
+    development: RealtimeConfig
+    production: RealtimeConfig
+    highPerformance: RealtimeConfig
+    chat: RealtimeConfig
+    gaming: RealtimeConfig
+    single: RealtimeConfig
+  }
+};
+/**
+ * AWS-specific configuration
+ */
+export declare interface AwsConfig {
+  region?: string
+  profile?: string
+  accountId?: string
+}
+// Core configuration types
+export declare interface CloudConfig {
+  project: ProjectConfig
+  mode?: DeploymentMode
+  environments: Record<string, EnvironmentConfig>
+  infrastructure?: InfrastructureConfig
+  sites?: Record<string, SiteConfig>
+  aws?: AwsConfig
+  features?: Record<string, boolean>
+  hooks?: {
+    beforeDeploy?: string | ((config: CloudConfig) => Promise<void>)
+    afterDeploy?: string | ((config: CloudConfig) => Promise<void>)
+    beforeBuild?: string | ((config: CloudConfig) => Promise<void>)
+    afterBuild?: string | ((config: CloudConfig) => Promise<void>)
+  }
+  costPreset?: 'minimal' | 'balanced' | 'performance' | 'custom'
+  tags?: Record<string, string>
+}
+export declare interface ProjectConfig {
+  name: string
+  slug: string
+  region: string
+}
+export declare interface EnvironmentConfig {
+  type: EnvironmentType
+  region?: string
+  variables?: Record<string, string>
+  domain?: string
+  infrastructure?: Partial<InfrastructureConfig>
+}
+/**
+ * Network/VPC configuration
+ */
+export declare interface NetworkConfig {
+  vpc?: VpcConfig
+  subnets?: {
+    public?: number
+    private?: number
+  }
+  natGateway?: boolean | 'single' | 'perAz'
+}
+/**
+ * API Gateway configuration
+ */
+export declare interface ApiGatewayConfig {
+  type?: 'REST' | 'HTTP' | 'websocket'
+  name?: string
+  description?: string
+  stageName?: string
+  cors?: boolean | {
+    allowOrigins?: string[]
+    allowMethods?: string[]
+    allowHeaders?: string[]
+    maxAge?: number
+  }
+  authorization?: 'NONE' | 'IAM' | 'COGNITO' | 'LAMBDA'
+  throttling?: {
+    rateLimit?: number
+    burstLimit?: number
+  }
+  customDomain?: {
+    domain?: string
+    certificateArn?: string
+  }
+  authorizer?: {
+    type?: string
+    identitySource?: string
+    audience?: string[]
+  }
+  routes?: Array<{
+    path?: string
+    method?: string
+    integration?: string | { type?: string; service?: string }
+    authorizer?: string
+  }> | Record<string, {
+    path?: string
+    method?: string
+    integration?: string | { type?: string; service?: string }
+  }>
+}
+/**
+ * Messaging (SNS) configuration
+ */
+export declare interface MessagingConfig {
+  topics?: Record<string, {
+    name?: string
+    displayName?: string
+    subscriptions?: Array<{
+      protocol: 'email' | 'sqs' | 'lambda' | 'http' | 'https'
+      endpoint: string
+      filterPolicy?: Record<string, string[]>
+    }>
+  }>
+}
+export declare interface InfrastructureConfig {
+  vpc?: VpcConfig
+  network?: NetworkConfig
+  compute?: ComputeConfig
+  containers?: Record<string, ContainerItemConfig>
+  storage?: Record<string, StorageItemConfig & ResourceConditions>
+  functions?: Record<string, FunctionConfig & ResourceConditions>
+  servers?: Record<string, ServerItemConfig & ResourceConditions>
+  databases?: Record<string, DatabaseItemConfig & ResourceConditions>
+  cache?: CacheConfig
+  cdn?: Record<string, CdnItemConfig & ResourceConditions> | CdnItemConfig
+  fileSystem?: Record<string, FileSystemItemConfig>
+  apiGateway?: ApiGatewayConfig
+  messaging?: MessagingConfig
+  queues?: Record<string, QueueItemConfig & ResourceConditions>
+  realtime?: RealtimeConfig
+  dns?: DnsConfig
+  security?: SecurityConfig
+  monitoring?: MonitoringConfig
+  api?: ApiConfig
+  loadBalancer?: LoadBalancerConfig
+  ssl?: SslConfig
+  streaming?: Record<string, {
+    name?: string
+    shardCount?: number
+    retentionPeriod?: number
+    encryption?: boolean | string
+  }>
+  machineLearning?: {
+    sagemakerEndpoint?: string
+    modelBucket?: string
+    sagemaker?: {
+      endpointName?: string
+      instanceType?: string
+      endpoints?: Array<{
+        name?: string
+        modelName?: string
+        modelS3Path?: string
+        instanceType?: string
+        instanceCount?: number
+        initialInstanceCount?: number
+        autoScaling?: {
+          minInstances?: number
+          maxInstances?: number
+          targetInvocationsPerInstance?: number
+        }
+      }>
+      trainingJobs?: Array<{
+        name?: string
+        algorithmSpecification?: {
+          trainingImage?: string
+          trainingInputMode?: string
+        }
+        instanceType?: string
+        instanceCount?: number
+        volumeSizeInGB?: number
+        maxRuntimeInSeconds?: number
+      }>
+    }
+  }
+  analytics?: {
+    enabled?: boolean
+    firehose?: Record<string, {
+      name?: string
+      destination?: string
+      bufferSize?: number
+      bufferInterval?: number
+    }>
+    athena?: {
+      database?: string
+      workgroup?: string
+      outputLocation?: string
+      outputBucket?: string
+      tables?: Array<{
+        name?: string
+        location?: string
+        format?: string
+        partitionKeys?: string[]
+      }>
+    }
+    glue?: {
+      crawlers?: Array<{
+        name?: string
+        databaseName?: string
+        s3Targets?: string[]
+        schedule?: string
+      }>
+      jobs?: Array<{
+        name?: string
+        scriptLocation?: string
+        role?: string
+        maxCapacity?: number
+        timeout?: number
+      }>
+    }
+  }
+  workflow?: {
+    pipelines?: Array<{
+      name?: string
+      type?: 'stepFunctions' | string
+      definition?: Record<string, unknown>
+      schedule?: string
+    }>
+  }
+}
+/**
+ * Conditions that determine if a resource should be deployed
+ */
+export declare interface ResourceConditions {
+  environments?: EnvironmentType[]
+  requiresFeatures?: string[]
+  regions?: string[]
+  condition?: (config: CloudConfig, env: EnvironmentType) => boolean
+}
+export declare interface SiteConfig {
+  root: string
+  path?: string
+  domain?: string
+  certificateArn?: string
+  build?: string
+}
+export declare interface VpcConfig {
+  cidr?: string
+  zones?: number
+  availabilityZones?: number
+  natGateway?: boolean
+  natGateways?: number | boolean
+}
+export declare interface StorageConfig {
+  buckets?: BucketConfig[]
+}
+export declare interface BucketConfig {
+  name: string
+  public?: boolean
+  versioning?: boolean
+  website?: boolean
+  encryption?: boolean
+}
+export declare interface DatabaseConfig {
+  type?: 'rds' | 'dynamodb'
+  engine?: 'postgres' | 'mysql'
+  instanceType?: string
+}
+export declare interface CacheConfig {
+  type?: 'redis' | 'memcached'
+  nodeType?: string
+  redis?: {
+    nodeType?: string
+    numCacheNodes?: number
+    engine?: string
+    engineVersion?: string
+    port?: number
+    parameterGroup?: Record<string, string>
+    snapshotRetentionLimit?: number
+    snapshotWindow?: string
+    automaticFailoverEnabled?: boolean
+  }
+  elasticache?: {
+    nodeType?: string
+    numCacheNodes?: number
+    engine?: string
+    engineVersion?: string
+  }
+}
+export declare interface CdnConfig {
+  enabled?: boolean
+  customDomain?: string
+  certificateArn?: string
+}
+export declare interface DnsConfig {
+  domain?: string
+  hostedZoneId?: string
+  provider?: 'route53' | 'cloudflare' | 'porkbun' | 'godaddy'
+}
+export declare interface SecurityConfig {
+  waf?: WafConfig
+  kms?: boolean
+  certificate?: {
+    domain: string
+    subdomains?: string[]
+    validationMethod?: 'DNS' | 'EMAIL'
+  }
+  securityGroups?: Record<string, {
+    ingress?: Array<{
+      port: number
+      protocol: string
+      cidr?: string
+      source?: string
+    }>
+    egress?: Array<{
+      port: number
+      protocol: string
+      cidr?: string
+      destination?: string
+    }>
+  }>
+}
+export declare interface WafConfig {
+  enabled?: boolean
+  blockCountries?: string[]
+  blockIps?: string[]
+  rateLimit?: number
+  rules?: string[]
+}
+export declare interface MonitoringConfig {
+  alarms?: Record<string, AlarmItemConfig> | AlarmItemConfig[]
+  dashboards?: boolean
+  dashboard?: {
+    name?: string
+    widgets?: Array<{
+      type?: string
+      metrics?: string[] | Array<{
+        service?: string
+        metric?: string
+      }>
+    }>
+  }
+  logs?: {
+    retention?: number
+    groups?: string[]
+  }
+}
+export declare interface AlarmConfig {
+  name: string
+  metric: string
+  threshold: number
+}
+export declare interface AlarmItemConfig {
+  name?: string
+  metric?: string
+  metricName?: string
+  namespace?: string
+  threshold: number
+  comparisonOperator?: string
+  period?: number
+  evaluationPeriods?: number
+  service?: string
+}
+export declare interface StorageItemConfig {
+  public?: boolean
+  versioning?: boolean
+  encryption?: boolean
+  encrypted?: boolean
+  website?: boolean | {
+    indexDocument?: string
+    errorDocument?: string
+  }
+  type?: 'efs' | 's3'
+  intelligentTiering?: boolean
+  cors?: Array<{
+    allowedOrigins?: string[]
+    allowedMethods?: string[]
+    allowedHeaders?: string[]
+    maxAge?: number
+  }>
+  lifecycleRules?: Array<{
+    id?: string
+    enabled?: boolean
+    expirationDays?: number
+    transitions?: Array<{
+      days?: number
+      storageClass?: string
+    }>
+  }>
+  performanceMode?: string
+  throughputMode?: string
+  lifecyclePolicy?: {
+    transitionToIA?: number
+  }
+}
+export declare interface FunctionConfig {
+  handler?: string
+  runtime?: string
+  code?: string
+  timeout?: number
+  memorySize?: number
+  memory?: number
+  events?: Array<{
+    type?: string
+    path?: string
+    method?: string
+    queueName?: string
+    streamName?: string
+    tableName?: string
+    expression?: string
+    batchSize?: number
+    startingPosition?: string
+    parallelizationFactor?: number
+    bucket?: string
+    prefix?: string
+    suffix?: string
+  }>
+  environment?: Record<string, string>
+}
+/**
+ * Elastic File System (EFS) configuration
+ */
+export declare interface FileSystemItemConfig {
+  performanceMode?: 'generalPurpose' | 'maxIO' | string
+  throughputMode?: 'bursting' | 'provisioned' | string
+  encrypted?: boolean
+  lifecyclePolicy?: {
+    transitionToIA?: number
+  }
+  mountPath?: string
+}
+/**
+ * Server/VM Instance Configuration
+ */
+export declare interface ServerItemConfig {
+  size?: InstanceSize
+  image?: string
+  startupScript?: string
+}
+/**
+ * Instance configuration for mixed instance fleets
+ */
+export declare interface InstanceConfig {
+  size: InstanceSize
+  weight?: number
+  spot?: boolean
+  maxPrice?: string
+}
+/**
+ * Compute Configuration
+ * Defines the virtual machines/instances for your application
+ *
+ * @example Single instance
+ * compute: {
+ *   instances: 1,
+ *   size: 'small',
+ * }
+ *
+ * @example Multiple instances (auto-enables load balancer)
+ * compute: {
+ *   instances: 3,
+ *   size: 'medium',
+ *   autoScaling: { min: 2, max: 10 },
+ * }
+ *
+ * @example Mixed instance fleet for cost optimization
+ * compute: {
+ *   instances: 3,
+ *   fleet: [
+ *     { size: 'small', weight: 1 },
+ *     { size: 'medium', weight: 2 },
+ *     { size: 'small', weight: 1, spot: true },
+ *   ],
+ * }
+ */
+export declare interface ContainerItemConfig {
+  cpu?: number
+  memory?: number
+  port?: number
+  healthCheck?: string
+  desiredCount?: number
+  autoScaling?: {
+    min?: number
+    max?: number
+    targetCpuUtilization?: number
+    targetMemoryUtilization?: number
+  }
+}
+export declare interface ComputeConfig {
+  mode?: 'server' | 'serverless'
+  instances?: number
+  size?: InstanceSize
+  fleet?: InstanceConfig[]
+  image?: string
+  server?: {
+    instanceType?: string
+    ami?: string
+    keyPair?: string
+    autoScaling?: {
+      min?: number
+      max?: number
+      desired?: number
+      targetCPU?: number
+      scaleUpCooldown?: number
+      scaleDownCooldown?: number
+    }
+    loadBalancer?: {
+      type?: string
+      healthCheck?: {
+        path?: string
+        interval?: number
+        timeout?: number
+        healthyThreshold?: number
+        unhealthyThreshold?: number
+      }
+      stickySession?: {
+        enabled?: boolean
+        duration?: number
+      }
+    }
+    userData?: string | {
+      packages?: string[]
+      commands?: string[]
+    }
+  }
+  serverless?: {
+    cpu?: number
+    memory?: number
+    desiredCount?: number
+  }
+  fargate?: {
+    taskDefinition?: {
+      cpu?: string
+      memory?: string
+      containerDefinitions?: Array<{
+        name?: string
+        image?: string
+        portMappings?: Array<{
+          containerPort?: number
+        }>
+        environment?: unknown[]
+        secrets?: unknown[]
+      }>
+    }
+    service?: {
+      desiredCount?: number
+      healthCheck?: {
+        path?: string
+        interval?: number
+        timeout?: number
+        healthyThreshold?: number
+        unhealthyThreshold?: number
+      }
+      serviceDiscovery?: {
+        enabled?: boolean
+        namespace?: string
+      }
+      autoScaling?: {
+        min?: number
+        max?: number
+        targetCPU?: number
+        targetMemory?: number
+      }
+    }
+    loadBalancer?: {
+      type?: string
+      customDomain?: {
+        domain?: string
+        certificateArn?: string
+      }
+    }
+  }
+  services?: Array<{
+    name: string
+    type?: string
+    taskDefinition?: {
+      cpu?: string
+      memory?: string
+      containerDefinitions?: Array<{
+        name?: string
+        image?: string
+        portMappings?: Array<{
+          containerPort?: number
+        }>
+        healthCheck?: {
+          command?: string[]
+          interval?: number
+          timeout?: number
+          retries?: number
+        }
+      }>
+    }
+    service?: {
+      desiredCount?: number
+      serviceDiscovery?: {
+        enabled?: boolean
+        namespace?: string
+      }
+      autoScaling?: {
+        min?: number
+        max?: number
+        targetCPU?: number
+      }
+    }
+  }>
+  autoScaling?: {
+    /** Minimum number of instances @default 1 */
+    min?: number
+    /** Maximum number of instances @default instances value */
+    max?: number
+    /** Desired number of instances @default instances value */
+    desired?: number
+    /** CPU threshold to scale up (%) @default 70 */
+    scaleUpThreshold?: number
+    /** CPU threshold to scale down (%) @default 30 */
+    scaleDownThreshold?: number
+    /** Cooldown in seconds @default 300 */
+    cooldown?: number
+  }
+  disk?: {
+    /** Size in GB @default 20 */
+    size?: number
+    /** Disk type @default 'ssd' */
+    type?: 'standard' | 'ssd' | 'premium'
+    /** Enable encryption @default true */
+    encrypted?: boolean
+  }
+  sshKey?: string
+  monitoring?: boolean
+  spotConfig?: {
+    /** Base capacity that must be on-demand @default 1 */
+    baseCapacity?: number
+    /** % of instances above base that are on-demand @default 100 */
+    onDemandPercentage?: number
+    /** Allocation strategy @default 'capacity-optimized' */
+    strategy?: 'lowest-price' | 'capacity-optimized'
+  }
+}
+export declare interface DatabaseItemConfig {
+  engine?: 'dynamodb' | 'postgres' | 'mysql'
+  partitionKey?: string | { name: string; type: string }
+  sortKey?: string | { name: string; type: string }
+  username?: string
+  password?: string
+  storage?: number
+  instanceClass?: string
+  version?: string
+  allocatedStorage?: number
+  maxAllocatedStorage?: number
+  multiAZ?: boolean
+  backupRetentionDays?: number
+  preferredBackupWindow?: string
+  preferredMaintenanceWindow?: string
+  deletionProtection?: boolean
+  streamEnabled?: boolean
+  pointInTimeRecovery?: boolean
+  billingMode?: string
+  parameters?: Record<string, string | number>
+  databaseName?: string
+  enablePerformanceInsights?: boolean
+  performanceInsightsRetention?: number
+  tables?: Record<string, {
+    name?: string
+    partitionKey?: string | { name: string; type: string }
+    sortKey?: string | { name: string; type: string }
+    billing?: string
+    billingMode?: string
+    streamEnabled?: boolean
+    pointInTimeRecovery?: boolean
+    globalSecondaryIndexes?: Array<{
+      name: string
+      partitionKey: { name: string; type: string }
+      sortKey?: { name: string; type: string }
+      projection: string
+    }>
+  }>
+}
+export declare interface CdnItemConfig {
+  origin?: string
+  customDomain?: string | {
+    domain: string
+    certificateArn?: string
+  }
+  certificateArn?: string
+  domain?: string
+  enabled?: boolean
+  cachePolicy?: {
+    minTTL?: number
+    defaultTTL?: number
+    maxTTL?: number
+  }
+  minTTL?: number
+  defaultTTL?: number
+  maxTTL?: number
+  compress?: boolean
+  http3?: boolean
+  errorPages?: Record<number | string, string>
+  origins?: Array<{
+    type?: string
+    pathPattern?: string
+    domainName?: string
+    originId?: string
+  }>
+  edgeFunctions?: Array<{
+    eventType?: string
+    functionArn?: string
+    name?: string
+  }>
+}
+/**
+ * Lambda trigger configuration for SQS queues
+ */
+export declare interface QueueLambdaTrigger {
+  functionName: string
+  batchSize?: number
+  batchWindow?: number
+  reportBatchItemFailures?: boolean
+  maxConcurrency?: number
+  filterPattern?: Record<string, unknown>
+}
+/**
+ * CloudWatch alarm configuration for SQS queues
+ */
+export declare interface QueueAlarms {
+  enabled?: boolean
+  queueDepthThreshold?: number
+  messageAgeThreshold?: number
+  dlqAlarm?: boolean
+  notificationTopicArn?: string
+  notificationEmails?: string[]
+}
+/**
+ * SNS subscription configuration for SQS queues
+ */
+export declare interface QueueSnsSubscription {
+  topicArn?: string
+  topicName?: string
+  filterPolicy?: Record<string, string[]>
+  filterPolicyScope?: 'MessageAttributes' | 'MessageBody'
+  rawMessageDelivery?: boolean
+}
+/**
+ * Queue (SQS) Configuration
+ * Defines message queue settings for async processing
+ *
+ * @example Standard queue with Lambda trigger
+ * queues: {
+ *   orders: {
+ *     visibilityTimeout: 60,
+ *     deadLetterQueue: true,
+ *     trigger: {
+ *       functionName: 'processOrders',
+ *       batchSize: 10,
+ *     },
+ *   }
+ * }
+ *
+ * @example FIFO queue with alarms
+ * queues: {
+ *   transactions: {
+ *     fifo: true,
+ *     contentBasedDeduplication: true,
+ *     alarms: {
+ *       enabled: true,
+ *       queueDepthThreshold: 500,
+ *       notificationEmails: ['ops@example.com'],
+ *     },
+ *   }
+ * }
+ *
+ * @example Queue subscribed to SNS topic
+ * queues: {
+ *   notifications: {
+ *     subscribe: {
+ *       topicArn: 'arn:aws:sns:us-east-1:123456789:events',
+ *       filterPolicy: { eventType: ['user.created'] },
+ *     },
+ *   }
+ * }
+ */
+export declare interface QueueItemConfig {
+  fifo?: boolean
+  visibilityTimeout?: number
+  messageRetentionPeriod?: number
+  delaySeconds?: number
+  maxMessageSize?: number
+  receiveMessageWaitTime?: number
+  deadLetterQueue?: boolean
+  maxReceiveCount?: number
+  contentBasedDeduplication?: boolean
+  encrypted?: boolean
+  kmsKeyId?: string
+  trigger?: QueueLambdaTrigger
+  alarms?: QueueAlarms
+  subscribe?: QueueSnsSubscription
+  tags?: Record<string, string>
+}
+/**
+ * Server mode configuration (ts-broadcasting)
+ * High-performance Bun WebSocket server for EC2/ECS deployments
+ */
+export declare interface RealtimeServerConfig {
+  host?: string
+  port?: number
+  scheme?: 'ws' | 'wss'
+  driver?: 'bun' | 'reverb' | 'pusher' | 'ably'
+  idleTimeout?: number
+  maxPayloadLength?: number
+  backpressureLimit?: number
+  closeOnBackpressureLimit?: boolean
+  sendPings?: boolean
+  perMessageDeflate?: boolean
+  redis?: RealtimeRedisConfig
+  rateLimit?: RealtimeRateLimitConfig
+  encryption?: RealtimeEncryptionConfig
+  webhooks?: RealtimeWebhooksConfig
+  queue?: RealtimeQueueConfig
+  loadManagement?: RealtimeLoadConfig
+  metrics?: boolean | {
+    enabled: boolean
+    path?: string
+  }
+  healthCheckPath?: string
+  instances?: number
+  autoScaling?: {
+    min?: number
+    max?: number
+    targetCPU?: number
+    targetConnections?: number
+  }
+}
+/**
+ * Redis configuration for ts-broadcasting horizontal scaling
+ */
+export declare interface RealtimeRedisConfig {
+  enabled?: boolean
+  host?: string
+  port?: number
+  password?: string
+  database?: number
+  url?: string
+  keyPrefix?: string
+  useElastiCache?: boolean
+}
+/**
+ * Rate limiting for WebSocket connections
+ */
+export declare interface RealtimeRateLimitConfig {
+  enabled?: boolean
+  max?: number
+  window?: number
+  perChannel?: boolean
+  perUser?: boolean
+}
+/**
+ * Message encryption configuration
+ */
+export declare interface RealtimeEncryptionConfig {
+  enabled?: boolean
+  algorithm?: 'aes-256-gcm' | 'aes-128-gcm'
+  keyRotationInterval?: number
+}
+/**
+ * Webhook notifications for realtime events
+ */
+export declare interface RealtimeWebhooksConfig {
+  enabled?: boolean
+  endpoints?: {
+    /**
+     * Called when a client connects
+     */
+    connection?: string
+
+    /**
+     * Called when a client subscribes to a channel
+     */
+    subscribe?: string
+
+    /**
+     * Called when a client unsubscribes
+     */
+    unsubscribe?: string
+
+    /**
+     * Called when a client disconnects
+     */
+    disconnect?: string
+
+    /**
+     * Custom event webhooks
+     */
+    [event: string]: string | undefined
+  }
+}
+/**
+ * Queue configuration for background broadcasting
+ */
+export declare interface RealtimeQueueConfig {
+  enabled?: boolean
+  defaultQueue?: string
+  retry?: {
+    attempts?: number
+    backoff?: {
+      type: 'fixed' | 'exponential'
+      delay: number
+    }
+  }
+  deadLetter?: {
+    enabled?: boolean
+    maxRetries?: number
+  }
+}
+/**
+ * Load management for server mode
+ */
+export declare interface RealtimeLoadConfig {
+  enabled?: boolean
+  maxConnections?: number
+  maxSubscriptionsPerConnection?: number
+  shedLoadThreshold?: number
+}
+/**
+ * Channel authorization configuration
+ */
+export declare interface RealtimeChannelAuth {
+  functionName?: string
+  endpoint?: string
+  jwtSecret?: string
+  tokenExpiration?: number
+}
+/**
+ * Presence channel configuration
+ */
+export declare interface RealtimePresenceConfig {
+  enabled?: boolean
+  maxMembers?: number
+  heartbeatInterval?: number
+  inactivityTimeout?: number
+}
+/**
+ * Connection storage configuration
+ */
+export declare interface RealtimeStorageConfig {
+  type?: 'dynamodb' | 'elasticache'
+  dynamodb?: {
+    /**
+     * Billing mode for DynamoDB
+     * @default 'PAY_PER_REQUEST'
+     */
+    billingMode?: 'PAY_PER_REQUEST' | 'PROVISIONED'
+
+    /**
+     * Read capacity units (only for PROVISIONED)
+     * @default 5
+     */
+    readCapacity?: number
+
+    /**
+     * Write capacity units (only for PROVISIONED)
+     * @default 5
+     */
+    writeCapacity?: number
+
+    /**
+     * Enable point-in-time recovery
+     * @default false
+     */
+    pointInTimeRecovery?: boolean
+
+    /**
+     * TTL for connection records (seconds)
+     * @default 86400 (24 hours)
+     */
+    connectionTTL?: number
+  }
+  elasticache?: {
+    /**
+     * Node type for Redis cluster
+     * @default 'cache.t3.micro'
+     */
+    nodeType?: string
+
+    /**
+     * Number of cache nodes
+     * @default 1
+     */
+    numNodes?: number
+  }
+}
+/**
+ * WebSocket scaling configuration
+ */
+export declare interface RealtimeScalingConfig {
+  maxConnections?: number
+  messagesPerSecond?: number
+  handlerMemory?: number
+  handlerTimeout?: number
+  provisionedConcurrency?: number
+}
+/**
+ * Realtime monitoring and alarms
+ */
+export declare interface RealtimeMonitoringConfig {
+  enabled?: boolean
+  connectionThreshold?: number
+  errorThreshold?: number
+  latencyThreshold?: number
+  notificationTopicArn?: string
+  notificationEmails?: string[]
+}
+/**
+ * Realtime event hooks
+ */
+export declare interface RealtimeHooksConfig {
+  onConnect?: string
+  onDisconnect?: string
+  onMessage?: string
+  onSubscribe?: string
+  onUnsubscribe?: string
+}
+/**
+ * Realtime (WebSocket) Configuration
+ * Provides Laravel Echo / Pusher-compatible broadcasting
+ *
+ * @example Serverless mode (API Gateway WebSocket)
+ * realtime: {
+ *   enabled: true,
+ *   mode: 'serverless',
+ *   channels: { public: true, private: true, presence: true },
+ * }
+ *
+ * @example Server mode (ts-broadcasting on EC2/ECS)
+ * realtime: {
+ *   enabled: true,
+ *   mode: 'server',
+ *   server: {
+ *     port: 6001,
+ *     redis: { enabled: true, host: 'redis.example.com' },
+ *     rateLimit: { max: 100, window: 60000 },
+ *   },
+ * }
+ *
+ * @example Production server mode with clustering
+ * realtime: {
+ *   enabled: true,
+ *   mode: 'server',
+ *   server: {
+ *     port: 6001,
+ *     instances: 3,
+ *     redis: { enabled: true, useElastiCache: true },
+ *     autoScaling: { min: 2, max: 10, targetCPU: 70 },
+ *     metrics: true,
+ *   },
+ *   channels: { public: true, private: true, presence: true },
+ * }
+ *
+ * @example Integration with Stacks.js
+ * // In your Stacks app:
+ * import { Broadcast } from '@stacksjs/broadcast'
+ *
+ * // Broadcast to a channel
+ * Broadcast.channel('orders').emit('order.created', { id: 123 })
+ *
+ * // Client-side (similar to Laravel Echo)
+ * Echo.channel('orders').listen('order.created', (e) => {
+ *   console.log('New order:', e.id)
+ * })
+ *
+ * // Private channel
+ * Echo.private(`user.${userId}`).listen('notification', (e) => {
+ *   console.log('Private notification:', e)
+ * })
+ *
+ * // Presence channel
+ * Echo.join('chat-room')
+ *   .here((users) => console.log('Online:', users))
+ *   .joining((user) => console.log('Joined:', user))
+ *   .leaving((user) => console.log('Left:', user))
+ */
+export declare interface RealtimeConfig {
+  enabled?: boolean
+  mode?: RealtimeMode
+  name?: string
+  server?: RealtimeServerConfig
+  channels?: {
+    /**
+     * Enable public channels (no auth required)
+     * @default true
+     */
+    public?: boolean
+
+    /**
+     * Enable private channels (requires auth)
+     * @default true
+     */
+    private?: boolean
+
+    /**
+     * Enable presence channels (track online users)
+     * @default false
+     */
+    presence?: boolean | RealtimePresenceConfig
+  }
+  auth?: RealtimeChannelAuth
+  storage?: RealtimeStorageConfig
+  scaling?: RealtimeScalingConfig
+  monitoring?: RealtimeMonitoringConfig
+  hooks?: RealtimeHooksConfig
+  customDomain?: string
+  certificateArn?: string
+  keepAlive?: boolean
+  keepAliveInterval?: number
+  idleTimeout?: number
+  maxMessageSize?: number
+  compression?: boolean
+  tags?: Record<string, string>
+}
+export declare interface ApiConfig {
+  enabled?: boolean
+  name?: string
+}
+/**
+ * Load Balancer Configuration
+ * Controls whether and how traffic is load balanced
+ */
+export declare interface LoadBalancerConfig {
+  enabled?: boolean
+  type?: 'application' | 'network'
+  healthCheck?: {
+    path?: string
+    interval?: number
+    timeout?: number
+    healthyThreshold?: number
+    unhealthyThreshold?: number
+  }
+  idleTimeout?: number
+  accessLogs?: {
+    enabled?: boolean
+    bucket?: string
+    prefix?: string
+  }
+}
+/**
+ * SSL/TLS Configuration
+ * Supports both AWS ACM certificates and Let's Encrypt
+ */
+export declare interface SslConfig {
+  enabled?: boolean
+  provider?: 'acm' | 'letsencrypt'
+  certificateArn?: string
+  domains?: string[]
+  redirectHttp?: boolean
+  letsEncrypt?: {
+    /**
+     * Email for Let's Encrypt notifications
+     */
+    email?: string
+
+    /**
+     * Use staging server for testing
+     * @default false
+     */
+    staging?: boolean
+
+    /**
+     * Auto-renew certificates
+     * @default true
+     */
+    autoRenew?: boolean
+  }
+}
+export type CloudOptions = Partial<CloudConfig>
+/**
+ * Deployment mode (optional)
+ * @deprecated Mode is now auto-detected from your infrastructure configuration.
+ * Simply define the resources you need (functions, servers, storage, etc.) and
+ * ts-cloud will deploy them accordingly. No need to specify a mode.
+ */
+export type DeploymentMode = 'server' | 'serverless' | 'hybrid'
+export type EnvironmentType = 'production' | 'staging' | 'development'
+/**
+ * Instance size presets
+ * Provider-agnostic sizing that maps to appropriate instance types
+ */
+export type InstanceSize = | 'nano'      // ~0.5 vCPU, 0.5GB RAM
+  | 'micro'     // ~1 vCPU, 1GB RAM
+  | 'small'     // ~1 vCPU, 2GB RAM
+  | 'medium'    // ~2 vCPU, 4GB RAM
+  | 'large'     // ~2 vCPU, 8GB RAM
+  | 'xlarge'    // ~4 vCPU, 16GB RAM
+  | '2xlarge'   // ~8 vCPU, 32GB RAM
+  | (string & {})
+/**
+ * Realtime deployment mode
+ * - 'serverless': Uses API Gateway WebSocket + Lambda (auto-scales, pay-per-use)
+ * - 'server': Uses ts-broadcasting Bun WebSocket server on EC2/ECS (lowest latency)
+ */
+export type RealtimeMode = 'serverless' | 'server'