stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/config-ref/dynamo-db-table.md

@@ -0,0 +1,202 @@
+---
+docType: config-ref
+title: Dynamo Db Table
+resourceType: dynamo-db-table
+tags:
+  - dynamo-db-table
+  - dynamodb
+  - nosql
+  - document-db
+source: types/stacktape-config/dynamo-db-tables.d.ts
+priority: 1
+---
+
+# Dynamo Db Table
+
+Serverless NoSQL database with single-digit millisecond reads/writes at any scale.
+
+No servers to manage, no capacity planning needed (in on-demand mode). Pay per read/write.
+Great for user profiles, session data, IoT data, and any key-value or document workload.
+
+Resource type: `dynamo-db-table`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Serverless NoSQL database with single-digit millisecond reads/writes at any scale.
+ *
+ * ---
+ *
+ * No servers to manage, no capacity planning needed (in on-demand mode). Pay per read/write.
+ * Great for user profiles, session data, IoT data, and any key-value or document workload.
+ */
+interface DynamoDbTable {
+  type: 'dynamo-db-table';
+  properties: DynamoDbTableProps;
+  overrides?: ResourceOverrides;
+}
+
+interface DynamoDbTableProps {
+  /**
+   * #### The primary key that uniquely identifies each item.
+   *
+   * ---
+   *
+   * - **Simple key**: Just a `partitionKey` (e.g., `userId`).
+   * - **Composite key**: `partitionKey` + `sortKey` (e.g., `userId` + `createdAt`).
+   *
+   * > **Cannot be changed after creation.** Every item must include the primary key attribute(s).
+   */
+  primaryKey: DynamoDbTablePrimaryKey;
+  /**
+   * #### Fixed-capacity mode with predictable pricing. Omit for on-demand (pay-per-request) mode.
+   *
+   * ---
+   *
+   * - **On-demand** (default, no config): Pay per read/write. Best for unpredictable or variable traffic.
+   * - **Provisioned**: Set fixed read/write capacity. Cheaper at steady, predictable load. Can auto-scale.
+   */
+  provisionedThroughput?: DynamoDbProvisionedThroughput;
+  /**
+   * #### Enable continuous backups with point-in-time recovery (restore to any second in the last 35 days).
+   *
+   * ---
+   *
+   * Restores always create a new table. Adds ~20% to storage cost.
+   */
+  enablePointInTimeRecovery?: boolean;
+  /**
+   * #### Stream item changes to trigger functions or batch jobs in real time.
+   *
+   * ---
+   *
+   * - `KEYS_ONLY`: Only key attributes of the changed item.
+   * - `NEW_IMAGE`: The full item after the change.
+   * - `OLD_IMAGE`: The full item before the change.
+   * - `NEW_AND_OLD_IMAGES`: Both before and after — useful for change tracking and auditing.
+   */
+  streamType?: 'KEYS_ONLY' | 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES';
+  /**
+   * #### Additional indexes for querying by attributes other than the primary key.
+   *
+   * ---
+   *
+   * Without indexes, you can only query by primary key. Add a secondary index to query by
+   * any attribute (e.g., query orders by `status` or users by `email`).
+   */
+  secondaryIndexes?: DynamoDbTableGlobalSecondaryIndex[];
+  /**
+   * #### Dev mode: runs locally in Docker by default. Set `remote: true` to use the deployed table.
+   */
+  dev?: DevModeConfig;
+}
+
+interface DynamoDbTablePrimaryKey {
+  /**
+   * #### The main key attribute (e.g., `userId`, `orderId`). Must be unique if no sort key is used.
+   */
+  partitionKey: DynamoDbAttribute;
+  /**
+   * #### Optional second key for composite keys. Enables range queries and multiple items per partition key.
+   *
+   * ---
+   *
+   * E.g., partition key `userId` + sort key `createdAt` lets you query all items for a user sorted by date.
+   */
+  sortKey?: DynamoDbAttribute;
+}
+
+interface DynamoDbTableGlobalSecondaryIndex {
+  /**
+   * #### Name of the index (used when querying).
+   */
+  name: string;
+  /**
+   * #### Partition key for this index — the attribute you'll query by.
+   */
+  partitionKey: DynamoDbAttribute;
+  /**
+   * #### Optional sort key for range queries within a partition.
+   */
+  sortKey?: DynamoDbAttribute;
+  /**
+   * #### Extra attributes to copy into the index. Only projected attributes are available when querying.
+   *
+   * ---
+   *
+   * The table's primary key is always projected. List additional attributes you need in query results.
+   */
+  projections?: string[];
+}
+
+interface DynamoDbAttribute {
+  /**
+   * #### Attribute name (e.g., `userId`, `email`, `createdAt`).
+   */
+  name: string;
+  /**
+   * #### Attribute data type: `string`, `number`, or `binary`.
+   */
+  type: 'string' | 'number' | 'binary';
+}
+
+interface DynamoDbProvisionedThroughput {
+  /**
+   * #### Read capacity units per second. 1 unit = one 4 KB strongly consistent read (or two eventually consistent).
+   *
+   * ---
+   *
+   * Requests exceeding this limit get throttled. Use `readScaling` to auto-adjust.
+   */
+  readUnits: number;
+  /**
+   * #### Write capacity units per second. 1 unit = one 1 KB write.
+   *
+   * ---
+   *
+   * Requests exceeding this limit get throttled. Use `writeScaling` to auto-adjust.
+   */
+  writeUnits: number;
+  /**
+   * #### Auto-scale write capacity based on actual usage. Scales up/down between min and max units.
+   */
+  writeScaling?: DynamoDbWriteScaling;
+  /**
+   * #### Auto-scale read capacity based on actual usage. Scales up/down between min and max units.
+   */
+  readScaling?: DynamoDbReadScaling;
+}
+
+interface DynamoDbWriteScaling {
+  /**
+   * #### Minimum write units. Capacity never scales below this.
+   */
+  minUnits: number;
+  /**
+   * #### Maximum write units. Capacity never scales above this.
+   */
+  maxUnits: number;
+  /**
+   * #### Target utilization percentage (e.g., 70). Scales up when usage exceeds this, down when it drops.
+   */
+  keepUtilizationUnder: number;
+}
+
+interface DynamoDbReadScaling {
+  /**
+   * #### Minimum read units. Capacity never scales below this.
+   */
+  minUnits: number;
+  /**
+   * #### Maximum read units. Capacity never scales above this.
+   */
+  maxUnits: number;
+  /**
+   * #### Target utilization percentage (e.g., 70). Scales up when usage exceeds this, down when it drops.
+   */
+  keepUtilizationUnder: number;
+}
+
+type DynamoDBTableReferencableParam = 'name' | 'arn' | 'streamArn';
+```

package/ai-docs/config-ref/edge-lambda-function.md

@@ -0,0 +1,87 @@
+---
+docType: config-ref
+title: Edge Lambda Function
+resourceType: edge-lambda-function
+tags:
+  - edge-lambda-function
+source: types/stacktape-config/edge-lambda-functions.d.ts
+priority: 1
+---
+
+# Edge Lambda Function
+
+Lambda function that runs at CDN edge locations for request/response manipulation.
+
+Runs on CloudFront events (viewer request, origin request, etc.) to modify headers, rewrite URLs,
+implement A/B testing, or add auth checks at the edge. Referenced from CDN `edgeFunctions` config.
+
+Resource type: `edge-lambda-function`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Lambda function that runs at CDN edge locations for request/response manipulation.
+ *
+ * ---
+ *
+ * Runs on CloudFront events (viewer request, origin request, etc.) to modify headers, rewrite URLs,
+ * implement A/B testing, or add auth checks at the edge. Referenced from CDN `edgeFunctions` config.
+ */
+interface EdgeLambdaFunction {
+  type: 'edge-lambda-function';
+  properties: EdgeLambdaFunctionProps;
+  overrides?: ResourceOverrides;
+}
+
+interface EdgeLambdaFunctionProps {
+  /**
+   * #### How the function code is packaged and deployed.
+   */
+  packaging: LambdaPackaging;
+  /**
+   * #### Lambda runtime. Auto-detected from file extension. Edge functions support Node.js and Python only.
+   */
+  runtime?:
+  | 'nodejs24.x'
+  | 'nodejs22.x'
+  | 'nodejs20.x'
+  | 'nodejs18.x'
+  | 'python3.13'
+  | 'python3.12'
+  | 'python3.11'
+  | 'python3.10'
+  | 'python3.9'
+  | 'python3.8';
+  /**
+   * #### Memory in MB. Max depends on event type: viewer events = 128 MB, origin events = 10,240 MB.
+   * @default 128
+   */
+  memory?: number;
+  /**
+   * #### Max execution time in seconds. Viewer events: max 5s. Origin events: max 30s.
+   * @default 3
+   */
+  timeout?: number;
+
+  /**
+   * #### Grant access to other resources in your stack (IAM permissions only — no env vars or VPC access).
+   *
+   * ---
+   *
+   * Edge Lambda functions **cannot** use environment variables or connect to VPC resources.
+   * `connectTo` only sets up IAM permissions (e.g., S3 bucket access, DynamoDB, SES).
+   */
+  connectTo?: string[];
+  /**
+   * #### Custom IAM policy statements for fine-grained AWS permissions beyond what `connectTo` provides.
+   */
+  iamRoleStatements?: StpIamRoleStatement[];
+  /**
+   * #### Logging config. Logs are sent to CloudWatch **in the region where the function executed** (not your stack region).
+   */
+  logging?: LambdaFunctionLogging;
+}
+
+type EdgeLambdaFunctionReferencableParam = 'arn';
+```

