@friggframework/core 2.0.0--canary.657.b14221f.0 → 2.0.0--canary.658.93c8e07.0

package/types/integrations/index.d.ts

@@ -1,6 +1,27 @@
 declare module "@friggframework/integrations" {
   import { Delegate, IFriggDelegate } from "@friggframework/core";
 
+  export type IntegrationMessageAction =
+    | { type: "RETRY_WHEN_READY" }
+    | { type: "LINK"; label: string; url: string };
+
+  /**
+   * A stored message. The framework stores the keys of an item as given, so a
+   * caller can add its own. A rate limit adds `code: "RATE_LIMITED"`,
+   * `module`, `reason`, `retryAt` (ISO 8601) and `actions`.
+   */
+  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 +29,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;
@@ -75,6 +75,8 @@ declare module "@friggframework/module-plugin" {
     static requestTimeoutMs?: number;
 
     DLGT_INVALID_AUTH: string;
+    /** Notified with the `RateLimitError` right before a wait that is too long throws. */
+    DLGT_RATE_LIMITED: string;
     requestTimeoutMs: number;
     backOff: number[];
     fetch: any;
@@ -94,6 +96,12 @@ declare module "@friggframework/module-plugin" {
     parseBody(response: any): Promise<any>;
     refreshAuth(): Promise<any>;
     _adoptNewerCredential(): Promise<boolean>;
+    /**
+     * Tells the integration about a `RateLimitError` the module throws itself.
+     * The Requester calls it for its own errors; a module built on a vendor SDK
+     * calls it before its own throw.
+     */
+    _notifyRateLimited(rateLimitError: RateLimitError): Promise<void>;
 
     delegate: any;
     delegateTypes: any[];
@@ -111,6 +119,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>;
@@ -126,6 +135,7 @@ declare module "@friggframework/module-plugin" {
     _delete(options: RequestOptions): Promise<any>;
     refreshAuth(): Promise<any>;
     _adoptNewerCredential(): Promise<boolean>;
+    _notifyRateLimited(rateLimitError: RateLimitError): Promise<void>;
   }
 
   type RequestOptions = {

package/queues/queue-deferral.js

@@ -1,79 +0,0 @@
-const MAX_DEFERRALS = 10;
-const MAX_DEFERRED_MS = 24 * 60 * 60 * 1000;
-const MAX_DELAY_SECONDS = 900;
-const MAX_VISIBILITY_TIMEOUT_SECONDS = 43_200;
-const MAX_DEFERRALS_ENV = 'FRIGG_QUEUE_MAX_DEFERRALS';
-const MAX_DEFERRED_MS_ENV = 'FRIGG_QUEUE_MAX_DEFERRED_MS';
-
-const toPositiveInteger = (value) => {
-    const number = Number(value);
-    return Number.isInteger(number) && number > 0 ? number : undefined;
-};
-
-/**
- * @typedef {Object} DeferralLimits
- * @property {number} maxDeferrals Times one message may be put back for a rate limit.
- * @property {number} maxDeferredMs Longest total time from the first deferral to the last retry time.
- */
-
-/**
- * @param {Object} [env=process.env]
- * @returns {DeferralLimits}
- */
-const readDeferralLimits = (env = process.env) => ({
-    maxDeferrals: toPositiveInteger(env[MAX_DEFERRALS_ENV]) ?? MAX_DEFERRALS,
-    maxDeferredMs:
-        toPositiveInteger(env[MAX_DEFERRED_MS_ENV]) ?? MAX_DEFERRED_MS,
-});
-
-/**
- * The deferral counters a message body carries in `_frigg`.
- * @returns {{deferrals: number, firstDeferredAt: string|undefined}}
- */
-const readDeferral = (body) => {
-    const frigg = body?._frigg;
-    const deferrals =
-        Number.isInteger(frigg?.deferrals) && frigg.deferrals > 0
-            ? frigg.deferrals
-            : 0;
-    const firstDeferredAt =
-        typeof frigg?.firstDeferredAt === 'string' &&
-        !Number.isNaN(Date.parse(frigg.firstDeferredAt))
-            ? frigg.firstDeferredAt
-            : undefined;
-    return { deferrals, firstDeferredAt };
-};
-
-const nextDeferral = (body, now = Date.now()) => {
-    const current = readDeferral(body);
-    return {
-        deferrals: current.deferrals + 1,
-        firstDeferredAt: current.firstDeferredAt ?? new Date(now).toISOString(),
-    };
-};
-
-const withDeferral = (body, deferral) => ({
-    ...body,
-    _frigg: { ...body._frigg, ...deferral },
-});
-
-const isDeferralCapped = (
-    { deferrals, firstDeferredAt, retryAt },
-    { maxDeferrals, maxDeferredMs }
-) =>
-    deferrals > maxDeferrals ||
-    retryAt.getTime() - Date.parse(firstDeferredAt) > maxDeferredMs;
-
-module.exports = {
-    MAX_DEFERRALS,
-    MAX_DEFERRALS_ENV,
-    MAX_DEFERRED_MS,
-    MAX_DEFERRED_MS_ENV,
-    MAX_DELAY_SECONDS,
-    MAX_VISIBILITY_TIMEOUT_SECONDS,
-    isDeferralCapped,
-    nextDeferral,
-    readDeferral,
-    readDeferralLimits,
-    withDeferral,
-};