unnbound-events 1.0.2 → 1.0.4

package/README.md

@@ -67,7 +67,7 @@ await client.http({ port: 3000 });
 export const handler = client.sqs();
 
 // SQS long-poll listener (env-driven)
-// Env: SQS_QUEUE_URL, AWS_REGION, AWS_SQS_ENDPOINT (optional)
+// Env: UNNBOUND_SQS_QUEUE_URL (or SQS_QUEUE_URL), AWS_REGION, AWS_SQS_ENDPOINT (optional)
 await client.sqsListen();
 ```
 
@@ -94,3 +94,42 @@ interface QueueEnvelope {
   addons?: Record<string, unknown>;
 }
 ```
+
+## Environment Variables
+
+### SQS Configuration
+
+The SDK looks for SQS configuration in this order:
+
+1. **Options passed to `sqsListen()` or `start()`**
+2. **Environment variables** (in order of preference):
+   - `UNNBOUND_SQS_QUEUE_URL` (custom Unnbound variable)
+   - `SQS_QUEUE_URL` (standard variable)
+   - `QUEUE_URL` (fallback)
+
+**Required:**
+
+- `UNNBOUND_SQS_QUEUE_URL` or `SQS_QUEUE_URL` - The SQS queue URL
+
+**Optional:**
+
+- `AWS_REGION` - AWS region (defaults to `us-east-1`)
+- `AWS_SQS_ENDPOINT` - Custom SQS endpoint (for LocalStack, etc.)
+
+**Example:**
+
+```bash
+export UNNBOUND_SQS_QUEUE_URL="https://sqs.us-west-2.amazonaws.com/123456789012/my-queue"
+export AWS_REGION="us-west-2"
+```
+
+### AWS Credentials
+
+When running in ECS with a Task Role, no additional credentials are needed. The AWS SDK will automatically use the ECS Task Role credentials.
+
+For local development or other environments, set:
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+```

package/dist/lib/client.js

@@ -196,12 +196,20 @@ function createEventsClient() {
             }
             const env = globalThis
                 .process?.env ?? {};
-            const queueUrl = options?.queueUrl || env.SQS_QUEUE_URL || env.QUEUE_URL;
+            const queueUrl = options?.queueUrl || env.UNNBOUND_SQS_QUEUE_URL || env.SQS_QUEUE_URL || env.QUEUE_URL;
             if (!queueUrl || queueUrl === undefined) {
-                throw new Error('SQS queue URL not provided. Set SQS_QUEUE_URL env or pass options.queueUrl');
+                throw new Error('SQS queue URL not provided. Set UNNBOUND_SQS_QUEUE_URL, SQS_QUEUE_URL env or pass options.queueUrl');
             }
             const region = options?.region || env.AWS_REGION || 'us-east-1';
             const endpoint = env.AWS_SQS_ENDPOINT || env.AWS_ENDPOINT_URL || undefined;
+            // Log SQS configuration for debugging
+            unnbound_logger_sdk_1.logger.info({
+                queueUrl: queueUrl.replace(/\/[^/]+$/, '/***'), // Mask queue name for security
+                region,
+                endpoint,
+                hasCredentials: !!(env.AWS_ACCESS_KEY_ID || env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI),
+                executionEnv: env.AWS_EXECUTION_ENV,
+            }, 'Starting SQS listener');
             const waitTimeSeconds = options?.waitTimeSeconds ?? 10;
             const maxMessages = options?.maxMessages ?? 10;
             const visibilityTimeout = options?.visibilityTimeoutSeconds;
@@ -247,11 +255,31 @@ function createEventsClient() {
             // Start async loop without awaiting
             // eslint-disable-next-line @typescript-eslint/no-floating-promises
             loop();
-            return Promise.resolve({
-                stop() {
-                    stopped = true;
-                    return Promise.resolve();
-                },
+            // Test the SQS connection immediately to catch early errors
+            return new Promise((resolve, reject) => {
+                const testConnection = async () => {
+                    try {
+                        const testParams = {
+                            QueueUrl: queueUrl,
+                            MaxNumberOfMessages: 1,
+                            WaitTimeSeconds: 0, // Don't wait, just test connection
+                        };
+                        await sqs.send(new awsSqs.ReceiveMessageCommand(testParams));
+                        unnbound_logger_sdk_1.logger.info('SQS connection test successful');
+                        resolve({
+                            stop() {
+                                stopped = true;
+                                return Promise.resolve();
+                            },
+                        });
+                    }
+                    catch (error) {
+                        unnbound_logger_sdk_1.logger.error({ err: error, queueUrl: queueUrl.replace(/\/[^/]+$/, '/***') }, 'SQS connection test failed');
+                        reject(error instanceof Error ? error : new Error(String(error)));
+                    }
+                };
+                // Run connection test after a short delay to allow the async loop to start
+                setTimeout(testConnection, 100);
             });
         },
         async start(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-events",
   "description": "Unified events SDK to handle HTTP routes and SQS messages with a single routing API.",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {