@friggframework/core 2.0.0-next.111 → 2.0.0-next.113

package/integrations/repositories/integration-mapping-query.js

@@ -0,0 +1,193 @@
+const SEGMENT_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_TAKE = 500;
+const MAX_IN_VALUES = 500;
+const MAX_CONDITIONS = 20;
+const DIRECTIONS = ['asc', 'desc'];
+
+const OPERATORS = {
+    exists: { fields: ['mapping'] },
+    notExists: { fields: ['mapping'] },
+    in: { fields: ['mapping'], value: toStringList },
+    notStartsWith: { fields: ['sourceId'], value: toPrefix },
+};
+
+/**
+ * Checks a queryMappings query and normalizes it for an adapter.
+ *
+ * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+ * @returns {{where: Array<Object>, orderBy: ({path: string[], direction: 'asc'|'desc'}|null), skip: number, take: number, omit: string[]}}
+ * @throws {Error} When the query does not fit that shape
+ */
+function validateMappingQuery(query) {
+    if (!isPlainObject(query)) {
+        throw new Error('queryMappings: query must be an object');
+    }
+    const { where = [], orderBy, skip = 0, take, omit = [] } = query;
+    if (!Array.isArray(where)) {
+        throw new Error('queryMappings: where must be an array');
+    }
+    if (!Number.isInteger(take) || take < 1 || take > MAX_TAKE) {
+        throw new Error(
+            `queryMappings: take must be an integer between 1 and ${MAX_TAKE}`
+        );
+    }
+    if (!Number.isSafeInteger(skip) || skip < 0) {
+        throw new Error('queryMappings: skip must be a non-negative integer');
+    }
+    if (
+        !Array.isArray(omit) ||
+        !omit.every((key) => typeof key === 'string' && SEGMENT_REGEX.test(key))
+    ) {
+        throw new Error(
+            `queryMappings: omit must be an array of top-level mapping keys matching ${SEGMENT_REGEX}`
+        );
+    }
+
+    const whereEntries = where.map(toWhereEntry);
+    const conditionCount = whereEntries.reduce(
+        (count, entry) => count + (entry.anyOf ? entry.anyOf.length : 1),
+        0
+    );
+    if (conditionCount > MAX_CONDITIONS) {
+        throw new Error(
+            `queryMappings: where must have at most ${MAX_CONDITIONS} conditions, anyOf members included`
+        );
+    }
+
+    return {
+        where: whereEntries,
+        orderBy: orderBy === undefined ? null : toOrderBy(orderBy),
+        skip,
+        take,
+        omit,
+    };
+}
+
+function toOrderBy(orderBy) {
+    if (!isPlainObject(orderBy)) {
+        throw new Error('queryMappings: orderBy must be an object');
+    }
+    const { field, segments } = parsePath(orderBy.path);
+    if (field !== 'mapping') {
+        throw new Error(
+            "queryMappings: orderBy.path must be a mapping path ('mapping.<segment>...')"
+        );
+    }
+    if (!DIRECTIONS.includes(orderBy.direction)) {
+        throw new Error(
+            "queryMappings: orderBy.direction must be 'asc' or 'desc'"
+        );
+    }
+    return { path: segments, direction: orderBy.direction };
+}
+
+function toWhereEntry(entry) {
+    assertWhereEntryShape(entry);
+    if (!('anyOf' in entry)) return toCondition(entry);
+
+    const { anyOf } = entry;
+    if (!Array.isArray(anyOf) || anyOf.length === 0) {
+        throw new Error('queryMappings: anyOf must be a non-empty array');
+    }
+    return {
+        anyOf: anyOf.map((condition) => {
+            assertWhereEntryShape(condition);
+            if ('anyOf' in condition) {
+                throw new Error('queryMappings: nested anyOf is not supported');
+            }
+            return toCondition(condition);
+        }),
+    };
+}
+
+function assertWhereEntryShape(entry) {
+    if (!isPlainObject(entry)) {
+        throw new Error('queryMappings: each where entry must be an object');
+    }
+}
+
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * `{ path: 'mapping.outbound.status', op: 'in', value: ['failed'] }` →
+ * `{ field: 'mapping', path: ['outbound', 'status'], op: 'in', value: ['failed'] }`.
+ * A `sourceId` condition has no `path`; an op without a value has no `value`.
+ */
+function toCondition({ path, op, value }) {
+    const { field, segments } = parsePath(path);
+    const operator = Object.hasOwn(OPERATORS, op) ? OPERATORS[op] : null;
+    if (!operator?.fields.includes(field)) {
+        throw new Error(
+            `queryMappings: op ${JSON.stringify(
+                op
+            )} is not allowed on '${path}' (allowed: ${operatorsOn(field).join(
+                ', '
+            )})`
+        );
+    }
+    return {
+        field,
+        ...(segments.length > 0 && { path: segments }),
+        op,
+        ...(operator.value && { value: operator.value(value, path) }),
+    };
+}
+
+function operatorsOn(field) {
+    return Object.keys(OPERATORS).filter((op) =>
+        OPERATORS[op].fields.includes(field)
+    );
+}
+
+function toStringList(value, path) {
+    if (
+        !Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((v) => typeof v === 'string')
+    ) {
+        throw new Error(
+            `queryMappings: 'in' value must be a non-empty array of strings on '${path}'`
+        );
+    }
+    if (value.length > MAX_IN_VALUES) {
+        throw new Error(
+            `queryMappings: 'in' value must have at most ${MAX_IN_VALUES} strings on '${path}'`
+        );
+    }
+    return value;
+}
+
+function toPrefix(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(
+            `queryMappings: 'notStartsWith' value must be a non-empty string on '${path}'`
+        );
+    }
+    return value;
+}
+
+/**
+ * `'mapping.outbound.status'` → `{ field: 'mapping', segments: ['outbound', 'status'] }`,
+ * `'sourceId'` → `{ field: 'sourceId', segments: [] }`.
+ */
+function parsePath(path) {
+    const [field, ...segments] =
+        typeof path === 'string' ? path.split('.') : [];
+    const valid =
+        (field === 'sourceId' && segments.length === 0) ||
+        (field === 'mapping' &&
+            segments.length > 0 &&
+            segments.every((segment) => SEGMENT_REGEX.test(segment)));
+    if (!valid) {
+        throw new Error(
+            `queryMappings: invalid path ${JSON.stringify(
+                path
+            )} (must be 'sourceId' or 'mapping.<segment>...' with segments matching ${SEGMENT_REGEX})`
+        );
+    }
+    return { field, segments };
+}
+
+module.exports = { validateMappingQuery };

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

