stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/config-ref/http-api-gateway.md

@@ -0,0 +1,149 @@
+---
+docType: config-ref
+title: Http Api Gateway
+resourceType: http-api-gateway
+tags:
+  - http-api-gateway
+  - api-gateway
+  - apigateway
+  - gateway
+  - api
+source: types/stacktape-config/http-api-gateways.d.ts
+priority: 1
+---
+
+# Http Api Gateway
+
+Serverless HTTP API with pay-per-request pricing (~$1/million requests).
+
+Routes HTTP requests to Lambda functions, containers, or other backends.
+No servers to manage. Includes built-in throttling, CORS, and TLS.
+
+Resource type: `http-api-gateway`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Serverless HTTP API with pay-per-request pricing (~$1/million requests).
+ *
+ * ---
+ *
+ * Routes HTTP requests to Lambda functions, containers, or other backends.
+ * No servers to manage. Includes built-in throttling, CORS, and TLS.
+ */
+interface HttpApiGateway {
+  type: 'http-api-gateway';
+  properties?: HttpApiGatewayProps;
+  overrides?: ResourceOverrides;
+}
+
+interface HttpApiGatewayProps {
+  /**
+   * #### Lambda event payload format. `2.0` is simpler and recommended for new projects.
+   *
+   * ---
+   *
+   * Only used if not overridden at the integration level.
+   */
+  payloadFormat?: '1.0' | '2.0';
+  /**
+   * #### CORS settings. Overrides any CORS headers from your application code.
+   */
+  cors?: HttpApiCorsConfig;
+  /**
+   * #### Access logging (request ID, IP, method, status, etc.). Viewable with `stacktape logs`.
+   */
+  logging?: HttpApiAccessLogsConfig;
+  /**
+   * #### Custom domains (e.g., `api.example.com`). Stacktape auto-creates DNS records and TLS certificates.
+   *
+   * ---
+   *
+   * Your domain must be added as a Route53 hosted zone in your AWS account first.
+   */
+  customDomains?: DomainConfiguration[];
+  /**
+   * #### Put a CDN (CloudFront) in front of this API for caching and lower latency worldwide.
+   */
+  cdn?: CdnConfiguration;
+  /**
+   * #### Alarms for this API Gateway (merged with global alarms from the Stacktape Console).
+   */
+  alarms?: HttpApiGatewayAlarm[];
+  /**
+   * #### Global alarm names to exclude from this API Gateway.
+   */
+  disabledGlobalAlarms?: string[];
+}
+
+interface HttpApiAccessLogsConfig extends LogForwardingBase {
+  /**
+   * #### Disable access logging.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * #### Log format. Logs include: requestId, IP, method, status, protocol, responseLength.
+   * @default JSON
+   */
+  format?: 'CLF' | 'JSON' | 'XML' | 'CSV';
+  /**
+   * #### How many days to keep logs.
+   * @default 30
+   */
+  retentionDays?: 1 | 3 | 5 | 7 | 14 | 30 | 60 | 90 | 120 | 150 | 180 | 365 | 400 | 545 | 731 | 1827 | 3653;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | '*';
+
+interface HttpApiCorsConfig {
+  /**
+   * #### Enable CORS. With no other options, uses permissive defaults (`*` origins, common headers).
+   * @default false
+   */
+  enabled: boolean;
+  /**
+   * #### Allowed origins (e.g., `https://myapp.com`). Use `*` for any origin.
+   * @default ["*"]
+   */
+  allowedOrigins?: string[];
+  /**
+   * #### Allowed request headers in CORS preflight.
+   */
+  allowedHeaders?: string[];
+  /**
+   * #### Allowed HTTP methods. Auto-detected from integrations if not set.
+   */
+  allowedMethods?: HttpMethod[];
+  /**
+   * #### Allow cookies/auth headers in cross-origin requests.
+   */
+  allowCredentials?: boolean;
+  /**
+   * #### Response headers accessible to browser JavaScript.
+   */
+  exposedResponseHeaders?: string[];
+  /**
+   * #### How long (seconds) browsers can cache preflight responses.
+   */
+  maxAge?: number;
+}
+
+type HttpApiGatewayReferencableParam =
+  | 'domain'
+  | 'customDomains'
+  | 'url'
+  | 'customDomainUrl'
+  | 'customDomainUrls'
+  | 'canonicalDomain'
+  | CdnReferenceableParam;
+
+type HttpApiGatewayOutputs = {
+  integrations: {
+    url: string | IntrinsicFunction;
+    method: string;
+    resourceName: string;
+  }[];
+};
+```

package/ai-docs/config-ref/http-endpoint.md

@@ -0,0 +1,92 @@
+---
+docType: config-ref
+title: Log Forwarding Base
+resourceType: http-endpoint
+tags:
+  - http-endpoint
+source: types/stacktape-config/log-forwarding.d.ts
+priority: 1
+---
+
+# Log Forwarding Base
+
+Resource type: `http-endpoint`
+
+## TypeScript Definition
+
+```typescript
+interface LogForwardingBase {
+  /**
+   * #### Forward logs to an external service (Datadog, Highlight.io, or any HTTP endpoint).
+   *
+   * ---
+   *
+   * Uses Kinesis Data Firehose (~$0.03/GB). Failed deliveries go to a backup S3 bucket.
+   */
+  logForwarding?: HttpEndpointLogForwarding | HighlightLogForwarding | DatadogLogForwarding;
+}
+
+interface HttpEndpointLogForwarding {
+  type: 'http-endpoint';
+  properties: HttpEndpointLogForwardingProps;
+}
+
+interface HttpEndpointLogForwardingProps {
+  /**
+   * #### HTTPS endpoint URL where logs are sent.
+   */
+  endpointUrl: string;
+  /**
+   * #### Compress request body with GZIP to reduce transfer costs.
+   * @default false
+   */
+  gzipEncodingEnabled?: boolean;
+  /**
+   * #### Extra metadata sent in the `X-Amz-Firehose-Common-Attributes` header.
+   */
+  parameters?: { [paramName: string]: string };
+  /**
+   * #### Total retry time (seconds) before sending failed logs to a backup S3 bucket.
+   * @default 300
+   */
+  retryDuration?: number;
+  /**
+   * #### Auth credential sent in `X-Amz-Firehose-Access-Key` header. Store as `$Secret()` for security.
+   */
+  accessKey?: string;
+}
+
+interface HighlightLogForwarding {
+  type: 'highlight';
+  properties: HighlightLogForwardingProps;
+}
+
+interface HighlightLogForwardingProps {
+  /**
+   * #### Your Highlight.io project ID (from the Highlight console).
+   */
+  projectId: string;
+  /**
+   * #### Highlight.io endpoint. Override for self-hosted or regional endpoints.
+   * @default "https://pub.highlight.io/v1/logs/firehose"
+   */
+  endpointUrl?: string;
+}
+
+interface DatadogLogForwarding {
+  type: 'datadog';
+  properties: DatadogLogForwardingProps;
+}
+
+interface DatadogLogForwardingProps {
+  /**
+   * #### Your Datadog API key. Store as `$Secret()` for security.
+   */
+  apiKey: string;
+  /**
+   * #### Datadog endpoint. Use the EU URL if your account is in the EU region.
+   * @default "https://aws-kinesis-http-intake.logs.datadoghq.com/v1/input"
+   */
+  endpointUrl?: string;
+}
+```

package/ai-docs/config-ref/kinesis-stream.md

@@ -0,0 +1,97 @@
+---
+docType: config-ref
+title: Kinesis Stream
+resourceType: kinesis-stream
+tags:
+  - kinesis-stream
+  - kinesis
+  - streaming
+source: types/stacktape-config/kinesis-streams.d.ts
+priority: 1
+---
+
+# Kinesis Stream
+
+Real-time data stream for ingesting high-volume events (logs, clickstreams, IoT, analytics).
+
+Continuously captures data from many producers. Consumers (Lambda functions, etc.) process records in order.
+Use when you need real-time processing with sub-second latency, not just async messaging (use SQS for that).
+
+Resource type: `kinesis-stream`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Real-time data stream for ingesting high-volume events (logs, clickstreams, IoT, analytics).
+ *
+ * ---
+ *
+ * Continuously captures data from many producers. Consumers (Lambda functions, etc.) process records in order.
+ * Use when you need real-time processing with sub-second latency, not just async messaging (use SQS for that).
+ */
+interface KinesisStream {
+  type: 'kinesis-stream';
+  properties?: KinesisStreamProps;
+  overrides?: ResourceOverrides;
+}
+
+interface KinesisStreamProps {
+  /**
+   * #### How the stream scales.
+   *
+   * ---
+   *
+   * - **`ON_DEMAND`**: Auto-scales, pay per GB. Recommended for most use cases.
+   * - **`PROVISIONED`**: You choose a fixed number of shards (1 MB/s write, 2 MB/s read each). More predictable costs.
+   *
+   * @default "ON_DEMAND"
+   */
+  capacityMode?: 'ON_DEMAND' | 'PROVISIONED';
+  /**
+   * #### Number of shards. Only used when `capacityMode` is `PROVISIONED`.
+   *
+   * ---
+   *
+   * Each shard: 1 MB/s write (1,000 records/s), 2 MB/s read (shared across consumers).
+   *
+   * @default 1
+   */
+  shardCount?: number;
+  /**
+   * #### How long records stay in the stream (hours). Range: 24–8,760 (365 days). Beyond 24h costs extra.
+   *
+   * @default 24
+   */
+  retentionPeriodHours?: number;
+  /**
+   * #### Encrypt data at rest using a KMS key.
+   */
+  encryption?: KinesisStreamEncryption;
+  /**
+   * #### Give each consumer its own dedicated 2 MB/s read throughput (instead of sharing).
+   *
+   * ---
+   *
+   * Use when you have multiple consumers reading from the same stream and need low latency.
+   * Enhanced fan-out consumers are auto-created when a Lambda uses `autoCreateConsumer: true`.
+   *
+   * @default false
+   */
+  enableEnhancedFanOut?: boolean;
+}
+
+interface KinesisStreamEncryption {
+  /**
+   * #### Enable server-side encryption.
+   * @default false
+   */
+  enabled: boolean;
+  /**
+   * #### ARN of your own KMS key. If omitted, uses the AWS-managed `alias/aws/kinesis` key (no extra cost).
+   */
+  kmsKeyArn?: string;
+}
+
+type KinesisStreamReferencableParam = 'arn' | 'name';
+```

package/ai-docs/config-ref/mongo-db-atlas-cluster.md

@@ -0,0 +1,254 @@
+---
+docType: config-ref
+title: Mongo Db Atlas Cluster
+resourceType: mongo-db-atlas-cluster
+tags:
+  - mongo-db-atlas-cluster
+  - mongodb
+  - mongo
+source: types/stacktape-config/mongo-db-atlas-clusters.d.ts
+priority: 1
+---
+
+# Mongo Db Atlas Cluster
+
+Managed MongoDB database (Atlas) deployed into your AWS account and managed within your stack.
+
+Document database with flexible schemas — great for content management, user profiles, catalogs, and apps
+where your data model evolves. Starts at M2 (shared, ~$9/month) or M10 (dedicated, ~$57/month).
+
+Resource type: `mongo-db-atlas-cluster`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Managed MongoDB database (Atlas) deployed into your AWS account and managed within your stack.
+ *
+ * ---
+ *
+ * Document database with flexible schemas — great for content management, user profiles, catalogs, and apps
+ * where your data model evolves. Starts at M2 (shared, ~$9/month) or M10 (dedicated, ~$57/month).
+ */
+interface MongoDbAtlasCluster {
+  type: 'mongo-db-atlas-cluster';
+  properties: MongoDbAtlasClusterProps;
+}
+
+interface MongoDbAtlasClusterProps {
+  /**
+   * #### Disk size in GB. Not available for shared tiers (M2/M5). M10+ auto-scales storage by default.
+   */
+  diskSizeGB?: number;
+  /**
+   * #### Instance size. M2/M5 = shared (cheapest). M10+ = dedicated (more features, auto-scaling, backups).
+   */
+  clusterTier:
+    | 'M2'
+    | 'M5'
+    | 'M10'
+    | 'M20'
+    | 'M30'
+    | 'M40'
+    | 'M40 Low-CPU (R40)'
+    | 'M40_NVME'
+    | 'M50'
+    | 'M50 Low-CPU (R50)'
+    | 'M50_NVME'
+    | 'M60'
+    | 'M60 Low-CPU (R60)'
+    | 'M60_NVME'
+    | 'M80'
+    | 'M80 Low-CPU (R80)'
+    | 'M80_NVME'
+    | 'M100'
+    | 'M140'
+    | 'M200'
+    | 'M200 Low-CPU (R200)'
+    | 'M200_NVME'
+    | 'M300'
+    | 'M300 Low-CPU (R300)'
+    | 'M400'
+    | 'M400 Low-CPU (R400)'
+    | 'M400_NVME'
+    | 'M700'
+    | 'M700 Low-CPU (R700)';
+  /**
+   * #### MongoDB engine version.
+   * @default "7.0"
+   */
+  version?: '5.0' | '6.0' | '7.0';
+  /**
+   * #### Number of shards. More than 1 enables sharded mode for horizontal scaling. Requires M30+.
+   * @default 1
+   */
+  numShards?: number;
+  /**
+   * #### Node count configuration: electable, read-only, and analytics nodes. Default: 3 electable nodes.
+   */
+  replication?: MongoDbReplication;
+  /**
+   * #### Enable daily snapshots (18:00 UTC). M10+ only — M2/M5 get automatic snapshots with different rules.
+   */
+  enableBackups?: boolean;
+  /**
+   * #### Restore to any second within the last 7 days. Requires `enableBackups: true` and M10+.
+   */
+  enablePointInTimeRecovery?: boolean;
+  /**
+   * #### BI Connector for SQL-based access to MongoDB data. CPU-intensive — may degrade M10/M20 performance.
+   */
+  biConnector?: MongoDbBiConnector;
+  /**
+   * #### Auto-scale tier and/or storage based on CPU/memory usage. Set min/max tier to control costs.
+   *
+   * ---
+   *
+   * Scales up when CPU or memory exceeds 75% for 1 hour. Scales down when both are below 50% for 24 hours.
+   */
+  autoScaling?: MongoDbAutoScaling;
+  /**
+   * #### Admin user for direct database access (e.g., from your local machine or admin tools).
+   *
+   * ---
+   *
+   * Not required for app-to-database access via `connectTo` — that's handled automatically.
+   */
+  adminUserCredentials?: MongoDbAdminUserCredentials;
+}
+
+interface MongoDbReplication {
+  /**
+   * #### Read-only nodes for long-running analytics queries. Prevents impact on primary workload performance.
+   */
+  numAnalyticsNodes?: number;
+  /**
+   * #### Nodes that can become primary. More = better redundancy. Must be odd.
+   * @default 3
+   */
+  numElectableNodes?: 3 | 5 | 7;
+  /**
+   * #### Read-only replica nodes for scaling read throughput.
+   */
+  numReadOnlyNodes?: number;
+}
+
+interface MongoDbBiConnector {
+  /**
+   * #### Which node type the BI Connector reads from. Use `analytics` to avoid impacting production queries.
+   */
+  readPreference?: 'primary' | 'secondary' | 'analytics';
+  /**
+   * #### Enable the BI Connector for SQL-based access.
+   * @default false
+   */
+  enabled: boolean;
+}
+
+interface MongoDbAutoScaling {
+  /**
+   * #### Lowest tier the cluster can scale down to. Prevents unexpected cost increases from always scaling up.
+   */
+  minClusterTier?:
+    | 'M10'
+    | 'M20'
+    | 'M30'
+    | 'M40'
+    | 'M40 Low-CPU (R40)'
+    | 'M40_NVME'
+    | 'M50'
+    | 'M50 Low-CPU (R50)'
+    | 'M50_NVME'
+    | 'M60'
+    | 'M60 Low-CPU (R60)'
+    | 'M60_NVME'
+    | 'M80'
+    | 'M80 Low-CPU (R80)'
+    | 'M80_NVME'
+    | 'M100'
+    | 'M140'
+    | 'M200'
+    | 'M200 Low-CPU (R200)'
+    | 'M200_NVME'
+    | 'M300'
+    | 'M300 Low-CPU (R300)'
+    | 'M400 Low-CPU (R400)'
+    | 'M400_NVME'
+    | 'M700 Low-CPU (R700)';
+  /**
+   * #### Highest tier the cluster can scale up to. Set a ceiling to control maximum costs.
+   */
+  maxClusterTier?:
+    | 'M10'
+    | 'M20'
+    | 'M30'
+    | 'M40'
+    | 'M40 Low-CPU (R40)'
+    | 'M40_NVME'
+    | 'M50'
+    | 'M50 Low-CPU (R50)'
+    | 'M50_NVME'
+    | 'M60'
+    | 'M60 Low-CPU (R60)'
+    | 'M60_NVME'
+    | 'M80'
+    | 'M80 Low-CPU (R80)'
+    | 'M80_NVME'
+    | 'M100'
+    | 'M140'
+    | 'M200'
+    | 'M200 Low-CPU (R200)'
+    | 'M200_NVME'
+    | 'M300'
+    | 'M300 Low-CPU (R300)'
+    | 'M400 Low-CPU (R400)'
+    | 'M400_NVME'
+    | 'M700 Low-CPU (R700)';
+  /**
+   * #### Prevent automatic disk expansion. By default, storage grows when usage hits 90%. Storage never scales down.
+   */
+  disableDiskScaling?: boolean;
+  /**
+   * #### Prevent automatic scale-down. The cluster can only scale up, never back down to a smaller tier.
+   */
+  disableScaleDown?: boolean;
+}
+
+interface MongoDbAdminUserCredentials {
+  /**
+   * #### Name of the admin user
+   */
+  userName: string;
+  /**
+   * #### Password for the admin user
+   */
+  password: string;
+}
+
+interface MongoDbAtlasAccessibility {
+  /**
+   * #### Network access mode.
+   *
+   * ---
+   *
+   * - **`internet`**: Accessible from anywhere (credentials still required).
+   * - **`vpc`**: Only from resources in your VPC + any `whitelistedIps`.
+   * - **`scoping-workloads-in-vpc`**: Like `vpc`, but also requires security-group access via `connectTo`.
+   * - **`whitelisted-ips-only`**: Only from IP addresses listed in `whitelistedIps`.
+   *
+   * @default internet
+   */
+  accessibilityMode: 'internet' | 'vpc' | 'scoping-workloads-in-vpc' | 'whitelisted-ips-only';
+  /**
+   * #### IP addresses or CIDR ranges allowed to access the cluster (e.g., your office IP).
+   *
+   * ---
+   *
+   * No effect in `internet` mode. In `vpc`/`scoping-workloads-in-vpc`, adds access for IPs outside the VPC.
+   * In `whitelisted-ips-only`, these are the only IPs that can connect.
+   */
+  whitelistedIps?: string[];
+}
+
+type MongoDbAtlasClusterReferencableParam = 'connectionString';
+```