fix: peer dependency ranges state what the code needs

AGENTS.md

@@ -38,8 +38,8 @@ a private original.
 
    ```bash
    npm i @adaptivestone/framework-module-resize
-   # SQS task queue only: npm i @aws-sdk/client-sqs
-   # S3 storage only:     npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+   # SQS task queue only: npm i @aws-sdk/client-sqs   (>= 3.572)
+   # S3 storage only:     npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner   (>= 3.572)
    ```
 
 2. Scaffold the integration files (never overwrites existing files; `--force` to regenerate):

CHANGELOG.md

@@ -191,6 +191,11 @@ Pending changes since 0.2.1. The release version will be chosen when these chang
 - Host adoption documentation uses a generic checklist without internal project names or paths.
 - The resolved config object is validated once instead of on every `getResizeConfig()` call, so
   the read path no longer re-runs full validation per `resolve()`.
+- Optional peer ranges state what the code needs instead of `*`: `@adaptivestone/framework`
+  `^5.1.0`, `mongoose` `^9.0.0`, and the AWS SDK clients `^3.572.0`. `SqsTaskQueue` reads attempt
+  counts from `MessageSystemAttributeNames`, which older `@aws-sdk/client-sqs` versions silently
+  drop: every delivery then counted as attempt 1, so a failing task was never dead-lettered. It
+  now also warns once when SQS returns no `ApproximateReceiveCount`.
 
 # 0.2.1
 

README.md

@@ -32,12 +32,14 @@ part that uses it:
 
 | You use | Also install |
 |---|---|
-| `…/framework.js` (framework apps) | `@adaptivestone/framework` `mongoose` (already in a framework app) |
-| `…/drivers/mongo.js` | `mongoose` |
-| `S3Storage` (`…/drivers/s3.js`) | `@aws-sdk/client-s3` `@aws-sdk/s3-request-presigner` |
-| `SqsTaskQueue` (`…/drivers/sqs.js`) | `@aws-sdk/client-sqs` |
-
-A missing optional peer fails at your own import line, not at the first upload.
+| `…/framework.js` (framework apps) | `@adaptivestone/framework` ≥ 5.1 and `mongoose` 9 (already in a framework app) |
+| `…/drivers/mongo.js` | `mongoose` 9 |
+| S3: `storage: { driver: 's3' }` or `S3Storage` (`…/drivers/s3.js`) | `@aws-sdk/client-s3` `@aws-sdk/s3-request-presigner` ≥ 3.572 |
+| SQS: `queue: { driver: 'sqs' }` or `SqsTaskQueue` (`…/drivers/sqs.js`) | `@aws-sdk/client-sqs` ≥ 3.572 |
+
+A missing optional peer fails at your own import line (or, for a driver chosen in the config, when
+the Resizer first loads it), not at the first upload. An older SQS client does not return receive
+counts, so failing tasks would never be dead-lettered; `SqsTaskQueue` warns if that happens.
 
 ## Quick start (framework, eager)
 

package.json

@@ -54,11 +54,11 @@
     "sharp": "^0.35.3"
   },
   "peerDependencies": {
-    "@adaptivestone/framework": "^5.0.1",
-    "@aws-sdk/client-s3": "*",
-    "@aws-sdk/client-sqs": "*",
-    "@aws-sdk/s3-request-presigner": "*",
-    "mongoose": "*"
+    "@adaptivestone/framework": "^5.1.0",
+    "@aws-sdk/client-s3": "^3.572.0",
+    "@aws-sdk/client-sqs": "^3.572.0",
+    "@aws-sdk/s3-request-presigner": "^3.572.0",
+    "mongoose": "^9.0.0"
   },
   "peerDependenciesMeta": {
     "@adaptivestone/framework": {
@@ -78,15 +78,15 @@
     }
   },
   "devDependencies": {
-    "@adaptivestone/framework": "^5.1.0",
-    "@aws-sdk/client-s3": "^3.0.0",
-    "@aws-sdk/client-sqs": "^3.1079.0",
-    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@adaptivestone/framework": "^5.5.0",
+    "@aws-sdk/client-s3": "^3.1146.0",
+    "@aws-sdk/client-sqs": "^3.1146.0",
+    "@aws-sdk/s3-request-presigner": "^3.1146.0",
     "@biomejs/biome": "^2.5.2",
     "@types/express": "^5.0.6",
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.6.4",
     "mongodb-memory-server": "^11.0.0",
-    "mongoose": "^9.0.0",
+    "mongoose": "^9.11.0",
     "typescript": "^7.0.2"
   }
 }

