@friggframework/core 2.0.0--canary.652.60de836.0 → 2.0.0--canary.653.af34bd7.0

package/CLAUDE.md

@@ -414,6 +414,43 @@ const decrypted = await cryptor.decrypt(encrypted);
 - `integration-event-dispatcher.js` - Routes events to integration handlers
 - Supports lifecycle events and user actions
 
+**Queue handler delivery**: a handler dispatched from the integration queue
+(any `this.events` entry reached through SQS, including `ON_WEBHOOK` and
+scheduled jobs) receives `{ data, context, delivery }`. HTTP-dispatched
+handlers (`{ req, res, next }`) and `this.on` events do not.
+
+| Field | Type | Value |
+|---|---|---|
+| `delivery.receiveCount` | `number \| undefined` | SQS `ApproximateReceiveCount` of this delivery |
+| `delivery.maxReceiveCount` | `number \| undefined` | Receives allowed before SQS moves the message to the DLQ (`FRIGG_QUEUE_MAX_RECEIVE_COUNT`) |
+| `delivery.isLastAttempt` | `boolean` | `true` only when both counts are known and `receiveCount >= maxReceiveCount` |
+
+`isLastAttempt` is `false` when either count is unknown: a local or non-SQS
+invocation, or a queue whose redrive policy the stack does not own
+(`ownership.queue: 'external'`). The value is information only: core still
+rethrows retryable errors and discards halt errors (4xx except 408/429).
+
+Use it to end a run or count lost work on the final try: when a retryable
+error (429, 5xx, network) is about to be rethrown and `isLastAttempt` is
+`true`, the message goes to the DLQ next, so mark the run failed or count the
+message's records as failed before rethrowing.
+
+```javascript
+async processBatch({ data, delivery }) {
+    try {
+        await this.syncPage(data);
+    } catch (error) {
+        if (delivery?.isLastAttempt) await this.failRun(data.processId, error);
+        throw error;
+    }
+}
+```
+
+The single source of the max receive count is
+`INTEGRATION_QUEUE_MAX_RECEIVE_COUNT` in `queues/queue-delivery.js`. The
+devtools integration builder uses it for the queue's `RedrivePolicy` and sets
+it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
+
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.
@@ -662,6 +699,7 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
 - `DEBUG` - Debug logging pattern
 - `LOG_LEVEL` - Logging level (debug, info, warn, error)
+- `FRIGG_QUEUE_MAX_RECEIVE_COUNT` - Set by devtools on integration queue workers whose queue the stack owns; feeds `delivery.maxReceiveCount`
 
 ## Version Information
 

package/core/CLAUDE.md

@@ -52,9 +52,10 @@ const handler = createHandler({
 **Usage Pattern**:
 ```javascript
 class MyWorker extends Worker {
-    async _run(params, context = {}) {
+    async _run(params, context = {}, delivery) {
         // Your job processing logic here
         // params are already JSON.parsed from SQS message body
+        // delivery is { receiveCount, maxReceiveCount, isLastAttempt } (see ../CLAUDE.md "Queue handler delivery")
     }
     
     _validateParams(params) {

package/core/Worker.js

@@ -2,6 +2,7 @@ const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
+const { readQueueDelivery } = require('../queues/queue-delivery');
 
 const sqs = new SQSClient({ region: process.env.AWS_REGION });
 
@@ -42,7 +43,7 @@ class Worker {
             try {
                 const runParams = JSON.parse(record.body);
                 this._validateParams(runParams);
-                await this._run(runParams, context);
+                await this._run(runParams, context, readQueueDelivery(record));
                 console.log(`[Worker] record success`, {
                     messageId: record.messageId,
                     event: runParams?.event,

package/handlers/backend-utils.js

@@ -164,7 +164,7 @@ const createQueueWorker = (integrationClass) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
-        async _run(params, context) {
+        async _run(params, context, delivery) {
             const logCtx = {
                 integration: integrationName,
                 event: params.event,
@@ -254,6 +254,7 @@ const createQueueWorker = (integrationClass) => {
                     event: params.event,
                     data: params.data,
                     context: context,
+                    delivery,
                 });
                 console.log(
                     `[QueueWorker] ${params.event} dispatched ok`,

package/handlers/integration-event-dispatcher.js

@@ -18,9 +18,9 @@ class IntegrationEventDispatcher {
         );
     }
 
-    async dispatchJob({ event, data, context }) {
+    async dispatchJob({ event, data, context, delivery }) {
         return this._dispatch(event, (instance, handler) =>
-            handler.call(instance, { data, context })
+            handler.call(instance, { data, context, delivery })
         );
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.652.60de836.0",
+    "version": "2.0.0--canary.653.af34bd7.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.652.60de836.0",
-        "@friggframework/prettier-config": "2.0.0--canary.652.60de836.0",
-        "@friggframework/test": "2.0.0--canary.652.60de836.0",
+        "@friggframework/eslint-config": "2.0.0--canary.653.af34bd7.0",
+        "@friggframework/prettier-config": "2.0.0--canary.653.af34bd7.0",
+        "@friggframework/test": "2.0.0--canary.653.af34bd7.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "60de83654af65d71fc331c7dbfee727c4f2534ff"
+    "gitHead": "af34bd7c677948dcd9f4a7a8dc0a59b038c35c48"
 }

package/queues/queue-delivery.js

@@ -0,0 +1,41 @@
+const INTEGRATION_QUEUE_MAX_RECEIVE_COUNT = 3;
+const QUEUE_MAX_RECEIVE_COUNT_ENV = 'FRIGG_QUEUE_MAX_RECEIVE_COUNT';
+
+const toPositiveInteger = (value) => {
+    const number = Number(value);
+    return Number.isInteger(number) && number > 0 ? number : undefined;
+};
+
+/**
+ * @typedef {Object} QueueDelivery
+ * @property {number|undefined} receiveCount SQS ApproximateReceiveCount of this delivery.
+ * @property {number|undefined} maxReceiveCount Receives allowed before the queue dead-letters the message.
+ * @property {boolean} isLastAttempt True only when both counts are known and receiveCount >= maxReceiveCount.
+ */
+
+/**
+ * @param {Object} record SQS event record
+ * @param {Object} [env=process.env]
+ * @returns {QueueDelivery}
+ */
+const readQueueDelivery = (record, env = process.env) => {
+    const receiveCount = toPositiveInteger(
+        record?.attributes?.ApproximateReceiveCount
+    );
+    const maxReceiveCount = toPositiveInteger(env[QUEUE_MAX_RECEIVE_COUNT_ENV]);
+
+    return {
+        receiveCount,
+        maxReceiveCount,
+        isLastAttempt:
+            receiveCount !== undefined &&
+            maxReceiveCount !== undefined &&
+            receiveCount >= maxReceiveCount,
+    };
+};
+
+module.exports = {
+    INTEGRATION_QUEUE_MAX_RECEIVE_COUNT,
+    QUEUE_MAX_RECEIVE_COUNT_ENV,
+    readQueueDelivery,
+};