eoapi-cdk 8.1.0 → 8.2.0

package/.jsii

@@ -4170,7 +4170,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "lib/database/index.ts",
-        "line": 292
+        "line": 295
       },
       "name": "DatabaseParameters",
       "properties": [
@@ -4183,7 +4183,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 308
+            "line": 311
           },
           "name": "effectiveCacheSize",
           "type": {
@@ -4199,7 +4199,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 318
+            "line": 321
           },
           "name": "maintenanceWorkMem",
           "type": {
@@ -4215,7 +4215,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 296
+            "line": 299
           },
           "name": "maxConnections",
           "type": {
@@ -4231,7 +4231,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 323
+            "line": 326
           },
           "name": "maxLocksPerTransaction",
           "type": {
@@ -4247,7 +4247,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 338
+            "line": 341
           },
           "name": "randomPageCost",
           "type": {
@@ -4263,7 +4263,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 333
+            "line": 336
           },
           "name": "seqPageCost",
           "type": {
@@ -4280,7 +4280,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 303
+            "line": 306
           },
           "name": "sharedBuffers",
           "type": {
@@ -4296,7 +4296,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 328
+            "line": 331
           },
           "name": "tempBuffers",
           "type": {
@@ -4312,7 +4312,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 313
+            "line": 316
           },
           "name": "workMem",
           "type": {
@@ -4582,7 +4582,7 @@
         },
         "locationInModule": {
           "filename": "lib/database/index.ts",
-          "line": 43
+          "line": 44
         },
         "parameters": [
           {
@@ -4617,7 +4617,7 @@
           },
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 191
+            "line": 194
           },
           "name": "getParameters",
           "parameters": [
@@ -4656,7 +4656,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 39
+            "line": 40
           },
           "name": "connectionTarget",
           "type": {
@@ -4679,7 +4679,21 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 41
+            "line": 39
+          },
+          "name": "pgstacVersion",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/database/index.ts",
+            "line": 42
           },
           "name": "secretBootstrapper",
           "optional": true,
@@ -4694,7 +4708,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 40
+            "line": 41
           },
           "name": "securityGroup",
           "optional": true,
@@ -4744,7 +4758,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "lib/database/index.ts",
-        "line": 231
+        "line": 234
       },
       "name": "PgStacDatabaseProps",
       "properties": [
@@ -4758,7 +4772,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 265
+            "line": 268
           },
           "name": "addPgbouncer",
           "optional": true,
@@ -4776,7 +4790,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 289
+            "line": 292
           },
           "name": "bootstrapperLambdaFunctionOptions",
           "optional": true,
@@ -4794,7 +4808,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 280
+            "line": 283
           },
           "name": "customResourceProperties",
           "optional": true,
@@ -4817,7 +4831,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 272
+            "line": 275
           },
           "name": "pgbouncerInstanceProps",
           "optional": true,
@@ -4835,7 +4849,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 237
+            "line": 240
           },
           "name": "pgstacDbName",
           "optional": true,
@@ -4853,7 +4867,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 258
+            "line": 261
           },
           "name": "pgstacUsername",
           "optional": true,
@@ -4871,7 +4885,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 244
+            "line": 247
           },
           "name": "pgstacVersion",
           "optional": true,
@@ -4889,7 +4903,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/database/index.ts",
-            "line": 251
+            "line": 254
           },
           "name": "secretsPrefix",
           "optional": true,
@@ -5444,6 +5458,560 @@
       ],
       "symbolId": "lib/ingestor-api/index:StacIngestorProps"
     },
