@friggframework/core 2.0.0--canary.656.4fb07b4.0 → 2.0.0--canary.658.164d92b.0

package/CLAUDE.md

@@ -530,6 +530,50 @@ if (!userId) {
 }
 ```
 
+**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,
+  url, body and headers of the error are never sent: the message reaches end
+  users.
+- `IntegrationBase` writes one `WARN` (`integration.<name>.rate_limited`), and
+  `RecordRateLimitMessage` appends one item to the stored `warnings`. It
+  changes no status. A rate limit is not an `ERROR`, and an `ERROR` status
+  makes the queue worker drop every webhook.
+- A report for the same module whose reset time is within 60 s of a stored one
+  is skipped. The check reads the stored `warnings` with
+  `findIntegrationMessages`, not `this.messages`, which is per instance and
+  empty on Postgres. It is a read then a write, so workers that report at the
+  same instant can still store a few copies.
+- Every hop is best effort. A failure is logged, and the caller still gets the
+  `RateLimitError`.
+
+```javascript
+{
+    title: 'Rate limit reached',
+    message: 'The hubspot API rate limit was reached and resets at 2026-09-28 14:31 UTC.',
+    timestamp: 1790000000000,
+    code: 'RATE_LIMITED',
+    module: 'hubspot',
+    reason: 'daily',
+    retryAt: '2026-09-28T14:30:15.000Z',
+    actions: [
+        { type: 'RETRY_WHEN_READY' },
+        { type: 'LINK', label: 'API usage limits', url: 'https://example.com/limits' },
+    ],
+}
+```
+
+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.
+
+Integration messages (the item form, `findIntegrationMessages`, the newest 50
+per type): see "Integration Messages" in `docs/guides/INTEGRATION-PATTERNS.md`.
+
 ### 9. Logging System (`/logs`)
 
 **Purpose**: One redacted JSON record per line to stdout (ADR-048). See `docs/guides/LOGGING.md`.

package/integrations/integration-base.js

@@ -17,6 +17,9 @@ const {
 const {
     UpdateIntegrationConfig,
 } = require('./use-cases/update-integration-config');
+const {
+    RecordRateLimitMessage,
+} = require('./use-cases/record-rate-limit-message');
 const { validateExtensionBinding } = require('./extension');
 const { getTelemetry } = require('../telemetry/telemetry-runtime');
 const { instrumentHandler } = require('../telemetry/instrument-handler');
@@ -59,6 +62,9 @@ class IntegrationBase {
     updateIntegrationConfig = new UpdateIntegrationConfig({
         integrationRepository: this.integrationRepository,
     });
+    recordRateLimitMessage = new RecordRateLimitMessage({
+        integrationRepository: this.integrationRepository,
+    });
 
     // this.telemetry.count('records.synced', n, { entity: 'contact' })
     telemetry = bindTelemetryContext(getTelemetry(), () =>
@@ -908,6 +914,16 @@ class IntegrationBase {
             });
             await this.persistStatus('ENABLED');
         }
+
+        if (delegateString === 'RATE_LIMITED') {
+            this.logger.warn('Module reported a rate limit', {
+                eventName: `${this.logger.name}.rate_limited`,
+                moduleName: object?.moduleName,
+                reason: object?.reason,
+                retryAt: object?.retryAt,
+            });
+            await this.recordRateLimitMessage.execute(this.id, object);
+        }
     }
 
     /**

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

@@ -14,6 +14,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
+const { messagesOfType } = require('./message-item-shared');
 
 class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
     constructor() {
@@ -94,9 +95,8 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
     async updateIntegrationMessages(
         integrationId,
         messageType,
-        messageTitle,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         const objectId = toObjectId(integrationId);
         if (!objectId) {
@@ -107,13 +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]] : [];
-        list.push({
-            title: messageTitle ?? null,
-            message: messageBody,
-            timestamp: messageTimestamp,
-        });
-        const updatedMessages = { ...messages, [messageType]: list };
+        const list = [...messagesOfType(messages, messageType)];
+        list.push({ ...item, title: item.title ?? null });
+        const updatedMessages = {
+            ...messages,
+            [messageType]: list.slice(-keepLast),
+        };
         await updateOne(
             this.prisma,
             'Integration',
@@ -132,6 +131,20 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
         return true;
     }
 
+    async findIntegrationMessages(integrationId, messageType) {
+        const objectId = toObjectId(integrationId);
+        if (!objectId) {
+            throw new Error(`Integration ${integrationId} not found`);
+        }
+        const existing = await findOne(this.prisma, 'Integration', {
+            _id: objectId,
+        });
+        if (!existing) {
+            throw new Error(`Integration ${integrationId} not found`);
+        }
+        return messagesOfType(this._extractMessages(existing), messageType);
+    }
+
     async createIntegration(entities, userId, config) {
         const now = new Date();
         const document = {

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

@@ -97,26 +97,40 @@ class IntegrationRepositoryInterface {
     }
 
     /**
-     * Update integration messages
+     * 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} messageTitle - Message title
-     * @param {string} messageBody - Message body
-     * @param {Date} messageTimestamp - Message timestamp
+     * @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,
-        messageTitle,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         throw new Error('Method updateIntegrationMessages must be implemented by subclass');
     }
 
+    /**
+     * Find the stored messages of one type. Reads the stored items, not the
+     * `messages` of an integration record, which some adapters do not fill.
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {string} messageType - Type of message (errors, warnings, info, logs)
+     * @returns {Promise<Array>} The stored message items of that type, oldest first
+     * @abstract
+     */
+    async findIntegrationMessages(integrationId, messageType) {
+        throw new Error(
+            'Method findIntegrationMessages must be implemented by subclass'
+        );
+    }
+
     /**
      * Create a new integration
      *

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

@@ -3,6 +3,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
+const { messagesOfType } = require('./message-item-shared');
 
 /**
  * MongoDB Integration Repository Adapter
@@ -229,17 +230,16 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
      *
      * @param {string} integrationId - Integration ID
      * @param {string} messageType - Type of message (errors, warnings, info, logs)
-     * @param {string} messageTitle - Message title
-     * @param {string} messageBody - Message body
-     * @param {Date} messageTimestamp - Message timestamp
+     * @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,
-        messageTitle,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         // Get current integration
         const integration = await this.prisma.integration.findUnique({
@@ -251,29 +251,42 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
         }
 
         // Parse existing messages (JSON field)
-        const messages = integration.messages || {};
-        const messageArray = Array.isArray(messages[messageType])
-            ? messages[messageType]
-            : [];
+        const messageArray = messagesOfType(integration, messageType);
 
         // Add new message
-        messageArray.push({
-            title: messageTitle,
-            message: messageBody,
-            timestamp: messageTimestamp,
-        });
+        messageArray.push(item);
 
         // Update messages
         await this.prisma.integration.update({
             where: { id: integrationId },
             data: {
-                [messageType]: messageArray,
+                [messageType]: messageArray.slice(-keepLast),
             },
         });
 
         return true; // Mongoose compatibility
     }
 
+    /**
+     * Find the stored messages of one type
+     *
+     * @param {string} integrationId - Integration ID
+     * @param {string} messageType - Type of message (errors, warnings, info, logs)
+     * @returns {Promise<Array>} The stored message items of that type, oldest first
+     */
+    async findIntegrationMessages(integrationId, messageType) {
+        const integration = await this.prisma.integration.findUnique({
+            where: { id: integrationId },
+            select: { [messageType]: true },
+        });
+
+        if (!integration) {
+            throw new Error(`Integration ${integrationId} not found`);
+        }
+
+        return messagesOfType(integration, messageType);
+    }
+
     /**
      * Find all integrations whose entity set includes the given entity ID.
      *

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

@@ -3,6 +3,7 @@ const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
 const { validateConfigPatch } = require('./config-patch-shared');
+const { messagesOfType } = require('./message-item-shared');
 const { strictIntId } = require('./report-id');
 
 /**
@@ -273,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} messageTitle - Message title
-     * @param {string} messageBody - Message body
-     * @param {Date} messageTimestamp - Message timestamp
+     * @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,
-        messageTitle,
-        messageBody,
-        messageTimestamp
+        item,
+        { keepLast }
     ) {
         const intId = this._convertId(integrationId);
 
@@ -297,29 +297,43 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
         }
 
         // Parse existing messages (JSON field)
-        const messages = integration.messages || {};
-        const messageArray = Array.isArray(messages[messageType])
-            ? messages[messageType]
-            : [];
+        const messageArray = messagesOfType(integration, messageType);
 
         // Add new message
-        messageArray.push({
-            title: messageTitle,
-            message: messageBody,
-            timestamp: messageTimestamp,
-        });
+        messageArray.push(item);
 
         // Update messages
         await this.prisma.integration.update({
             where: { id: intId },
             data: {
-                [messageType]: messageArray,
+                [messageType]: messageArray.slice(-keepLast),
             },
         });
 
         return true; // Mongoose compatibility
     }
 
+    /**
+     * Find the stored messages of one type
+     *
+     * @param {string} integrationId - Integration ID (string from application layer)
+     * @param {string} messageType - Type of message (errors, warnings, info, logs)
+     * @returns {Promise<Array>} The stored message items of that type, oldest first
+     */
+    async findIntegrationMessages(integrationId, messageType) {
+        const intId = this._convertId(integrationId);
+        const integration = await this.prisma.integration.findUnique({
+            where: { id: intId },
+            select: { [messageType]: true },
+        });
+
+        if (!integration) {
+            throw new Error(`Integration ${integrationId} not found`);
+        }
+
+        return messagesOfType(integration, messageType);
+    }
+
     /**
      * Create a new integration
      *

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

@@ -0,0 +1,4 @@
+const messagesOfType = (record, messageType) =>
+    Array.isArray(record[messageType]) ? record[messageType] : [];
+
+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

@@ -72,18 +72,31 @@ class TestIntegrationRepository {
         return results;
     }
 
-    async updateIntegrationMessages(id, type, title, 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({ title, message: 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;
     }
 
+    async findIntegrationMessages(id, type) {
+        const rec = this.store.get(id);
+        this.operationHistory.push({
+            operation: 'findMessages',
+            id,
+            type,
+            found: !!rec,
+        });
+        if (!rec) throw new Error(`Integration ${id} not found`);
+        return [...(rec.messages[type] ?? [])];
+    }
+
     async updateIntegrationConfig(id, config) {
         if (config === null || config === undefined) {
             throw new Error('Config parameter is required');

package/integrations/use-cases/record-rate-limit-message.js

@@ -0,0 +1,110 @@
+const { getLogger } = require('../../logs');
+const { MAX_MESSAGES_PER_TYPE } = require('./update-integration-messages');
+
+const log = getLogger('frigg.integrations');
+
+const RATE_LIMITED_MESSAGE_CODE = 'RATE_LIMITED';
+const SAME_LIMIT_WINDOW_MS = 60_000;
+const MINUTE_MS = 60_000;
+
+const isNonEmptyString = (value) => typeof value === 'string' && value !== '';
+
+const isValidTime = (value) =>
+    value !== null &&
+    value !== undefined &&
+    !Number.isNaN(new Date(value).getTime());
+
+const isLink = (link) =>
+    typeof link?.label === 'string' && typeof link?.url === 'string';
+
+const linkActions = (links) =>
+    (Array.isArray(links) ? links : [])
+        .filter(isLink)
+        .map(({ label, url }) => ({ type: 'LINK', label, url }));
+
+function formatResetTime(date) {
+    const minute = new Date(Math.ceil(date.getTime() / MINUTE_MS) * MINUTE_MS);
+    return `${minute.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+/**
+ * @class RecordRateLimitMessage
+ */
+class RecordRateLimitMessage {
+    /**
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     */
+    constructor({ integrationRepository }) {
+        this.integrationRepository = integrationRepository;
+    }
+
+    /**
+     * @async
+     * @param {string} integrationId - ID of the integration to warn on.
+     * @param {Object} payload - The RATE_LIMITED payload of the Module.
+     * @param {string} payload.moduleName
+     * @param {string} payload.reason
+     * @param {Date|string|number} payload.retryAt
+     * @param {Array<{label: string, url: string}>} [payload.links]
+     */
+    async execute(integrationId, payload) {
+        const { moduleName, reason, retryAt, links } = payload ?? {};
+        if (!isNonEmptyString(moduleName) || !isValidTime(retryAt)) return;
+
+        try {
+            await this._recordUnlessStored(integrationId, {
+                moduleName,
+                reason,
+                resetAt: new Date(retryAt),
+                links,
+            });
+        } catch (error) {
+            log.warn('Failed to record rate limit message', {
+                eventName:
+                    'frigg.integrations.rate_limit_message_record_failed',
+                integrationId,
+                moduleName,
+                error,
+            });
+        }
+    }
+
+    async _recordUnlessStored(
+        integrationId,
+        { moduleName, reason, resetAt, links }
+    ) {
+        const warnings =
+            await this.integrationRepository.findIntegrationMessages(
+                integrationId,
+                'warnings'
+            );
+        const alreadyRecorded = warnings.some(
+            (warning) =>
+                warning?.code === RATE_LIMITED_MESSAGE_CODE &&
+                warning.module === moduleName &&
+                Math.abs(Date.parse(warning.retryAt) - resetAt.getTime()) <=
+                    SAME_LIMIT_WINDOW_MS
+        );
+        if (alreadyRecorded) return;
+
+        const resetsAt = formatResetTime(resetAt);
+        await this.integrationRepository.updateIntegrationMessages(
+            integrationId,
+            'warnings',
+            {
+                title: 'Rate limit reached',
+                message: `The ${moduleName} API rate limit was reached and resets at ${resetsAt}.`,
+                timestamp: Date.now(),
+                code: RATE_LIMITED_MESSAGE_CODE,
+                module: moduleName,
+                reason,
+                retryAt: resetAt.toISOString(),
+                actions: [{ type: 'RETRY_WHEN_READY' }, ...linkActions(links)],
+            },
+            { keepLast: MAX_MESSAGES_PER_TYPE }
+        );
+    }
+}
+
+module.exports = { RecordRateLimitMessage };

package/integrations/use-cases/update-integration-messages.js

@@ -1,3 +1,17 @@
+const MAX_MESSAGES_PER_TYPE = 50;
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function toMessageItem(titleOrItem, messageBody, messageTimestamp) {
+    if (isPlainObject(titleOrItem)) return { ...titleOrItem };
+    return {
+        title: titleOrItem,
+        message: messageBody,
+        timestamp: messageTimestamp,
+    };
+}
+
 /**
  * Use case for updating messages associated with an integration.
  * @class UpdateIntegrationMessages
@@ -13,19 +27,21 @@ class UpdateIntegrationMessages {
     }
 
     /**
-     * Executes the integration messages update.
+     * Executes the integration messages update. Pass the positional form
+     * (title, body, timestamp) or one message item object; the keys of an item
+     * object are stored as they are.
      * @async
      * @param {string} integrationId - ID of the integration to update.
      * @param {string} messageType - Type of message: 'errors', 'warnings', 'info', or 'logs'.
-     * @param {string} messageTitle - Title of the message.
-     * @param {string} messageBody - Body content of the message.
-     * @param {string} messageTimestamp - Timestamp when the message was created.
+     * @param {string|Object} messageTitleOrItem - Title of the message, or the whole message item.
+     * @param {string} [messageBody] - Body content of the message (positional form).
+     * @param {string} [messageTimestamp] - Timestamp when the message was created (positional form).
      * @returns {Promise<Object>} The updated integration record.
      */
     async execute(
         integrationId,
         messageType,
-        messageTitle,
+        messageTitleOrItem,
         messageBody,
         messageTimestamp
     ) {
@@ -33,12 +49,15 @@ class UpdateIntegrationMessages {
             await this.integrationRepository.updateIntegrationMessages(
                 integrationId,
                 messageType,
-                messageTitle,
-                messageBody,
-                messageTimestamp
+                toMessageItem(
+                    messageTitleOrItem,
+                    messageBody,
+                    messageTimestamp
+                ),
+                { keepLast: MAX_MESSAGES_PER_TYPE }
             );
         return integration;
     }
 }
 
-module.exports = { UpdateIntegrationMessages };
+module.exports = { MAX_MESSAGES_PER_TYPE, UpdateIntegrationMessages };

package/modules/module.js

@@ -8,6 +8,7 @@ const {
 const {
     createModuleRepository,
 } = require('./repositories/module-repository-factory');
+const { readRateLimitPolicy } = require('./requester/rate-limit');
 
 // todo: this class should be a Domain class, and the Delegate function is preventing us from
 // doing that, we probably have to get rid of the Delegate class as well as the event based
@@ -51,6 +52,8 @@ class Module extends Delegate {
         this.delegateTypes.push(this.DLGT_CREDENTIAL_INVALIDATED);
         this.DLGT_CREDENTIAL_VALIDATED = 'CREDENTIAL_VALIDATED';
         this.delegateTypes.push(this.DLGT_CREDENTIAL_VALIDATED);
+        this.DLGT_RATE_LIMITED = 'RATE_LIMITED';
+        this.delegateTypes.push(this.DLGT_RATE_LIMITED);
 
         Object.assign(this, this.definition.requiredAuthMethods);
 
@@ -160,6 +163,8 @@ class Module extends Delegate {
             await this.deauthorize();
         } else if (delegateString === this.api.DLGT_INVALID_AUTH) {
             await this.markCredentialsInvalid(object);
+        } else if (delegateString === this.api.DLGT_RATE_LIMITED) {
+            await this.reportRateLimit(object);
         } else if (delegateString === this.api.DLGT_CREDENTIAL_RELOAD) {
             return this.reloadCredential();
         }
@@ -234,6 +239,28 @@ class Module extends Delegate {
         }
     }
 
+    async reportRateLimit(rateLimitError) {
+        const { reason, retryAt, policy, statusCode } = rateLimitError;
+        const links =
+            readRateLimitPolicy(this.apiClass)?.userHints?.[reason]?.links ??
+            [];
+        try {
+            await this.notify(this.DLGT_RATE_LIMITED, {
+                moduleName: this.name,
+                reason,
+                retryAt,
+                policy,
+                statusCode,
+                links,
+            });
+        } catch (err) {
+            this.logger.warn('Failed to propagate RATE_LIMITED', {
+                eventName: `${this.logger.name}.rate_limit_propagation_failed`,
+                error: err,
+            });
+        }
+    }
+
     async deauthorize() {
         //todo: Check if this is correct, we're instantiating a new api without params (credentials, tokens, etc...)
         this.api = new this.apiClass();

package/modules/requester/requester.js

@@ -10,6 +10,7 @@ const { redactUrl } = require('../../logs/redact');
 const { toSanitizedSurrogate } = require('../../logs/serialize');
 const { getLoggerScope } = require('../../logs/context');
 const {
+    DEFAULT_MAX_IN_PROCESS_WAIT_MS,
     computeScopeKey,
     computeWaitMs,
     inProcessBudgetMs,
@@ -54,6 +55,8 @@ class Requester extends Delegate {
         this._authGeneration = 0;
         this.DLGT_INVALID_AUTH = 'INVALID_AUTH';
         this.delegateTypes.push(this.DLGT_INVALID_AUTH);
+        this.DLGT_RATE_LIMITED = 'RATE_LIMITED';
+        this.delegateTypes.push(this.DLGT_RATE_LIMITED);
         this.agent = get(params, 'agent', null);
 
         // Per-attempt HTTP timeout. Without this the framework called fetch()
@@ -528,6 +531,7 @@ class Requester extends Delegate {
             module: this._telemetryModuleLabel(),
             scopeKey: computeScopeKey(this._rateLimitPolicy, this),
         });
+        await this._notifyRateLimited(rateLimitError);
         throw this._maybeFlagTimeoutDuringBodyRead(rateLimitError, timeoutMs);
     }
 
@@ -595,6 +599,30 @@ class Requester extends Delegate {
         });
     }
 
+    async _notifyRateLimited(rateLimitError) {
+        if (!this._waitsLongerThanInProcessCap(rateLimitError)) return;
+        try {
+            await this.notify(this.DLGT_RATE_LIMITED, rateLimitError);
+        } catch (error) {
+            const logger = this.logger;
+            logger.warn('Rate limit notification failed', {
+                eventName: `${logger.name}.rate_limit_notify_failed`,
+                statusCode: rateLimitError.statusCode,
+                error,
+            });
+        }
+    }
+
+    _waitsLongerThanInProcessCap(rateLimitError) {
+        const waitMs = Number.isFinite(rateLimitError?.waitMs)
+            ? rateLimitError.waitMs
+            : new Date(rateLimitError?.retryAt).getTime() - Date.now();
+        const capMs =
+            this._rateLimitPolicy?.maxInProcessWaitMs ??
+            DEFAULT_MAX_IN_PROCESS_WAIT_MS;
+        return waitMs > capMs;
+    }
+
     _logRequestFailed(encodedUrl, options, status) {
         const logger = this.logger;
         if (!logger.isLevelEnabled('DEBUG')) return;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.656.4fb07b4.0",
+    "version": "2.0.0--canary.658.164d92b.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.656.4fb07b4.0",
-        "@friggframework/prettier-config": "2.0.0--canary.656.4fb07b4.0",
-        "@friggframework/test": "2.0.0--canary.656.4fb07b4.0",
+        "@friggframework/eslint-config": "2.0.0--canary.658.164d92b.0",
+        "@friggframework/prettier-config": "2.0.0--canary.658.164d92b.0",
+        "@friggframework/test": "2.0.0--canary.658.164d92b.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "4fb07b4e92324bbbf0d19153e2168642facc1182"
+    "gitHead": "164d92b13ea5ffc31d5f7861fbb936fc28ad3d97"
 }

package/types/integrations/index.d.ts

@@ -1,6 +1,22 @@
 declare module "@friggframework/integrations" {
   import { Delegate, IFriggDelegate } from "@friggframework/core";
 
+  export type IntegrationMessageAction =
+    | { type: "RETRY_WHEN_READY" }
+    | { type: "LINK"; label: string; url: string };
+
+  export interface IntegrationMessage {
+    title: string;
+    message: string;
+    timestamp: number;
+    code?: string;
+    module?: string;
+    reason?: string;
+    retryAt?: string;
+    actions?: IntegrationMessageAction[];
+    [key: string]: unknown;
+  }
+
   export interface Integration {
     entities: any[];
     userId: string;
@@ -8,10 +24,10 @@ declare module "@friggframework/integrations" {
     config: any;
     version: string;
     messages: {
-      errors: [];
-      warnings: [];
-      info: [];
-      logs: [];
+      errors: IntegrationMessage[];
+      warnings: IntegrationMessage[];
+      info: IntegrationMessage[];
+      logs: IntegrationMessage[];
     };
   }
 

package/types/module-plugin/index.d.ts

@@ -1,6 +1,6 @@
 declare module "@friggframework/module-plugin" {
   import { Delegate, IFriggDelegate } from "@friggframework/core";
-  import type { RateLimitHint } from "@friggframework/errors";
+  import type { RateLimitError, RateLimitHint } from "@friggframework/errors";
 
   export interface Credential {
     id?: string;
@@ -66,6 +66,7 @@ declare module "@friggframework/module-plugin" {
     static requestTimeoutMs?: number;
 
     DLGT_INVALID_AUTH: string;
+    DLGT_RATE_LIMITED: string;
     requestTimeoutMs: number;
     backOff: number[];
     fetch: any;
@@ -85,6 +86,7 @@ declare module "@friggframework/module-plugin" {
     parseBody(response: any): Promise<any>;
     refreshAuth(): Promise<any>;
     _adoptNewerCredential(): Promise<boolean>;
+    _notifyRateLimited(rateLimitError: RateLimitError): Promise<void>;
 
     delegate: any;
     delegateTypes: any[];
@@ -102,6 +104,7 @@ declare module "@friggframework/module-plugin" {
     isRefreshable: boolean;
     refreshCount: number;
     DLGT_INVALID_AUTH: string;
+    DLGT_RATE_LIMITED: string;
     fetch: any;
 
     parseBody(response: any): Promise<any>;
@@ -117,6 +120,7 @@ declare module "@friggframework/module-plugin" {
     _delete(options: RequestOptions): Promise<any>;
     refreshAuth(): Promise<any>;
     _adoptNewerCredential(): Promise<boolean>;
+    _notifyRateLimited(rateLimitError: RateLimitError): Promise<void>;
   }
 
   type RequestOptions = {