@@ -8,6 +8,7 @@ const {
     updateOne,
     deleteOne,
     deleteMany,
+    aggregate,
     aggregateDrained,
 } = require('../../database/documentdb-utils');
 const {
@@ -16,6 +17,20 @@ const {
 const {
     DocumentDBEncryptionService,
 } = require('../../database/documentdb-encryption-service');
+const {
+    assertMappingWrittenUnencrypted,
+} = require('../../database/encryption/integration-mapping-encryption');
+const { validateMappingQuery } = require('./integration-mapping-query');
+const {
+    buildMappingQueryStages,
+} = require('./integration-mapping-query-pipeline');
+
+function storedIntegrationId(id) {
+    if (!['string', 'number'].includes(typeof id) || id === '') {
+        throw new TypeError(`Invalid ID: ${id}`);
+    }
+    return String(id);
+}
 
 class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositoryInterface {
     constructor() {
@@ -179,6 +194,44 @@ class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositor
         return decryptedDocs.map((doc) => this._mapMapping(doc));
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const validated = validateMappingQuery(query);
+        const stored = storedIntegrationId(integrationId);
+        assertMappingWrittenUnencrypted();
+        const { match, page, sort } = buildMappingQueryStages(
+            stored,
+            validated
+        );
+
+        const [docs, counts] = await Promise.all([
+            aggregateDrained(
+                this.prisma,
+                'IntegrationMapping',
+                [match, ...page, sort],
+                { allowDiskUse: true }
+            ),
+            aggregate(this.prisma, 'IntegrationMapping', [
+                match,
+                { $count: 'total' },
+            ]),
+        ]);
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('IntegrationMapping', doc)
+            )
+        );
+
+        return {
+            mappings: decryptedDocs.map((doc) => this._mapMapping(doc)),
+            total: counts[0]?.total ?? 0,
+        };
+    }
+
     async deleteMapping(integrationId, sourceId) {
         const filter = this._compositeFilter(integrationId, sourceId);
         const result = await deleteOne(

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

@@ -52,6 +52,54 @@ class IntegrationMappingRepositoryInterface {
         );
     }
 
+    /**
+     * Query one filtered, ordered page of an integration's mappings without
+     * loading every row. Rows have the same shape as findMappingsByIntegration
+     * and are decrypted the same way.
+     *
+     * Paths address the `mapping` JSON by identifier-only segments
+     * (`'mapping.outbound.status'`), or the `sourceId` column. Conditions:
+     * - `{ path: 'mapping.…', op: 'exists' | 'notExists' }` — JSON null counts
+     *   as absent; notExists is the exact negation of exists.
+     * - `{ path: 'mapping.…', op: 'in', value: string[] }` — matches JSON
+     *   strings; 1–500 values.
+     * - `{ path: 'sourceId', op: 'notStartsWith', value: string }` — a NULL
+     *   sourceId matches.
+     *
+     * Only rows whose `mapping` is a JSON object can match, so rows whose
+     * whole `mapping` is still ciphertext from before an encryption opt-out
+     * never do. A nested path still encrypted from before its opt-out comes
+     * back plain, but conditions and orderBy on it see the ciphertext.
+     * Adapters refuse to run while field-level encryption is enabled
+     * and still encrypts `mapping`, or a path inside it, on write; opt out with
+     * `appDefinition.encryption.disable = { IntegrationMapping: ['mapping'] }`
+     * plus any nested `mapping.…` path a custom schema encrypts.
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {Object} query
+     * @param {Array<Object>} [query.where=[]] - Conditions ANDed together; an
+     *   entry may be `{ anyOf: Condition[] }` (one level, ORed). At most 20
+     *   conditions, anyOf members included.
+     * @param {{path: string, direction: 'asc'|'desc'}} [query.orderBy] - A
+     *   mapping path; nulls last, ties broken by id in the same direction.
+     *   Values order string < number < boolean < array < object. Strings
+     *   compare by the database collation on PostgreSQL and by code point on
+     *   MongoDB and DocumentDB; arrays and objects order among themselves
+     *   only on PostgreSQL. Without it rows are ordered by id ascending.
+     * @param {number} [query.skip=0] - Rows to skip (integer ≥ 0)
+     * @param {number} query.take - Page size (integer 1–500)
+     * @param {string[]} [query.omit=[]] - Top-level mapping keys to leave out of
+     *   the returned rows; such projected rows must not be written back
+     * @returns {Promise<{mappings: Array<Object>, total: number}>} The page, and
+     *   the number of rows matching `where` (counted by a separate command on
+     *   DocumentDB, so not from the page's snapshot)
+     */
+    async queryMappings(integrationId, query) {
+        throw new Error(
+            'queryMappings is not supported by this database adapter yet'
+        );
+    }
+
     /**
      * Delete a specific mapping
      *

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

@@ -1,7 +1,26 @@
 const { prisma } = require('../../database/prisma');
+const {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+} = require('../../database/encryption/integration-mapping-encryption');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
+const { validateMappingQuery } = require('./integration-mapping-query');
+const {
+    buildMappingQueryStages,
+} = require('./integration-mapping-query-pipeline');
+
+const OBJECT_ID_REGEX = /^[0-9a-fA-F]{24}$/;
+
+const fromRawDate = (raw) => new Date(raw.$date);
+
+function strictObjectId(id) {
+    if (typeof id !== 'string' || !OBJECT_ID_REGEX.test(id)) {
+        throw new TypeError(`Invalid ID: ${id} is not an ObjectId`);
+    }
+    return id;
+}
 
 /**
  * MongoDB Integration Mapping Repository Adapter
@@ -155,6 +174,59 @@ class IntegrationMappingRepositoryMongo extends IntegrationMappingRepositoryInte
         return counts;
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const validated = validateMappingQuery(query);
+        const objectId = strictObjectId(integrationId);
+        assertMappingWrittenUnencrypted();
+        const { match, page } = buildMappingQueryStages(
+            { $oid: objectId },
+            validated
+        );
+
+        const result = await this.prisma.$runCommandRaw({
+            aggregate: 'IntegrationMapping',
+            pipeline: [
+                match,
+                {
+                    $facet: {
+                        mappings: page,
+                        total: [{ $count: 'total' }],
+                    },
+                },
+            ],
+            cursor: {},
+            allowDiskUse: true,
+        });
+        const [{ mappings, total }] = result.cursor.firstBatch;
+
+        return {
+            mappings: await decryptQueriedMappings(
+                mappings.map((doc) => this._fromRawMapping(doc))
+            ),
+            total: total[0]?.total ?? 0,
+        };
+    }
+
+    /**
+     * A raw aggregate document, in the shape findMappingsByIntegration returns.
+     * @private
+     */
+    _fromRawMapping(doc) {
+        return {
+            id: doc._id.$oid,
+            integrationId: doc.integrationId.$oid,
+            sourceId: doc.sourceId ?? null,
+            mapping: doc.mapping ?? null,
+            createdAt: fromRawDate(doc.createdAt),
+            updatedAt: fromRawDate(doc.updatedAt),
+        };
+    }
+
     /**
      * Find mapping by ID
      * @param {string} id - Mapping ID

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

@@ -1,8 +1,31 @@
 const { prisma } = require('../../database/prisma');
+const {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+} = require('../../database/encryption/integration-mapping-encryption');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
 const { strictIntId } = require('./report-id');
+const { validateMappingQuery } = require('./integration-mapping-query');
+
+const COLUMNS = { mapping: '"mapping"', sourceId: '"sourceId"' };
+const SQL_DIRECTIONS = { asc: 'ASC', desc: 'DESC' };
+
+const jsonPathOperand = (column, path) => ({
+    json: `${column} #> ${path}::text[]`,
+    text: `${column} #>> ${path}::text[]`,
+});
+const jsonType = (json) => `COALESCE(jsonb_typeof(${json}), 'null')`;
+
+const CONDITION_SQL = {
+    exists: ({ json }) => `${jsonType(json)} <> 'null'`,
+    notExists: ({ json }) => `${jsonType(json)} = 'null'`,
+    in: ({ json, text, value }) =>
+        `(jsonb_typeof(${json}) = 'string' AND ${text} = ANY(${value}::text[]))`,
+    notStartsWith: ({ text, value }) =>
+        `(${text} IS NULL OR NOT starts_with(${text}, ${value}::text))`,
+};
 
 /**
  * PostgreSQL Integration Mapping Repository Adapter
@@ -216,6 +239,101 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
         return counts;
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const { where, orderBy, skip, take, omit } =
+            validateMappingQuery(query);
+        const intIntegrationId = strictIntId(integrationId);
+        assertMappingWrittenUnencrypted();
+
+        const params = [];
+        const bind = (v) => {
+            params.push(v);
+            return `$${params.length}`;
+        };
+
+        const whereSql = [
+            `"integrationId" = ${bind(intIntegrationId)}::int`,
+            `jsonb_typeof("mapping") = 'object'`,
+            ...where.map((entry) => this._whereEntrySql(entry, bind)),
+        ].join(' AND ');
+        const orderSql = orderBy ? this._orderSql(orderBy, bind) : `"id" ASC`;
+        const mappingSql =
+            omit.length > 0
+                ? `"mapping" - ${bind(omit)}::text[] AS "mapping"`
+                : `"mapping"`;
+
+        const sql = `
+            WITH "matched" AS (
+                SELECT "id", "integrationId", "sourceId", "mapping", "createdAt", "updatedAt"
+                FROM "IntegrationMapping"
+                WHERE ${whereSql}
+            ),
+            "page" AS (
+                SELECT * FROM "matched"
+                ORDER BY ${orderSql}
+                OFFSET ${bind(skip)}::bigint
+                LIMIT ${bind(take)}::int
+            )
+            SELECT "id", "integrationId", "sourceId", ${mappingSql}, "createdAt", "updatedAt",
+                (SELECT COUNT(*)::int FROM "matched") AS "__total"
+            FROM (VALUES (1)) AS "one"
+            LEFT JOIN "page" ON true
+            ORDER BY ${orderSql}
+        `;
+        const rows = await this.prisma.$queryRawUnsafe(sql, ...params);
+        const mappings = await decryptQueriedMappings(
+            rows
+                .filter((row) => row.id !== null)
+                .map(({ __total, ...row }) => this._convertMappingIds(row))
+        );
+
+        return { mappings, total: rows[0].__total };
+    }
+
+    /**
+     * One where entry: a condition, or an anyOf group as a parenthesized OR.
+     * @private
+     */
+    _whereEntrySql(entry, bind) {
+        if (!entry.anyOf) return this._conditionSql(entry, bind);
+        const alternatives = entry.anyOf.map((condition) =>
+            this._conditionSql(condition, bind)
+        );
+        return `(${alternatives.join(' OR ')})`;
+    }
+
+    /**
+     * SQL predicate for one validated queryMappings condition. `exists`
+     * treats JSON null as absent, and `notExists` is its exact negation.
+     * @private
+     */
+    _conditionSql({ field, path, op, value }, bind) {
+        const column = COLUMNS[field];
+        const operand = path
+            ? jsonPathOperand(column, bind(path))
+            : { text: column };
+        return CONDITION_SQL[op]({
+            ...operand,
+            value: value === undefined ? undefined : bind(value),
+        });
+    }
+
+    /**
+     * NULLIF folds JSON null into SQL NULL, so both sort after every value.
+     * @private
+     */
+    _orderSql({ path, direction }, bind) {
+        const { json } = jsonPathOperand(COLUMNS.mapping, bind(path));
+        const value = `NULLIF(${json}, 'null'::jsonb)`;
+        const sqlDirection = SQL_DIRECTIONS[direction];
+        return `${value} ${sqlDirection} NULLS LAST, "id" ${sqlDirection}`;
+    }
+
     /**
      * Find mapping by ID
      * @param {string} id - Mapping ID (string from application layer)

package/integrations/use-cases/delete-integration-for-user.js

@@ -1,4 +1,7 @@
 const Boom = require('@hapi/boom');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.integrations');
 // Removed Integration wrapper - using IntegrationBase directly
 
 /**
@@ -65,17 +68,25 @@ class DeleteIntegrationForUser {
                 );
                 modules.push(moduleInstance);
             } catch (error) {
-                console.error(
-                    `[Integration Deletion] Failed to load module for entity ${entityId}:`,
-                    error.message
-                );
+                log.warn('Failed to load module for deletion', {
+                    eventName: 'frigg.integrations.delete_module_load_failed',
+                    integrationId,
+                    entityId,
+                    error,
+                });
                 failedModuleLoads.push({ entityId, error: error.message });
             }
         }
 
         if (failedModuleLoads.length > 0) {
-            console.warn(
-                `[Integration Deletion] ${failedModuleLoads.length}/${integrationRecord.entitiesIds.length} module(s) failed to load. Webhooks for these modules may require manual cleanup.`
+            log.warn(
+                'Some modules failed to load. Webhooks for these modules may require manual cleanup.',
+                {
+                    eventName: 'frigg.integrations.delete_modules_incomplete',
+                    integrationId,
+                    failedCount: failedModuleLoads.length,
+                    totalCount: integrationRecord.entitiesIds.length,
+                }
             );
         }
 
@@ -97,19 +108,19 @@ class DeleteIntegrationForUser {
         try {
             await integrationInstance.send('ON_DELETE');
         } catch (error) {
-            const reason = error?.message ?? String(error);
-            console.error(
-                `[Integration Deletion] onDelete failed for integration ${integrationId}, leaving it IN_DELETION:`,
-                reason
-            );
+            // The error text can echo a request with its credentials and
+            // messages reach end users; the boundary logs the cause once.
             await integrationInstance.updateIntegrationMessages.execute(
                 integrationId,
                 'errors',
                 'Integration Deletion Error',
-                `Deletion did not complete: ${reason}`,
+                'Deletion did not complete. Contact support.',
                 Date.now()
             );
-            throw error;
+            throw new Error(
+                `Integration ${integrationId} deletion did not complete`,
+                { cause: error }
+            );
         }
 
         await this.integrationRepository.deleteIntegrationById(integrationId);

package/jest.config.js

@@ -18,4 +18,6 @@ module.exports = {
 
     // A path to a module which exports an async function that is triggered once after all test suites
     globalTeardown: './jest-teardown.js',
+
+    setupFilesAfterEnv: ['./logs/jest-logger-setup.js'],
 };

package/logs/.eslintrc.json

@@ -1,3 +1,28 @@
 {
-    "extends": "@friggframework/eslint-config"
+    "extends": "@friggframework/eslint-config",
+    "rules": {
+        "no-console": "error",
+        "no-restricted-syntax": [
+            "error",
+            {
+                "selector": "CallExpression[callee.object.object.name='process'][callee.object.property.name=/^(stdout|stderr)$/][callee.property.name='write']",
+                "message": "Write through the logger; only logs/sinks.js writes to fd 1"
+            }
+        ]
+    },
+    "overrides": [
+        {
+            "files": ["*.test.js", "__fixtures__/**", "jest-logger-setup.js"],
+            "rules": {
+                "no-console": "off",
+                "no-restricted-syntax": "off"
+            }
+        },
+        {
+            "files": ["sinks.js"],
+            "rules": {
+                "no-restricted-syntax": "off"
+            }
+        }
+    ]
 }