package/ai-docs/config-ref/efs-filesystem.md

@@ -0,0 +1,72 @@
+---
+docType: config-ref
+title: Efs Filesystem
+resourceType: efs-filesystem
+tags:
+  - efs-filesystem
+  - efs
+  - filesystem
+  - persistent-storage
+source: types/stacktape-config/efs-filesystem.d.ts
+priority: 1
+---
+
+# Efs Filesystem
+
+Shared file storage that multiple containers can read/write simultaneously.
+
+Persistent, elastic (grows/shrinks automatically), and accessible from any container in your stack
+via `volumeMounts`. Use for shared uploads, CMS media, ML model files, or anything that needs to
+survive container restarts. Pay only for storage used (~$0.30/GB/month for standard access).
+
+Resource type: `efs-filesystem`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Shared file storage that multiple containers can read/write simultaneously.
+ *
+ * ---
+ *
+ * Persistent, elastic (grows/shrinks automatically), and accessible from any container in your stack
+ * via `volumeMounts`. Use for shared uploads, CMS media, ML model files, or anything that needs to
+ * survive container restarts. Pay only for storage used (~$0.30/GB/month for standard access).
+ */
+interface EfsFilesystem {
+  type: 'efs-filesystem';
+  properties?: EfsFilesystemProps;
+  overrides?: ResourceOverrides;
+}
+
+interface EfsFilesystemProps {
+  /**
+   * #### Enable daily automatic backups with 35-day retention. Incremental (only changes are copied).
+   */
+  backupEnabled?: boolean;
+
+  /**
+   * #### How throughput scales with your workload.
+   *
+   * ---
+   *
+   * - **`elastic`** (recommended): Auto-scales throughput. Best for spiky workloads (web apps, CI/CD).
+   * - **`provisioned`**: Fixed throughput you set via `provisionedThroughputInMibps`. Best for steady high-throughput workloads.
+   * - **`bursting`**: Throughput scales with storage size (50 KiB/s per GiB). Can run out of burst credits.
+   *
+   * @default elastic
+   */
+  throughputMode?: 'elastic' | 'provisioned' | 'bursting';
+
+  /**
+   * #### Guaranteed throughput in MiB/s. Required when `throughputMode` is `provisioned`.
+   *
+   * ---
+   *
+   * E.g., `100` = 100 MiB/s. Additional fees apply based on the provisioned amount. Can be changed anytime.
+   */
+  provisionedThroughputInMibps?: number;
+}
+
+type EfsFilesystemReferencableParam = 'arn';
+```

package/ai-docs/config-ref/event-bus.md

@@ -0,0 +1,63 @@
+---
+docType: config-ref
+title: Event Bus
+resourceType: event-bus
+tags:
+  - event-bus
+  - eventbridge
+  - events
+source: types/stacktape-config/event-buses.d.ts
+priority: 1
+---
+
+# Event Bus
+
+Central event bus for decoupling services. Publish events and trigger functions, queues, or batch jobs.
+
+Use to build event-driven architectures where producers and consumers are independent.
+Functions, batch jobs, and other resources can subscribe to specific event patterns.
+
+Resource type: `event-bus`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Central event bus for decoupling services. Publish events and trigger functions, queues, or batch jobs.
+ *
+ * ---
+ *
+ * Use to build event-driven architectures where producers and consumers are independent.
+ * Functions, batch jobs, and other resources can subscribe to specific event patterns.
+ */
+interface EventBus {
+  type: 'event-bus';
+  properties?: EventBusProps;
+  overrides?: ResourceOverrides;
+}
+
+interface EventBusProps {
+  /**
+   * #### Partner event source name. Only needed for receiving events from third-party SaaS integrations.
+   */
+  eventSourceName?: string;
+  /**
+   * #### Archive events to store and replay them later. Useful for debugging, testing, or error recovery.
+   */
+  archivation?: EventBusArchivation;
+}
+
+interface EventBusArchivation {
+  /**
+   * #### Enable event archiving. Disabling deletes the archive.
+   * @default false
+   */
+  enabled: boolean;
+  /**
+   * #### Days to keep archived events. Omit to keep indefinitely.
+   */
+  retentionDays?: number;
+}
+
+type EventBusReferencableParam = 'arn' | 'archiveArn';
+```