src/drivers/sqs.test.ts

@@ -117,6 +117,7 @@ const newTask = (over: Partial<NewTask> = {}): NewTask => ({
 const message = (over: Partial<FakeMessage> = {}): FakeMessage => ({
   MessageId: 'mid',
   ReceiptHandle: 'rh',
+  Attributes: { ApproximateReceiveCount: '1' },
   Body: JSON.stringify({
     mediaId: 'm1',
     pipeline: 'photo',
@@ -410,6 +411,31 @@ describe('SqsTaskQueue.claim', () => {
     assert.equal(task.queue, 'bulk');
     assert.equal(task.attempts, 1);
   });
+  test('no ApproximateReceiveCount (a client before 3.572) reads as attempt 1 and warns once', async () => {
+    const bare = { ...message(), Attributes: undefined };
+    const { client } = makeFakeSqsClient({
+      outputs: {
+        ReceiveMessageCommand: [{ Messages: [bare] }, { Messages: [bare] }],
+      },
+    });
+    const warnings: unknown[][] = [];
+    const tasks = new SqsTaskQueue({
+      queueUrl: 'q',
+      client,
+      logger: {
+        info() {},
+        warn: (...args: unknown[]) => warnings.push(args),
+        error() {},
+      },
+    });
+    assert.equal((await tasks.claim('default', 60_000))?.attempts, 1);
+    assert.equal((await tasks.claim('default', 60_000))?.attempts, 1);
+    assert.equal(warnings.length, 1);
+    assert.match(
+      String(warnings[0][0]),
+      /never dead-lettered.*client-sqs >= 3\.572/,
+    );
+  });
   test('long-polls 10 seconds by default, and the queue named in the body wins', async () => {
     const { client, receiveParams } = makeFakeSqsClient({
       message: message({

src/drivers/sqs.ts

@@ -68,6 +68,7 @@ const isLostReceipt = (err: unknown): boolean => {
 export class SqsTaskQueue extends TaskQueue {
   readonly #opts: SqsTaskQueueOptions;
   #client: SQSClient | undefined;
+  #warnedNoReceiveCount = false;
 
   constructor(opts: SqsTaskQueueOptions) {
     super();
@@ -165,6 +166,15 @@ export class SqsTaskQueue extends TaskQueue {
       await this.#discard(queueUrl, message, 'malformed task body');
       return null;
     }
+    const receiveCount = message.Attributes?.ApproximateReceiveCount;
+    if (receiveCount === undefined && !this.#warnedNoReceiveCount) {
+      // Clients before @aws-sdk/client-sqs 3.572 drop MessageSystemAttributeNames: every delivery
+      // then reads as attempt 1, so a failing task would be retried forever.
+      this.#warnedNoReceiveCount = true;
+      this.#logger.warn(
+        'resize sqs: ReceiveMessage returned no ApproximateReceiveCount — attempts cannot be counted, so failing tasks are never dead-lettered; use @aws-sdk/client-sqs >= 3.572',
+      );
+    }
     return {
       taskId: message.MessageId ?? message.ReceiptHandle,
       resizer: body.resizer ?? 'default',
@@ -174,7 +184,7 @@ export class SqsTaskQueue extends TaskQueue {
       previews: body.previews ?? [],
       // The URL travels with the token: complete/fail/renew act on the queue it came from.
       token: JSON.stringify([queueUrl, message.ReceiptHandle]),
-      attempts: Number(message.Attributes?.ApproximateReceiveCount ?? 1),
+      attempts: Number(receiveCount ?? 1),
     };
   }