@friggframework/core 2.0.0--canary.658.93c8e07.0 → 2.0.0--canary.658.164d92b.0

package/CLAUDE.md

@@ -370,49 +370,11 @@ class MyIntegration extends IntegrationBase {
 - `BasicAuthRequester` - Basic authentication
 
 **Rate limits** (ADR-049): an API module declares `static rateLimit` on its
-`Requester` subclass. For a throttled response the Requester looks for a hint
-in this order:
-
-| Step | Source |
-|---|---|
-| 1 | `classify({ status, headers, body })` of the module. It recognises a limit that is not a plain 429 (a 403 limit code, a `policyName` in the body) and may name only a `reason` |
-| 2 | The header parsers in `parsers` order. Default: `retryAfter`, `resetHeaders`, `ietf` |
-| 3 | The static policy: `minRetryAfterMs`, or the `perMs` of the window named by the `reason` |
-| 4 | The fixed `backOff` ladder (1, 3, 10, 30, 60, 180 s) |
-
-- A 429 with no hint from steps 1 to 3 keeps today's ladder: the same calls,
-  the same delays, then a plain `FetchError`. Nothing budgets it. A response
-  that `classify` names as a limit but that has no time follows the same
-  ladder, and the last error is a `FetchError` flagged `isRateLimited` with
-  the `reason`, so the queue worker does not halt it.
-- With a hint, the wait is `max(hint, minRetryAfterMs, 1 s)` plus at most 10 %
-  jitter. The total sleep of one request is capped at `maxInProcessWaitMs`
-  (default 5 minutes) and at the time left in the invocation less one request
-  timeout (`remainingInvocationMs()`).
-- A wait that does not fit throws `RateLimitError` (`isRateLimited`, `retryAt`,
-  `waitMs`, `reason`, `policy`, `source`, `module`, `scopeKey`). The queue
-  worker does not halt it, whatever its status.
-- `Retry-After` is read on a 429 only. Another status counts only when
-  `classify` recognises it. A 5xx keeps the 5xx ladder.
-- `maxInProcessWaitMs: 0` turns off sleeping: every hinted wait throws.
-- A module that does not use the Requester (for example one on jsforce) calls
-  `classifyRateLimit(policy, { status, headers, body })` around its own client
-  and throws `RateLimitError` itself.
-
-```javascript
-class Api extends OAuth2Requester {
-    static rateLimit = {
-        scope: 'entity',
-        minRetryAfterMs: 1_000,
-        classify({ status, body }) {
-            if (status === 403 && body?.code === 'DAILY_LIMIT') {
-                return { reason: 'daily', waitMs: 60 * 60_000 };
-            }
-            return null;
-        },
-    };
-}
-```
+`Requester` subclass. A hinted wait (from `classify()`, the header parsers or
+the static policy) sleeps within a budget, or throws `RateLimitError`
+(`isRateLimited`, `retryAt`) when it does not fit. A 429 with no hint keeps the
+fixed `backOff` ladder. See
+[Rate Limits](../../docs/reference/api-module-definition-and-functions.md#rate-limits-static-ratelimit).
 
 **Module Factory**:
 - `ModuleFactory` - Creates and configures API module instances
@@ -568,10 +530,11 @@ if (!userId) {
 }
 ```
 
-**Rate-limit message** (ADR-049): when a wait is too long to sleep, the
-Requester tells its delegate (`RATE_LIMITED`, with the `RateLimitError`) and
-then throws. The notification takes the path of `CREDENTIAL_INVALIDATED`:
-Requester, `Module`, `IntegrationBase`.
+**Rate-limit message** (ADR-049): when a wait is longer than the in-process cap
+(`maxInProcessWaitMs`, default 5 min), the Requester tells its delegate
+(`RATE_LIMITED`, with the `RateLimitError`) and then throws. A shorter wait
+that throws sends no notification. The notification takes the path of
+`CREDENTIAL_INVALIDATED`: Requester, `Module`, `IntegrationBase`.
 
 - The `Module` sends `{ moduleName, reason, retryAt, policy, statusCode, links }`.
   `links` is `static rateLimit.userHints[reason].links`, or `[]`. The message,
@@ -607,13 +570,9 @@ Requester, `Module`, `IntegrationBase`.
 
 The text is fixed. It holds the module name and the reset time in UTC, rounded
 up to the minute, and nothing from the request.
-`updateIntegrationMessages(id, type, title, body, timestamp)` still works, and
-it also takes one item object, `updateIntegrationMessages(id, type, item)`,
-whose keys are stored as they are. Every call appends.
-`findIntegrationMessages(id, type)` reads the stored items of one type. The
-`messages` of the record from `findIntegrationById` is not filled on Postgres
-and Mongo, because the schema keeps the messages in the `errors`, `warnings`,
-`info` and `logs` columns.
+
+Integration messages (the item form, `findIntegrationMessages`, the newest 50
+per type): see "Integration Messages" in `docs/guides/INTEGRATION-PATTERNS.md`.
 
 ### 9. Logging System (`/logs`)
 

package/core/invocation-deadline.js

@@ -9,11 +9,6 @@ function storage() {
     return globalThis[STORE_KEY];
 }
 
-/**
- * Runs fn with the time the invocation ends, as epoch milliseconds. A nested
- * scope can shorten the deadline and never extend it. A deadline that is not
- * a finite number runs fn with no limit.
- */
 function runWithInvocationDeadline(deadlineAt, fn) {
     if (typeof deadlineAt !== 'number' || !Number.isFinite(deadlineAt)) {
         return fn();
@@ -25,25 +20,20 @@ function runWithInvocationDeadline(deadlineAt, fn) {
     return storage().run(Object.freeze({ deadlineAt: effective }), fn);
 }
 
-/**
- * The end of a Lambda invocation, from its context. Undefined when the
- * context cannot tell.
- */
-function deadlineFromContext(context) {
+function remainingTimeMs(context) {
     try {
         const remaining = context?.getRemainingTimeInMillis?.();
-        return typeof remaining === 'number' && Number.isFinite(remaining)
-            ? Date.now() + remaining
-            : undefined;
-    } catch {
-        return undefined;
+        return typeof remaining === 'number' ? remaining : Infinity;
+    } catch (_) {
+        return Infinity;
     }
 }
 
-/**
- * Milliseconds left in the invocation. Infinity outside a deadline scope
- * (tests, `frigg start`, scripts).
- */
+function deadlineFromContext(context) {
+    const remaining = remainingTimeMs(context);
+    return Number.isFinite(remaining) ? Date.now() + remaining : undefined;
+}
+
 function remainingInvocationMs(now = Date.now()) {
     const store = storage().getStore();
     return store ? Math.max(0, store.deadlineAt - now) : Infinity;
@@ -52,5 +42,6 @@ function remainingInvocationMs(now = Date.now()) {
 module.exports = {
     deadlineFromContext,
     remainingInvocationMs,
+    remainingTimeMs,
     runWithInvocationDeadline,
 };

package/core/invocation-scope.js

@@ -3,6 +3,7 @@ const { summarizeMessageBody } = require('../logs/summarize-event');
 const { flushSinks, hasFlushableSinks } = require('../logs/logger-runtime');
 const {
     deadlineFromContext,
+    remainingTimeMs,
     runWithInvocationDeadline,
 } = require('./invocation-deadline');
 
@@ -115,15 +116,6 @@ function withDeadline(ms, fn) {
     });
 }
 
-function remainingTimeMs(context) {
-    try {
-        const remaining = context?.getRemainingTimeInMillis?.();
-        return typeof remaining === 'number' ? remaining : Infinity;
-    } catch (_) {
-        return Infinity;
-    }
-}
-
 async function flushInvocation({
     telemetry,
     usageRollup,

package/errors/fetch-error.js

@@ -55,15 +55,13 @@ class FetchError extends BaseError {
 
     static async create(options = {}) {
         const { response } = options;
-        const provided = options.responseBody ?? options.body;
-        let responseBody = provided;
-        if (
-            responseBody === undefined &&
-            response &&
-            !response.bodyUsed &&
-            typeof response.text === 'function'
-        ) {
-            responseBody = (await response.text()) || provided;
+        let { responseBody } = options;
+        if (responseBody === undefined || responseBody === null) {
+            const canRead =
+                response &&
+                !response.bodyUsed &&
+                typeof response.text === 'function';
+            responseBody = (canRead && (await response.text())) || options.body;
         }
         const ErrorClass = typeof this === 'function' ? this : FetchError;
         return new ErrorClass({ ...options, responseBody });

package/errors/rate-limit-error.js

@@ -14,10 +14,6 @@ function resolveTiming({ hint, waitMs, now }) {
     return { waitMs: fallbackWaitMs, retryAt: new Date(now + fallbackWaitMs) };
 }
 
-/**
- * A FetchError for a response that said a limit was hit and told us, or the
- * module's policy told us, when to call again. `retryAt` is that time.
- */
 class RateLimitError extends FetchError {
     constructor({
         hint,

package/integrations/integration-base.js

@@ -871,9 +871,7 @@ class IntegrationBase {
      * something integration-level needs attention. Today this catches the
      * `CREDENTIAL_INVALIDATED` event Module fires from `markCredentialsInvalid`
      * and flips this integration's status to ERROR so the queue worker
-     * stops processing further webhooks until the user re-authorizes. It also
-     * catches `RATE_LIMITED`, which records one warning for the user and
-     * changes no status: a rate limit is not an error.
+     * stops processing further webhooks until the user re-authorizes.
      *
      * Modules are wired to this delegate in `_appendModules()`, which runs
      * during `setIntegrationRecord()` — this covers every construction path
@@ -918,14 +916,13 @@ class IntegrationBase {
         }
 
         if (delegateString === 'RATE_LIMITED') {
-            const moduleName = object?.moduleName ?? notifier?.name;
             this.logger.warn('Module reported a rate limit', {
                 eventName: `${this.logger.name}.rate_limited`,
-                moduleName,
+                moduleName: object?.moduleName,
                 reason: object?.reason,
                 retryAt: object?.retryAt,
             });
-            await this._recordRateLimitMessage({ ...object, moduleName });
+            await this.recordRateLimitMessage.execute(this.id, object);
         }
     }
 
@@ -952,23 +949,6 @@ class IntegrationBase {
             });
         }
     }
-
-    /**
-     * Best-effort: the module's request is about to throw a RateLimitError,
-     * and a failed warning must not change that. A rate limit is not an ERROR,
-     * so this never touches the integration status.
-     * @param {Object} payload - The RATE_LIMITED payload of the module.
-     */
-    async _recordRateLimitMessage(payload) {
-        try {
-            await this.recordRateLimitMessage.execute(this.id, payload);
-        } catch (error) {
-            this.logger.error('Failed to record rate limit message', {
-                eventName: `${this.logger.name}.rate_limit_message_record_failed`,
-                error,
-            });
-        }
-    }
 }
 
 module.exports = { IntegrationBase };

package/integrations/repositories/integration-repository-documentdb.js

@@ -14,7 +14,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
-const { toMessageItem } = require('./message-item-shared');
+const { messagesOfType } = require('./message-item-shared');
 
 class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
     constructor() {
@@ -95,9 +95,8 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
     async updateIntegrationMessages(
         integrationId,
         messageType,
-        messageTitleOrItem,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         const objectId = toObjectId(integrationId);
         if (!objectId) {
@@ -108,14 +107,12 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
             throw new Error(`Integration ${integrationId} not found`);
         }
         const messages = this._extractMessages(existing);
-        const list = Array.isArray(messages[messageType]) ? [...messages[messageType]] : [];
-        const item = toMessageItem(
-            messageTitleOrItem,
-            messageBody,
-            messageTimestamp
-        );
+        const list = [...messagesOfType(messages, messageType)];
         list.push({ ...item, title: item.title ?? null });
-        const updatedMessages = { ...messages, [messageType]: list };
+        const updatedMessages = {
+            ...messages,
+            [messageType]: list.slice(-keepLast),
+        };
         await updateOne(
             this.prisma,
             'Integration',
@@ -145,10 +142,7 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
         if (!existing) {
             throw new Error(`Integration ${integrationId} not found`);
         }
-        const messages = this._extractMessages(existing);
-        return Array.isArray(messages[messageType])
-            ? messages[messageType]
-            : [];
+        return messagesOfType(this._extractMessages(existing), messageType);
     }
 
     async createIntegration(entities, userId, config) {

package/integrations/repositories/integration-repository-interface.js

@@ -97,24 +97,21 @@ class IntegrationRepositoryInterface {
     }
 
     /**
-     * Append a message to the stored messages of one type. Takes the
-     * positional form (title, body, timestamp) or one message item object,
-     * whose keys are stored as they are.
+     * Append a message item to the stored messages of one type
      *
      * @param {string|number} integrationId - Integration ID
      * @param {string} messageType - Type of message (errors, warnings, info, logs)
-     * @param {string|Object} messageTitleOrItem - Message title, or the whole message item
-     * @param {string} [messageBody] - Message body (positional form)
-     * @param {Date} [messageTimestamp] - Message timestamp (positional form)
+     * @param {Object} item - Message item, stored as it is
+     * @param {Object} options
+     * @param {number} options.keepLast - How many of the newest items of the type to keep
      * @returns {Promise<boolean>} Success indicator
      * @abstract
      */
     async updateIntegrationMessages(
         integrationId,
         messageType,
-        messageTitleOrItem,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         throw new Error('Method updateIntegrationMessages must be implemented by subclass');
     }

package/integrations/repositories/integration-repository-mongo.js

@@ -3,7 +3,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
-const { toMessageItem } = require('./message-item-shared');
+const { messagesOfType } = require('./message-item-shared');
 
 /**
  * MongoDB Integration Repository Adapter
@@ -230,17 +230,16 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
      *
      * @param {string} integrationId - Integration ID
      * @param {string} messageType - Type of message (errors, warnings, info, logs)
-     * @param {string|Object} messageTitleOrItem - Message title, or the whole message item
-     * @param {string} [messageBody] - Message body (positional form)
-     * @param {Date} [messageTimestamp] - Message timestamp (positional form)
+     * @param {Object} item - Message item, stored as it is
+     * @param {Object} options
+     * @param {number} options.keepLast - How many of the newest items of the type to keep
      * @returns {Promise<boolean>} Success indicator
      */
     async updateIntegrationMessages(
         integrationId,
         messageType,
-        messageTitleOrItem,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         // Get current integration
         const integration = await this.prisma.integration.findUnique({
@@ -252,20 +251,16 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
         }
 
         // Parse existing messages (JSON field)
-        const messageArray = Array.isArray(integration[messageType])
-            ? integration[messageType]
-            : [];
+        const messageArray = messagesOfType(integration, messageType);
 
         // Add new message
-        messageArray.push(
-            toMessageItem(messageTitleOrItem, messageBody, messageTimestamp)
-        );
+        messageArray.push(item);
 
         // Update messages
         await this.prisma.integration.update({
             where: { id: integrationId },
             data: {
-                [messageType]: messageArray,
+                [messageType]: messageArray.slice(-keepLast),
             },
         });
 
@@ -289,9 +284,7 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
             throw new Error(`Integration ${integrationId} not found`);
         }
 
-        return Array.isArray(integration[messageType])
-            ? integration[messageType]
-            : [];
+        return messagesOfType(integration, messageType);
     }
 
     /**

package/integrations/repositories/integration-repository-postgres.js

@@ -3,7 +3,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
-const { toMessageItem } = require('./message-item-shared');
+const { messagesOfType } = require('./message-item-shared');
 const { strictIntId } = require('./report-id');
 
 /**
@@ -274,17 +274,16 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
      *
      * @param {string} integrationId - Integration ID (string from application layer)
      * @param {string} messageType - Type of message (errors, warnings, info, logs)
-     * @param {string|Object} messageTitleOrItem - Message title, or the whole message item
-     * @param {string} [messageBody] - Message body (positional form)
-     * @param {Date} [messageTimestamp] - Message timestamp (positional form)
+     * @param {Object} item - Message item, stored as it is
+     * @param {Object} options
+     * @param {number} options.keepLast - How many of the newest items of the type to keep
      * @returns {Promise<boolean>} Success indicator
      */
     async updateIntegrationMessages(
         integrationId,
         messageType,
-        messageTitleOrItem,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         const intId = this._convertId(integrationId);
 
@@ -298,20 +297,16 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
         }
 
         // Parse existing messages (JSON field)
-        const messageArray = Array.isArray(integration[messageType])
-            ? integration[messageType]
-            : [];
+        const messageArray = messagesOfType(integration, messageType);
 
         // Add new message
-        messageArray.push(
-            toMessageItem(messageTitleOrItem, messageBody, messageTimestamp)
-        );
+        messageArray.push(item);
 
         // Update messages
         await this.prisma.integration.update({
             where: { id: intId },
             data: {
-                [messageType]: messageArray,
+                [messageType]: messageArray.slice(-keepLast),
             },
         });
 
@@ -336,9 +331,7 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
             throw new Error(`Integration ${integrationId} not found`);
         }
 
-        return Array.isArray(integration[messageType])
-            ? integration[messageType]
-            : [];
+        return messagesOfType(integration, messageType);
     }
 
     /**

package/integrations/repositories/message-item-shared.js

@@ -1,24 +1,4 @@
-const isItem = (value) =>
-    value !== null && typeof value === 'object' && !Array.isArray(value);
+const messagesOfType = (record, messageType) =>
+    Array.isArray(record[messageType]) ? record[messageType] : [];
 
-/**
- * The stored shape of a message, for IntegrationRepository
- * .updateIntegrationMessages(). The method takes the positional form (title,
- * body, timestamp) or one item object. The keys of an item object are stored
- * as they are, so a caller can attach what a client acts on, like a code or
- * a list of actions.
- * @param {string|Object} titleOrItem - The title, or the whole item.
- * @param {string} [messageBody] - Ignored when an item is given.
- * @param {number|Date} [messageTimestamp] - Ignored when an item is given.
- * @returns {Object} A new object; the given item is never returned itself.
- */
-function toMessageItem(titleOrItem, messageBody, messageTimestamp) {
-    if (isItem(titleOrItem)) return { ...titleOrItem };
-    return {
-        title: titleOrItem,
-        message: messageBody,
-        timestamp: messageTimestamp,
-    };
-}
-
-module.exports = { toMessageItem };
+module.exports = { messagesOfType };

package/integrations/tests/doubles/prisma-message-row.js

@@ -0,0 +1,24 @@
+const copy = (value) => JSON.parse(JSON.stringify(value));
+
+function withMessageRow(repo, id, stored = {}) {
+    const row = {
+        id,
+        errors: [],
+        warnings: [],
+        info: [],
+        logs: [],
+        ...stored,
+    };
+    repo.prisma = {
+        integration: {
+            findUnique: jest.fn(async () => copy(row)),
+            update: jest.fn(async ({ data }) => {
+                Object.assign(row, copy(data));
+                return copy(row);
+            }),
+        },
+    };
+    return { repo, row };
+}
+
+module.exports = { withMessageRow };

package/integrations/tests/doubles/test-integration-repository.js

@@ -1,6 +1,5 @@
 const { v4: uuid } = require('uuid');
 const { validateConfigPatch } = require('../../repositories/config-patch-shared');
-const { toMessageItem } = require('../../repositories/message-item-shared');
 
 class TestIntegrationRepository {
     constructor() {
@@ -73,14 +72,15 @@ class TestIntegrationRepository {
         return results;
     }
 
-    async updateIntegrationMessages(id, type, titleOrItem, body, timestamp) {
+    async updateIntegrationMessages(id, type, item, { keepLast }) {
         const rec = this.store.get(id);
         if (!rec) {
             this.operationHistory.push({ operation: 'updateMessages', id, success: false });
             return false;
         }
         if (!rec.messages[type]) rec.messages[type] = [];
-        rec.messages[type].push(toMessageItem(titleOrItem, body, timestamp));
+        rec.messages[type].push(item);
+        rec.messages[type] = rec.messages[type].slice(-keepLast);
         this.operationHistory.push({ operation: 'updateMessages', id, type, success: true });
         return true;
     }