@friggframework/core 2.0.0-next.10 → 2.0.0-next.101

package/modules/requester/requester.js

@@ -0,0 +1,334 @@
+const fetch = require('node-fetch');
+const { Delegate } = require('../../core');
+const { FetchError } = require('../../errors');
+const { get } = require('../../assertions');
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_AUTH_RETRIES = 3;
+
+class Requester extends Delegate {
+    constructor(params) {
+        super(params);
+        this.backOff = get(params, 'backOff', [1, 3, 10, 30, 60, 180]);
+        this.isRefreshable = false;
+        this.refreshCount = 0;
+        this.authGraceRetryCount = 0;
+        this.DLGT_INVALID_AUTH = 'INVALID_AUTH';
+        this.delegateTypes.push(this.DLGT_INVALID_AUTH);
+        this.agent = get(params, 'agent', null);
+
+        // Per-attempt HTTP timeout. Without this the framework called fetch()
+        // with no AbortController and no timeout — a silently-hung TCP
+        // connection (server accepts but never responds) blocked the calling
+        // promise forever, cascading into stalled batches, stalled syncs,
+        // and worker-lambda timeouts.
+        //
+        // Configuration precedence:
+        //   1. Instance param:   new Requester({ requestTimeoutMs: 30_000 })
+        //   2. Class static:     static requestTimeoutMs = 30_000
+        //   3. Default:          DEFAULT_REQUEST_TIMEOUT_MS (60s)
+        //
+        // Pass 0 (or null) to disable the timeout entirely — reserved for
+        // test doubles and documented long-running endpoints.
+        // Intentionally NOT using `get(params, ...)` here — the Frigg
+        // `get` helper throws RequiredPropertyError if the key is missing
+        // and no default is provided, which would collide with the fall-
+        // through to the class-level static override.
+        const instanceTimeout = params?.requestTimeoutMs;
+        this.requestTimeoutMs =
+            instanceTimeout !== undefined && instanceTimeout !== null
+                ? instanceTimeout
+                : this.constructor.requestTimeoutMs ??
+                  DEFAULT_REQUEST_TIMEOUT_MS;
+
+        // Allow passing in the fetch function
+        // Instance methods can use this.fetch without differentiating
+        this.fetch = get(params, 'fetch', fetch);
+    }
+
+    parsedBody = async (resp) => {
+        const contentType = resp.headers.get('Content-Type') || '';
+
+        if (
+            contentType.match(/^application\/json/) ||
+            contentType.match(/^application\/vnd.api\+json/) ||
+            contentType.match(/^application\/hal\+json/)
+        ) {
+            return resp.json();
+        }
+
+        return resp.text();
+    };
+
+    /**
+     * @param {string} url - The request URL, relative or absolute.
+     * @param {Object} options - Fetch options (method, headers, body, query,
+     *   returnFullRes, etc.) built by the `_get`/`_post`/`_patch`/`_put`/
+     *   `_delete` wrappers.
+     * @param {number} attempt - 0-based count of retries already made for
+     *   this call. Indexes `this.backOff` for the next delay and is passed
+     *   back in on each recursive retry.
+     */
+    async _request(url, options, attempt = 0) {
+        let encodedUrl = encodeURI(url);
+        if (options.query) {
+            let queryBuild = '?';
+            for (const key in options.query) {
+                queryBuild += `${encodeURIComponent(key)}=${encodeURIComponent(
+                    options.query[key]
+                )}&`;
+            }
+            encodedUrl += queryBuild.slice(0, -1);
+        }
+
+        options.headers = await this.addAuthHeaders(options.headers);
+
+        if (this.agent) options.agent = this.agent;
+
+        // Per-attempt timeout — fresh AbortController per call so the retry
+        // recursion (with its own backoff sleeps) always gets a clean
+        // signal. Timer is cleared in the finally block regardless of
+        // outcome.
+        const timeoutMs = this.requestTimeoutMs;
+        const controller = timeoutMs > 0 ? new AbortController() : null;
+        const timeoutHandle = controller
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : null;
+        const fetchOptions = controller
+            ? { ...options, signal: controller.signal }
+            : options;
+
+        // Timer must stay active through body consumption. node-fetch v2
+        // resolves the fetch() promise when headers arrive, not when the
+        // body is fully read — so a server that sends headers and then
+        // stalls the body would still hang parsedBody() or
+        // FetchError.create()'s response.text() call. We clear the timer
+        // only after the body is fully consumed (success path) or
+        // deliberately before each recursive retry so the new attempt
+        // starts with its own fresh timer.
+        let timerCleared = false;
+        const clearRequestTimer = () => {
+            if (!timerCleared && timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timerCleared = true;
+            }
+        };
+
+        try {
+            let response;
+            try {
+                response = await this.fetch(encodedUrl, fetchOptions);
+            } catch (e) {
+                // AbortController fires AbortError (name) / ETIMEDOUT-shaped
+                // errors (type on node-fetch) when we hit the timeout. No
+                // retry on timeout: a slow endpoint is a downstream problem,
+                // and each retry would wait another `timeoutMs` before giving
+                // up — amplifying the hang into a per-record multi-minute
+                // stall at batch scale.
+                const isTimeout =
+                    e?.name === 'AbortError' || e?.type === 'aborted';
+                if (e?.code === 'ECONNRESET' && attempt < this.backOff.length) {
+                    clearRequestTimer();
+                    const delay = this.backOff[attempt] * 1000;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    return this._request(url, options, attempt + 1);
+                }
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    responseBody: isTimeout
+                        ? `Request timed out after ${timeoutMs}ms`
+                        : e,
+                });
+                if (isTimeout) {
+                    // Flag + machine-readable fields so callers can
+                    // distinguish a timeout from a generic network error
+                    // without parsing the message (which FetchError
+                    // sanitizes outside of STAGE=dev).
+                    fetchError.isTimeout = true;
+                    fetchError.timeoutMs = timeoutMs;
+                }
+                throw fetchError;
+            }
+
+            const { status } = response;
+
+            // If the status is retriable and there are back off requests left, retry the request
+            if (
+                (status === 429 || status >= 500) &&
+                attempt < this.backOff.length
+            ) {
+                clearRequestTimer();
+                const delay = this.backOff[attempt] * 1000;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this._request(url, options, attempt + 1);
+            }
+
+            if (status === 401) {
+                if (!this.isRefreshable) {
+                    // Up to MAX_AUTH_RETRIES grace retries before invalidating
+                    // — a 401 alone isn't proof the credential is bad.
+                    if (
+                        this.authGraceRetryCount < MAX_AUTH_RETRIES &&
+                        this.authGraceRetryCount < this.backOff.length
+                    ) {
+                        const delay =
+                            this.backOff[this.authGraceRetryCount] * 1000;
+                        this.authGraceRetryCount++;
+                        clearRequestTimer();
+                        await new Promise((resolve) =>
+                            setTimeout(resolve, delay)
+                        );
+                        return this._request(url, options, attempt + 1);
+                    }
+
+                    throw await this._invalidateAuth(
+                        encodedUrl,
+                        options,
+                        response
+                    );
+                }
+
+                if (this.refreshCount < MAX_AUTH_RETRIES) {
+                    this.refreshCount++;
+                    const refreshSucceeded = await this.refreshAuth();
+                    if (refreshSucceeded) {
+                        clearRequestTimer();
+                        return this._request(url, options, attempt + 1);
+                    }
+
+                    throw await this._invalidateAuth(
+                        encodedUrl,
+                        options,
+                        response
+                    );
+                }
+
+                throw await this._invalidateAuth(encodedUrl, options, response);
+            }
+
+            // If the error wasn't retried, throw. FetchError.create reads
+            // the response body (response.text()) — timer must still be
+            // alive to catch a stalled body stream.
+            if (status >= 400) {
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    response,
+                });
+                throw this._maybeFlagTimeoutDuringBodyRead(
+                    fetchError,
+                    timeoutMs
+                );
+            }
+
+            // Successful response: reset the per-instance refresh budget so
+            // a later 401 in the same Requester lifetime can attempt refresh
+            // again instead of silently falling through.
+            this.refreshCount = 0;
+            this.authGraceRetryCount = 0;
+
+            // parsedBody consumes the response body stream. If the server
+            // stalls mid-stream the timer (still armed) aborts it.
+            return options.returnFullRes
+                ? response
+                : await this.parsedBody(response);
+        } catch (e) {
+            // If the abort fired during body consumption, node-fetch emits
+            // the error as an AbortError on the body stream. Surface the
+            // same isTimeout flag callers use for header-phase timeouts.
+            throw this._maybeFlagTimeoutDuringBodyRead(e, timeoutMs);
+        } finally {
+            clearRequestTimer();
+        }
+    }
+
+    async _invalidateAuth(encodedUrl, options, response) {
+        const fetchError = await FetchError.create({
+            resource: encodedUrl,
+            init: options,
+            response,
+        });
+        await this.notify(this.DLGT_INVALID_AUTH, fetchError);
+        return fetchError;
+    }
+
+    _maybeFlagTimeoutDuringBodyRead(err, timeoutMs) {
+        if (!err || typeof err !== 'object') return err;
+        if (err.isTimeout) return err;
+        const isAbort = err.name === 'AbortError' || err.type === 'aborted';
+        if (!isAbort) return err;
+        err.isTimeout = true;
+        err.timeoutMs = timeoutMs;
+        return err;
+    }
+
+    async _get(options) {
+        const fetchOptions = {
+            method: 'GET',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            returnFullRes: options.returnFullRes || false,
+        };
+
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _post(options, stringify = true) {
+        const fetchOptions = {
+            method: 'POST',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _patch(options, stringify = true) {
+        const fetchOptions = {
+            method: 'PATCH',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _put(options, stringify = true) {
+        const fetchOptions = {
+            method: 'PUT',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            body: stringify ? JSON.stringify(options.body) : options.body,
+            returnFullRes: options.returnFullRes || false,
+        };
+        const res = await this._request(options.url, fetchOptions);
+        return res;
+    }
+
+    async _delete(options) {
+        const fetchOptions = {
+            method: 'DELETE',
+            credentials: 'include',
+            headers: options.headers || {},
+            query: options.query || {},
+            returnFullRes: options.returnFullRes || true,
+        };
+        return this._request(options.url, fetchOptions);
+    }
+
+    async refreshAuth() {
+        throw new Error('refreshAuth not yet defined in child of Requester');
+    }
+}
+
+module.exports = { Requester };

package/{module-plugin → modules}/test/mock-api/api.js

@@ -1,5 +1,5 @@
-const { get } = require('../../assertions');
-const { OAuth2Requester } = require('../../module-plugin');
+const { get } = require('../../../assertions');
+const { OAuth2Requester } = require('../..');
 
 class Api extends OAuth2Requester {
     constructor(params) {
@@ -23,7 +23,12 @@ class Api extends OAuth2Requester {
         return this.authorizationUri;
     }
 
-
+    getAuthorizationRequirements() {
+        return {
+            url: this.getAuthUri(),
+            type: 'oauth2',
+        };
+    }
 }
 
 module.exports = { Api };

package/{module-plugin → modules}/test/mock-api/definition.js

@@ -1,22 +1,26 @@
 require('dotenv').config();
-const {Api} = require('./api');
-const {get} = require('../../assertions');
-const config = {name: 'anapi'}
+const { Api } = require('./api');
+const { get } = require('../../../assertions');
+const config = { name: 'anapi' }
 
 const Definition = {
     API: Api,
-    getName: function() {return config.name},
+    getAuthorizationRequirements: () => ({
+        url: 'http://localhost:3000/redirect/anapi',
+        type: 'oauth2',
+    }),
+    getName: function () { return config.name },
     moduleName: config.name,
     modelName: 'AnApi',
     requiredAuthMethods: {
-        getToken: async function(api, params){
+        getToken: async function (api, params) {
             const code = get(params.data, 'code');
             return api.getTokenFromCode(code);
         },
-        getEntityDetails: async function(api, callbackParams, tokenResponse, userId) {
+        getEntityDetails: async function (api, callbackParams, tokenResponse, userId) {
             const userDetails = await api.getUserDetails();
             return {
-                identifiers: { externalId: userDetails.portalId, user: userId },
+                identifiers: { externalId: userDetails.portalId, userId },
                 details: { name: userDetails.hub_domain },
             }
         },
@@ -26,14 +30,14 @@ const Definition = {
             ],
             entity: [],
         },
-        getCredentialDetails: async function(api, userId) {
+        getCredentialDetails: async function (api, userId) {
             const userDetails = await api.getUserDetails();
             return {
-                identifiers: { externalId: userDetails.portalId, user: userId },
+                identifiers: { externalId: userDetails.portalId, userId },
                 details: {}
             };
         },
-        testAuthRequest: async function(api){
+        testAuthRequest: async function (api) {
             return api.getUserDetails()
         },
     },

package/modules/tests/doubles/test-module-factory.js

@@ -0,0 +1,16 @@
+class TestModuleFactory {
+    constructor() { }
+
+    async getModuleInstance(entityId, userId) {
+        // return minimal stub module with getName and api property
+        return {
+            getName() { return 'stubModule'; },
+            api: {},
+            entityId,
+            userId,
+            testAuth: async () => true,
+        };
+    }
+}
+
+module.exports = { TestModuleFactory }; 

package/modules/tests/doubles/test-module-repository.js

@@ -0,0 +1,39 @@
+class TestModuleRepository {
+    constructor() {
+        this.entities = new Map();
+    }
+
+    addEntity(entity) {
+        this.entities.set(entity.id, entity);
+    }
+
+    async findEntityById(id) {
+        return this.entities.get(id);
+    }
+
+    async findEntitiesByIds(ids) {
+        return ids.map((id) => this.entities.get(id));
+    }
+
+    async findEntity(filter) {
+        if (!filter || typeof filter !== 'object') {
+            return null;
+        }
+
+        if (filter.id && this.entities.has(filter.id)) {
+            return this.entities.get(filter.id);
+        }
+
+        if (filter.externalId) {
+            for (const entity of this.entities.values()) {
+                if (entity.externalId === filter.externalId) {
+                    return entity;
+                }
+            }
+        }
+
+        return null;
+    }
+}
+
+module.exports = { TestModuleRepository }; 

package/modules/use-cases/get-entities-for-user.js

@@ -0,0 +1,32 @@
+const { Module } = require('../module');
+const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+
+class GetEntitiesForUser {
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+
+        this.definitionMap = new Map();
+        for (const definition of moduleDefinitions) {
+            this.definitionMap.set(definition.moduleName, definition);
+        }
+    }
+
+    async execute(userId) {
+        const entities = await this.moduleRepository.findEntitiesByUserId(
+            userId
+        );
+
+        return entities.map((entity) => {
+            const definition = this.definitionMap.get(entity.moduleName);
+
+            const moduleInstance = new Module({
+                userId,
+                definition: definition,
+                entity: entity,
+            });
+            return mapModuleClassToModuleDTO(moduleInstance);
+        });
+    }
+}
+
+module.exports = { GetEntitiesForUser }; 

package/modules/use-cases/get-entity-options-by-id.js

@@ -0,0 +1,71 @@
+const { Module } = require('../module');
+
+class GetEntityOptionsById {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve entity options for a given entity
+     *
+     * @param {string|number} entityId - Entity ID to retrieve options for
+     * @param {string|number|import('../../user/user').User} userIdOrUser - User ID or User object for validation
+     * @returns {Promise<Object>} Entity options
+     */
+    async execute(entityId, userIdOrUser) {
+        // Support both userId (backward compatible) and User object (new pattern)
+        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
+            ? userIdOrUser.getId()
+            : userIdOrUser;
+
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        // Validate entity ownership
+        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+            ? userIdOrUser.ownsUserId(entity.userId)
+            : entity.userId?.toString() === userId?.toString();
+
+        if (!isOwned) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.moduleName;
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            const modelName =
+                Module.getEntityModelFromDefinition(def).modelName;
+            return entityType === modelName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for entity type: ${entityType}`
+            );
+        }
+
+        const module = new Module({
+            userId,
+            entity,
+            definition: moduleDefinition,
+        });
+
+        const entityOptions = await module.getEntityOptions();
+        return entityOptions;
+    }
+}
+
+module.exports = { GetEntityOptionsById };

package/modules/use-cases/get-entity-options-by-type.js

@@ -0,0 +1,34 @@
+const { Module } = require('../module');
+
+class GetEntityOptionsByType {
+    /**
+     * @param {Object} params
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleDefinitions }) {
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve a Module instance for a given user and entity/module type.
+     * @param {string} userId
+     * @param {string} type – human-readable module/entity type (e.g. "Hubspot")
+     */
+    async execute(userId, type) {
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.getName() === type
+        );
+        if (!moduleDefinition) {
+            throw new Error(`Module definition not found for type: ${type}`);
+        }
+        const moduleInstance = new Module({
+            userId,
+            definition: moduleDefinition,
+        });
+
+        const entityOptions = await moduleInstance.getEntityOptions();
+        return entityOptions;
+    }
+}
+
+module.exports = { GetEntityOptionsByType };

package/modules/use-cases/get-module-instance-from-type.js

@@ -0,0 +1,34 @@
+const { Module } = require('../module');
+
+class GetModuleInstanceFromType {
+    /**
+     * @param {Object} params
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleDefinitions }) {
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve a Module instance for a given user and entity/module type.
+     * @param {string} userId
+     * @param {string} type – human-readable module/entity type (e.g. "Hubspot")
+     * @param {Object} [options]
+     * @param {string} [options.state] – optional OAuth state value to be forwarded to the API client (round-trips through the OAuth provider).
+     */
+    async execute(userId, type, options = {}) {
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.getName() === type
+        );
+        if (!moduleDefinition) {
+            throw new Error(`Module definition not found for type: ${type}`);
+        }
+        return new Module({
+            userId,
+            definition: moduleDefinition,
+            state: options.state,
+        });
+    }
+}
+
+module.exports = { GetModuleInstanceFromType };