+    "eoapi-cdk.StacItemLoader": {
+      "assembly": "eoapi-cdk",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "The StacItemLoader creates a serverless, event-driven system for loading\nSTAC (SpatioTemporal Asset Catalog) items into a PostgreSQL database with\nthe pgstac extension. This construct supports multiple ingestion pathways\nfor flexible STAC item loading.\n\n## Architecture Overview\n\nThis construct creates the following AWS resources:\n- **SNS Topic**: Entry point for STAC items and S3 event notifications\n- **SQS Queue**: Buffers and batches messages before processing (60-second visibility timeout)\n- **Dead Letter Queue**: Captures failed loading attempts after 5 retries\n- **Lambda Function**: Python function that processes batches and inserts items into pgstac\n\n## Data Flow\n\nThe loader supports two primary data ingestion patterns:\n\n### Direct STAC Item Publishing\n1. STAC items (JSON) are published directly to the SNS topic in message bodies\n2. The SQS queue collects messages and batches them (up to {batchSize} items or 1 minute window)\n3. The Lambda function receives batches, validates items, and inserts into pgstac\n\n### S3 Event-Driven Loading\n1. An S3 bucket is configured to send notifications to the SNS topic when json files are created\n2. STAC items are uploaded to S3 buckets as JSON/GeoJSON files\n3. S3 event notifications are sent to the SNS topic when items are uploaded\n4. The Lambda function receives S3 events in the SQS message batch, fetches items from S3, and loads into pgstac\n\n## Batching Behavior\n\nThe SQS-to-Lambda integration uses intelligent batching to optimize performance:\n\n- **Batch Size**: Lambda waits to receive up to `batchSize` messages (default: 500)\n- **Batching Window**: If fewer than `batchSize` messages are available, Lambda\n  triggers after `maxBatchingWindow` minutes (default: 1 minute)\n- **Trigger Condition**: Lambda executes when EITHER condition is met first\n- **Concurrency**: Limited to `maxConcurrency` concurrent executions to prevent database overload\n- **Partial Failures**: Uses `reportBatchItemFailures` to retry only failed items\n\nThis approach balances throughput (larger batches = fewer database connections)\nwith latency (time-based triggers prevent indefinite waiting).\n\n## Error Handling and Dead Letter Queue\n\nFailed messages are sent to the dead letter queue after 5 processing attempts.\n**Important**: This construct provides NO automated handling of dead letter queue\nmessages - monitoring, inspection, and reprocessing of failed items is the\nresponsibility of the implementing application.\n\nConsider implementing:\n- CloudWatch alarms on dead letter queue depth\n- Manual or automated reprocessing workflows\n- Logging and alerting for failed items\n- Regular cleanup of old dead letter messages (14-day retention)\n\n## Operational Characteristics\n\n- **Scalability**: Lambda scales automatically based on queue depth\n- **Reliability**: Dead letter queue captures failures for debugging\n- **Efficiency**: Batching optimizes database operations for high throughput\n- **Security**: Database credentials accessed via AWS Secrets Manager\n- **Observability**: CloudWatch logs retained for one week\n\n## Prerequisites\n\nBefore using this construct, ensure:\n- The pgstac database has collections loaded (items require existing collection IDs)\n- Database credentials are stored in AWS Secrets Manager\n- The pgstac extension is properly installed and configured\n\n## Usage Example\n\n```typescript\n// Create database first\nconst database = new PgStacDatabase(this, 'Database', {\n  pgstacVersion: '0.9.5'\n});\n\n// Create item loader\nconst loader = new StacItemLoader(this, 'ItemLoader', {\n  pgstacDb: database,\n  batchSize: 1000,          // Process up to 1000 items per batch\n  maxBatchingWindowMinutes: 1, // Wait max 1 minute to fill batch\n  lambdaTimeoutSeconds: 300     // Allow up to 300 seconds for database operations\n});\n\n// The topic ARN can be used by other services to publish items\nnew CfnOutput(this, 'LoaderTopicArn', {\n  value: loader.topic.topicArn\n});\n```\n\n## Direct Item Publishing\n\nExternal services can publish STAC items directly to the topic:\n\n```bash\naws sns publish --topic-arn $ITEM_LOAD_TOPIC --message '{\n  \"type\": \"Feature\",\n  \"stac_version\": \"1.0.0\",\n  \"id\": \"example-item\",\n  \"properties\": {\"datetime\": \"2021-01-01T00:00:00Z\"},\n  \"geometry\": {\"type\": \"Polygon\", \"coordinates\": [...]},\n  \"collection\": \"example-collection\"\n}'\n```\n\n## S3 Event Configuration\n\nTo enable S3 event-driven loading, configure S3 bucket notifications to send\nevents to the SNS topic when STAC items (.json or .geojson files) are uploaded:\n\n```typescript\n// Configure S3 bucket to send notifications to the loader topic\nbucket.addEventNotification(\n  s3.EventType.OBJECT_CREATED,\n  new s3n.SnsDestination(loader.topic),\n  { suffix: '.json' }\n);\n\nbucket.addEventNotification(\n  s3.EventType.OBJECT_CREATED,\n  new s3n.SnsDestination(loader.topic),\n  { suffix: '.geojson' }\n);\n```\n\nWhen STAC items are uploaded to the configured S3 bucket, the loader will:\n1. Receive S3 event notifications via SNS\n2. Fetch the STAC item JSON from S3\n3. Validate and load the item into the pgstac database\n\n## Monitoring and Troubleshooting\n\n- Monitor Lambda logs: `/aws/lambda/{FunctionName}`\n- **Dead Letter Queue**: Check for failed items - **no automated handling provided**\n- Use batch item failure reporting for partial batch processing\n- CloudWatch metrics available for queue depth and Lambda performance\n\n### Dead Letter Queue Management\n\nApplications must implement their own dead letter queue monitoring:\n\n```typescript\n// Example: CloudWatch alarm for dead letter queue depth\nnew cloudwatch.Alarm(this, 'DeadLetterAlarm', {\n  metric: loader.deadLetterQueue.metricApproximateNumberOfVisibleMessages(),\n  threshold: 1,\n  evaluationPeriods: 1\n});\n\n// Example: Lambda to reprocess dead letter messages\nconst reprocessFunction = new lambda.Function(this, 'Reprocess', {\n  // Implementation to fetch and republish failed messages\n});\n```",
+        "stability": "experimental",
+        "summary": "AWS CDK Construct for STAC Item Loading Infrastructure."
+      },
+      "fqn": "eoapi-cdk.StacItemLoader",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "locationInModule": {
+          "filename": "lib/stac-item-loader/index.ts",
+          "line": 342
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "type": {
+              "fqn": "eoapi-cdk.StacItemLoaderProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/stac-item-loader/index.ts",
+        "line": 290
+      },
+      "name": "StacItemLoader",
+      "properties": [
+        {
+          "docs": {
+            "remarks": "Messages that fail processing after 5 attempts are sent here\nfor inspection and potential replay. Retains messages for 14 days\nto allow for debugging and manual intervention.\n\n**User Responsibility**: This construct provides NO automated monitoring,\nalerting, or reprocessing of dead letter queue messages. Applications\nusing this construct must implement their own:\n- Dead letter queue depth monitoring and alerting\n- Failed message inspection and debugging workflows\n- Manual or automated reprocessing mechanisms\n- Cleanup procedures for old failed messages",
+            "stability": "experimental",
+            "summary": "Dead letter queue for failed item loading attempts."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 327
+          },
+          "name": "deadLetterQueue",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sqs.Queue"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "This Python function receives batches of messages from SQS and processes\nthem based on their type:\n- Direct STAC items: Validates and loads directly into pgstac\n- S3 events: Fetches STAC items from S3, validates, and loads into pgstac\n\nThe function connects to PostgreSQL using credentials from Secrets Manager\nand uses pypgstac for efficient database operations.",
+            "stability": "experimental",
+            "summary": "The Lambda function that loads STAC items into the pgstac database."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 340
+          },
+          "name": "lambdaFunction",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.Function"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "This queue collects both direct STAC items from SNS and S3 event\nnotifications, batching them for efficient database operations.\nConfigured with a visibility timeout that accommodates Lambda\nprocessing time plus buffer.",
+            "stability": "experimental",
+            "summary": "The SQS queue that buffers messages before processing."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 310
+          },
+          "name": "queue",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sqs.Queue"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "This topic serves as the entry point for two types of events:\n1. Direct STAC item JSON documents published by external services\n2. S3 event notifications when STAC items are uploaded to configured buckets\n\nThe topic fans out to the SQS queue for batched processing.",
+            "stability": "experimental",
+            "summary": "The SNS topic that receives STAC items and S3 event notifications for loading."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 300
+          },
+          "name": "topic",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.Topic"
+          }
+        }
+      ],
+      "symbolId": "lib/stac-item-loader/index:StacItemLoader"
+    },
+    "eoapi-cdk.StacItemLoaderProps": {
+      "assembly": "eoapi-cdk",
+      "datatype": true,
+      "docs": {
+        "example": "const loader = new StacItemLoader(this, 'ItemLoader', {\n  pgstacDb: database,\n  batchSize: 1000,\n  maxBatchingWindowMinutes: 1,\n  lambdaTimeoutSeconds: 300\n});",
+        "remarks": "The StacItemLoader is part of a two-phase serverless STAC ingestion pipeline\nthat loads STAC items into a pgstac database. This construct creates\nthe infrastructure for receiving STAC items from multiple sources:\n1. SNS messages containing STAC metadata (direct ingestion)\n2. S3 event notifications for STAC items uploaded to S3 buckets\n\nItems from both sources are batched and inserted into PostgreSQL with the pgstac extension.",
+        "stability": "experimental",
+        "summary": "Configuration properties for the StacItemLoader construct."
+      },
+      "fqn": "eoapi-cdk.StacItemLoaderProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stac-item-loader/index.ts",
+        "line": 34
+      },
+      "name": "StacItemLoaderProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "This database must have the pgstac extension installed and be properly\nconfigured with collections before items can be loaded. The loader will\nuse AWS Secrets Manager to securely access database credentials.",
+            "stability": "experimental",
+            "summary": "The PgSTAC database instance to load items into."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 42
+          },
+          "name": "pgstacDb",
+          "type": {
+            "fqn": "eoapi-cdk.PgStacDatabase"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "500",
+            "remarks": "This determines the maximum number of STAC items that will be\nprocessed together in a single lambda invocation. Larger batch\nsizes improve database insertion efficiency but require more\nmemory and longer processing time.\n\n**Batching Behavior**: SQS will wait to accumulate up to this many\nmessages before triggering the Lambda, OR until the maxBatchingWindow\ntimeout is reached, whichever comes first. This creates an efficient\nbalance between throughput and latency.",
+            "stability": "experimental",
+            "summary": "SQS batch size for lambda event source."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 92
+          },
+          "name": "batchSize",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "These will be merged with the default environment variables including\nPGSTAC_SECRET_ARN. Use this for custom configuration or debugging flags.",
+            "stability": "experimental",
+            "summary": "Additional environment variables for the lambda function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 126
+          },
+          "name": "environment",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "map"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "lambda.Runtime.PYTHON_3_11",
+            "remarks": "The function is implemented in Python and uses pypgstac for database\noperations. Ensure the runtime version is compatible with the pgstac\nversion specified in the database configuration.",
+            "stability": "experimental",
+            "summary": "The lambda runtime to use for the item loading function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 53
+          },
+          "name": "lambdaRuntime",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.Runtime"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "300",
+            "remarks": "This should accommodate the time needed to process up to `batchSize`\nitems and perform database insertions. The SQS visibility timeout\nwill be set to this value plus 10 seconds.",
+            "stability": "experimental",
+            "summary": "The timeout for the item load lambda in seconds."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 64
+          },
+          "name": "lambdaTimeoutSeconds",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "1",
+            "remarks": "Even if the batch size isn't reached, the lambda will be triggered\nafter this time period to ensure timely processing of items.\nThis prevents items from waiting indefinitely in low-volume scenarios.\n\n**Important**: This timeout works in conjunction with batchSize - SQS\nwill trigger the Lambda when EITHER the batch size is reached OR this\ntime window expires, ensuring items are processed in a timely manner\nregardless of volume.",
+            "stability": "experimental",
+            "summary": "Maximum batching window in minutes."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 108
+          },
+          "name": "maxBatchingWindowMinutes",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "2",
+            "remarks": "This limit will be applied to the Lambda function and will control how\nmany concurrent batches will be released from the SQS queue.",
+            "stability": "experimental",
+            "summary": "Maximum concurrent executions for the StacItemLoader Lambda function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 118
+          },
+          "name": "maxConcurrency",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "1024",
+            "remarks": "Higher memory allocation may improve performance when processing\nlarge batches of STAC items, especially for memory-intensive\ndatabase operations.",
+            "stability": "experimental",
+            "summary": "Memory size for the lambda function in MB."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stac-item-loader/index.ts",
+            "line": 75
+          },
+          "name": "memorySize",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "lib/stac-item-loader/index:StacItemLoaderProps"
+    },
+    "eoapi-cdk.StactoolsItemGenerator": {
+      "assembly": "eoapi-cdk",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "The StactoolsItemGenerator creates a serverless, event-driven system for generating\nSTAC (SpatioTemporal Asset Catalog) items from source data. This construct\nimplements the first phase of a two-stage ingestion pipeline that transforms\nraw geospatial data into standardized STAC metadata.\n\n## Architecture Overview\n\nThis construct creates the following AWS resources:\n- **SNS Topic**: Entry point for triggering item generation workflows\n- **SQS Queue**: Buffers generation requests (120-second visibility timeout)\n- **Dead Letter Queue**: Captures failed messages after 5 processing attempts\n- **Lambda Function**: Containerized function that generates STAC items using stactools\n\n## Data Flow\n\n1. External systems publish ItemRequest messages to the SNS topic with metadata about assets\n2. The SQS queue buffers these messages and triggers the Lambda function\n3. The Lambda function:\n   - Uses `uvx` to install the required stactools package\n   - Executes the `create-item` CLI command with provided arguments\n   - Publishes generated STAC items to the ItemLoad topic\n4. Failed processing attempts are sent to the dead letter queue\n\n## Operational Characteristics\n\n- **Scalability**: Lambda scales automatically based on queue depth (up to maxConcurrency)\n- **Flexibility**: Supports any stactools package through dynamic installation\n- **Reliability**: Dead letter queue captures failed generation attempts\n- **Isolation**: Each generation task runs in a fresh container environment\n- **Observability**: CloudWatch logs retained for one week\n\n## Message Schema\n\nThe function expects messages matching the ItemRequest model:\n\n```json\n{\n  \"package_name\": \"stactools-glad-global-forest-change\",\n  \"group_name\": \"gladglobalforestchange\",\n  \"create_item_args\": [\n    \"https://example.com/data.tif\"\n  ],\n  \"collection_id\": \"glad-global-forest-change-1.11\"\n}\n```\n\n## Usage Example\n\n```typescript\n// Create item loader first (or get existing topic ARN)\nconst loader = new StacItemLoader(this, 'ItemLoader', {\n  pgstacDb: database\n});\n\n// Create item generator that feeds the loader\nconst generator = new StactoolsItemGenerator(this, 'ItemGenerator', {\n  itemLoadTopicArn: loader.topic.topicArn,\n  lambdaTimeoutSeconds: 120,    // Allow time for package installation\n  maxConcurrency: 100,          // Control parallel processing\n  batchSize: 10                 // Process 10 requests per invocation\n});\n\n// Grant permission to publish to the loader topic\nloader.topic.grantPublish(generator.lambdaFunction);\n```\n\n## Publishing Generation Requests\n\nSend messages to the generator topic to trigger item creation:\n\n```bash\naws sns publish --topic-arn $ITEM_GEN_TOPIC --message '{\n  \"package_name\": \"stactools-glad-global-forest-change\",\n  \"group_name\": \"gladglobalforestchange\",\n  \"create_item_args\": [\n    \"https://storage.googleapis.com/earthenginepartners-hansen/GFC-2023-v1.11/Hansen_GFC-2023-v1.11_gain_40N_080W.tif\"\n  ],\n  \"collection_id\": \"glad-global-forest-change-1.11\"\n}'\n```\n\n## Batch Processing Example\n\nFor processing many assets, you can loop through URLs:\n\n```bash\nwhile IFS= read -r url; do\n  aws sns publish --topic-arn \"$ITEM_GEN_TOPIC\" --message \"{\n    \\\"package_name\\\": \\\"stactools-glad-glclu2020\\\",\n    \\\"group_name\\\": \\\"gladglclu2020\\\",\n    \\\"create_item_args\\\": [\\\"$url\\\"]\n  }\"\ndone < urls.txt\n```\n\n## Monitoring and Troubleshooting\n\n- Monitor Lambda logs: `/aws/lambda/{FunctionName}`\n- Check dead letter queue for failed generation attempts\n- Use CloudWatch metrics to track processing rates and errors\n- Failed items can be replayed from the dead letter queue\n\n## Supported Stactools Packages\n\nAny package available on PyPI that follows the stactools plugin pattern\ncan be used. Examples include:\n- `stactools-glad-global-forest-change`\n- `stactools-glad-glclu2020`\n- `stactools-landsat`\n- `stactools-sentinel2`",
+        "see": "{@link https://stactools.readthedocs.io/} for stactools documentation",
+        "stability": "experimental",
+        "summary": "AWS CDK Construct for STAC Item Generation Infrastructure."
+      },
+      "fqn": "eoapi-cdk.StactoolsItemGenerator",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "locationInModule": {
+          "filename": "lib/stactools-item-generator/index.ts",
+          "line": 263
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "type": {
+              "fqn": "eoapi-cdk.StactoolsItemGeneratorProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/stactools-item-generator/index.ts",
+        "line": 227
+      },
+      "name": "StactoolsItemGenerator",
+      "properties": [
+        {
+          "docs": {
+            "remarks": "Messages that fail processing after 5 attempts are sent here for\ninspection and potential replay. This helps with debugging stactools\npackage issues, network failures, or malformed requests.",
+            "stability": "experimental",
+            "summary": "Dead letter queue for failed item generation attempts."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 244
+          },
+          "name": "deadLetterQueue",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sqs.Queue"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "This Docker-based function dynamically installs stactools packages\nusing uvx, processes source data, and publishes generated STAC items\nto the configured ItemLoad SNS topic.",
+            "stability": "experimental",
+            "summary": "The containerized Lambda function that generates STAC items."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 261
+          },
+          "name": "lambdaFunction",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.DockerImageFunction"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "This queue receives messages from the SNS topic containing ItemRequest\npayloads. It's configured with a visibility timeout that matches the\nLambda timeout plus buffer time to prevent duplicate processing.",
+            "stability": "experimental",
+            "summary": "The SQS queue that buffers item generation requests."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 235
+          },
+          "name": "queue",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sqs.Queue"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "External systems publish ItemRequest messages to this topic to trigger\nSTAC item generation. The topic fans out to the SQS queue for processing.",
+            "stability": "experimental",
+            "summary": "The SNS topic that receives item generation requests."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 252
+          },
+          "name": "topic",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.Topic"
+          }
+        }
+      ],
+      "symbolId": "lib/stactools-item-generator/index:StactoolsItemGenerator"
+    },
+    "eoapi-cdk.StactoolsItemGeneratorProps": {
+      "assembly": "eoapi-cdk",
+      "datatype": true,
+      "docs": {
+        "example": "const generator = new StactoolsItemGenerator(this, 'ItemGenerator', {\n  itemLoadTopicArn: loader.topic.topicArn,\n  lambdaTimeoutSeconds: 120,\n  maxConcurrency: 100,\n  batchSize: 10\n});",
+        "remarks": "The StactoolsItemGenerator is part of a two-phase serverless STAC ingestion pipeline\nthat generates STAC items from source data. This construct creates the\ninfrastructure for the first phase of the pipeline - processing metadata\nabout assets and transforming them into standardized STAC items.",
+        "stability": "experimental",
+        "summary": "Configuration properties for the StactoolsItemGenerator construct."
+      },
+      "fqn": "eoapi-cdk.StactoolsItemGeneratorProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stactools-item-generator/index.ts",
+        "line": 31
+      },
+      "name": "StactoolsItemGeneratorProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "This is typically the topic from a StacItemLoader construct.\nGenerated STAC items will be published here for downstream\nprocessing and database insertion.",
+            "stability": "experimental",
+            "summary": "ARN of the SNS topic to publish generated items to."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 107
+          },
+          "name": "itemLoadTopicArn",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "10",
+            "remarks": "This determines how many generation requests are processed together\nin a single lambda invocation. Unlike the loader, generation typically\nprocesses items individually, so smaller batch sizes are common.",
+            "stability": "experimental",
+            "summary": "SQS batch size for lambda event source."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 89
+          },
+          "name": "batchSize",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "These will be merged with default environment variables including\nITEM_LOAD_TOPIC_ARN and LOG_LEVEL. Use this for custom configuration\nor to pass credentials for external data sources.",
+            "stability": "experimental",
+            "summary": "Additional environment variables for the lambda function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 98
+          },
+          "name": "environment",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "map"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "lambda.Runtime.PYTHON_3_11",
+            "remarks": "The function is containerized using Docker and can accommodate various\nstactools packages. The runtime version should be compatible with the\npackages you plan to use for STAC item generation.",
+            "stability": "experimental",
+            "summary": "The lambda runtime to use for the item generation function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 41
+          },
+          "name": "lambdaRuntime",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.Runtime"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "120",
+            "remarks": "This should accommodate the time needed to:\n- Install stactools packages using uvx\n- Download and process source data\n- Generate STAC metadata\n- Publish results to SNS\n\nThe SQS visibility timeout will be set to this value plus 10 seconds.",
+            "stability": "experimental",
+            "summary": "The timeout for the item generation lambda in seconds."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 56
+          },
+          "name": "lambdaTimeoutSeconds",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "100",
+            "remarks": "This controls how many item generation tasks can run simultaneously.\nHigher concurrency enables faster processing of large batches but\nmay strain downstream systems or external data sources.",
+            "stability": "experimental",
+            "summary": "Maximum number of concurrent executions."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 78
+          },
+          "name": "maxConcurrency",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "1024",
+            "remarks": "Higher memory allocation may be needed for processing large geospatial\ndatasets or when stactools packages have high memory requirements.\nMore memory also provides proportionally more CPU power.",
+            "stability": "experimental",
+            "summary": "Memory size for the lambda function in MB."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stactools-item-generator/index.ts",
+            "line": 67
+          },
+          "name": "memorySize",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "lib/stactools-item-generator/index:StactoolsItemGeneratorProps"
+    },
     "eoapi-cdk.TiPgApiLambda": {
       "assembly": "eoapi-cdk",
       "base": "constructs.Construct",
@@ -5915,6 +6483,6 @@
       "symbolId": "lib/titiler-pgstac-api/index:TitilerPgstacApiLambda"
     }
   },
-  "version": "8.1.0",
-  "fingerprint": "P912To9BQxA8vUvBUyuaAexQ0TQFsm0a+p1BQVOsp2Q="
+  "version": "8.2.0",
+  "fingerprint": "JVUml3IdUs10f+0ZGUviU7bZ2hZTYqXC7NyzJiNYy0s="
 }