@friggframework/core 2.0.0--canary.636.7dc8dca.0 → 2.0.0--canary.651.87132bf.0

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

@@ -0,0 +1,176 @@
+/**
+ * Validation for IntegrationMappingRepository.queryMappings().
+ *
+ * Backend-agnostic: enforces the query shape BEFORE an adapter builds a
+ * database command, so every adapter rejects the same input. Paths come out
+ * split into identifier-only segments that adapters pass as bound
+ * parameters; nothing from the query is spliced into SQL text.
+ */
+
+const SEGMENT_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_TAKE = 500;
+const MAX_IN_VALUES = 500;
+const MAX_CONDITIONS = 20;
+const SQL_DIRECTIONS = { asc: 'ASC', desc: 'DESC' };
+
+const OPS_BY_FIELD = {
+    mapping: ['exists', 'notExists', 'in'],
+    sourceId: ['notStartsWith'],
+};
+
+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 (!Object.hasOwn(SQL_DIRECTIONS, orderBy.direction)) {
+        throw new Error(
+            "queryMappings: orderBy.direction must be 'asc' or 'desc'"
+        );
+    }
+    return { segments, direction: SQL_DIRECTIONS[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);
+}
+
+function toCondition({ path, op, value }) {
+    const { field, segments } = parsePath(path);
+    const allowed = OPS_BY_FIELD[field];
+    if (!allowed.includes(op)) {
+        throw new Error(
+            `queryMappings: op ${JSON.stringify(
+                op
+            )} is not allowed on '${path}' (allowed: ${allowed.join(', ')})`
+        );
+    }
+
+    if (op === 'in') {
+        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 { field, segments, op, value };
+    }
+
+    if (op === 'notStartsWith') {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(
+                `queryMappings: 'notStartsWith' value must be a non-empty string on '${path}'`
+            );
+        }
+        return { field, segments, op, value };
+    }
+
+    return { field, segments, op };
+}
+
+/**
+ * `'mapping.c2h.lastStatus'` → `{ field: 'mapping', segments: ['c2h', 'lastStatus'] }`,
+ * `'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 = { SEGMENT_REGEX, validateMappingQuery };

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

@@ -179,6 +179,14 @@ class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositor
         return decryptedDocs.map((doc) => this._mapMapping(doc));
     }
 
+    /**
+     * Not implemented for DocumentDB yet; only the PostgreSQL adapter supports it.
+     * @throws {Error} Always
+     */
+    async queryMappings() {
+        throw new Error('queryMappings is not supported on DocumentDB yet');
+    }
+
     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,51 @@ class IntegrationMappingRepositoryInterface {
         );
     }
 
+    /**
+     * Query one filtered, ordered page of an integration's mappings without
+     * loading every row. Rows have the same shape as findMappingsByIntegration.
+     *
+     * Cost: each call is O(rows of the integration × mapping size) in the
+     * database, because JSON paths are evaluated per row and no JSON index
+     * exists. That is fine at ~10⁴ rows per integration and takes seconds per
+     * call at 10⁵+.
+     *
+     * Paths address the `mapping` JSON by identifier-only segments
+     * (`'mapping.c2h.lastStatus'`), 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. 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.
+     *   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`
+     * @abstract
+     */
+    async queryMappings(integrationId, query) {
+        throw new Error('Method queryMappings must be implemented by subclass');
+    }
+
     /**
      * Delete a specific mapping
      *

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

@@ -87,6 +87,14 @@ class IntegrationMappingRepositoryMongo extends IntegrationMappingRepositoryInte
         });
     }
 
+    /**
+     * Not implemented for MongoDB yet; only the PostgreSQL adapter supports it.
+     * @throws {Error} Always
+     */
+    async queryMappings() {
+        throw new Error('queryMappings is not supported on MongoDB yet');
+    }
+
     /**
      * Delete a mapping by integration and source ID
      * Replaces: IntegrationMapping.deleteOne({ integration, sourceId })

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

@@ -1,8 +1,18 @@
-const { prisma } = require('../../database/prisma');
+const { prisma, getEncryptionConfig } = require('../../database/prisma');
+const {
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('../../database/encryption/encryption-schema-registry');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
 const { strictIntId } = require('./report-id');
+const { validateMappingQuery } = require('./integration-mapping-query');
+
+const encryptedMappingFields = () =>
+    getFieldsToEncryptOnWrite('IntegrationMapping').filter(
+        (field) => field === 'mapping' || field.startsWith('mapping.')
+    );
 
 /**
  * PostgreSQL Integration Mapping Repository Adapter
@@ -216,6 +226,155 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
         return counts;
     }
 
+    /**
+     * Query one page of an integration's mappings, filtering and ordering
+     * inside Postgres instead of loading every row. The total rides on the
+     * page as a window count, so one statement reads the matching rows once;
+     * only an empty page after the first needs a second, count-only statement.
+     *
+     * The SQL text is fixed: every caller value, JSON paths included (as
+     * text[]), is a positional parameter, and the sort direction comes from
+     * the ASC/DESC whitelist in integration-mapping-query.js.
+     *
+     * @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);
+        this._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 whereParams = [...params];
+
+        const mappingSql =
+            omit.length > 0
+                ? `"mapping" - ${bind(omit)}::text[] AS "mapping"`
+                : `"mapping"`;
+        const orderSql = orderBy ? this._orderSql(orderBy, bind) : `"id" ASC`;
+
+        const pageSql = `
+            SELECT "id", "integrationId", "sourceId", ${mappingSql}, "createdAt", "updatedAt",
+                (COUNT(*) OVER ())::int AS "__total"
+            FROM "IntegrationMapping"
+            WHERE ${whereSql}
+            ORDER BY ${orderSql}
+            OFFSET ${bind(skip)}::bigint
+            LIMIT ${bind(take)}::int
+        `;
+        const rows = await this.prisma.$queryRawUnsafe(pageSql, ...params);
+
+        return {
+            mappings: rows.map((row) => {
+                const mapping = this._convertMappingIds(row);
+                delete mapping.__total;
+                return mapping;
+            }),
+            total: await this._totalMatches(rows, skip, whereSql, whereParams),
+        };
+    }
+
+    /**
+     * An empty page is either past the end (count again) or, at skip 0,
+     * proof that nothing matches.
+     * @private
+     */
+    async _totalMatches(pageRows, skip, whereSql, whereParams) {
+        if (pageRows.length > 0) return pageRows[0].__total;
+        if (skip === 0) return 0;
+
+        const [{ total }] = await this.prisma.$queryRawUnsafe(
+            `SELECT COUNT(*)::int AS "total" FROM "IntegrationMapping" WHERE ${whereSql}`,
+            ...whereParams
+        );
+        return total;
+    }
+
+    /**
+     * queryMappings reads the stored JSON, so it needs `mapping`, and every
+     * path inside it, written as plain JSON. The app's opt-out
+     * (`encryption.disable`) is registered lazily, when the Prisma client is
+     * created, so load it before deciding. The stage, the keys and the app
+     * definition do not change at runtime, so a passed check is kept.
+     * @private
+     */
+    _assertMappingWrittenUnencrypted() {
+        if (this._mappingWrittenUnencrypted) return;
+
+        if (getEncryptionConfig().enabled) {
+            if (encryptedMappingFields().length > 0) {
+                loadCustomEncryptionSchema();
+            }
+            const fields = encryptedMappingFields();
+            if (fields.length > 0) {
+                const encrypted = fields
+                    .map((field) => `IntegrationMapping.${field}`)
+                    .join(', ');
+                const optOut = fields.map((field) => `'${field}'`).join(', ');
+                throw new Error(
+                    `queryMappings: field-level encryption still encrypts ${encrypted} on write, so it cannot be queried. Opt out by adding ${optOut} to appDefinition.encryption.disable.IntegrationMapping.`
+                );
+            }
+        }
+
+        this._mappingWrittenUnencrypted = true;
+    }
+
+    /**
+     * 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({ segments, op, value }, bind) {
+        if (op === 'notStartsWith') {
+            const prefix = bind(value);
+            return `("sourceId" IS NULL OR NOT starts_with("sourceId", ${prefix}::text))`;
+        }
+
+        const path = `${bind(segments)}::text[]`;
+        if (op === 'in') {
+            const values = bind(value);
+            return `(jsonb_typeof("mapping" #> ${path}) = 'string' AND "mapping" #>> ${path} = ANY(${values}::text[]))`;
+        }
+
+        const type = `COALESCE(jsonb_typeof("mapping" #> ${path}), 'null')`;
+        return op === 'exists' ? `${type} <> 'null'` : `${type} = 'null'`;
+    }
+
+    /**
+     * NULLIF folds JSON null into SQL NULL, so both sort after every value.
+     * @private
+     */
+    _orderSql({ segments, direction }, bind) {
+        const path = bind(segments);
+        const value = `NULLIF("mapping" #> ${path}::text[], 'null'::jsonb)`;
+        return `${value} ${direction} NULLS LAST, "id" ${direction}`;
+    }
+
     /**
      * Find mapping by ID
      * @param {string} id - Mapping ID (string from application layer)

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

@@ -82,6 +82,17 @@ class IntegrationMappingRepository extends IntegrationMappingRepositoryInterface
         });
     }
 
+    /**
+     * Not implemented on this legacy repository; the adapters from
+     * createIntegrationMappingRepository() support it.
+     * @throws {Error} Always
+     */
+    async queryMappings() {
+        throw new Error(
+            'queryMappings is not supported on the legacy IntegrationMappingRepository; use createIntegrationMappingRepository()'
+        );
+    }
+
     /**
      * Delete a mapping by integration and source ID
      * Replaces: IntegrationMapping.deleteOne({ integration, sourceId })

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.636.7dc8dca.0",
+    "version": "2.0.0--canary.651.87132bf.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.636.7dc8dca.0",
-        "@friggframework/prettier-config": "2.0.0--canary.636.7dc8dca.0",
-        "@friggframework/test": "2.0.0--canary.636.7dc8dca.0",
+        "@friggframework/eslint-config": "2.0.0--canary.651.87132bf.0",
+        "@friggframework/prettier-config": "2.0.0--canary.651.87132bf.0",
+        "@friggframework/test": "2.0.0--canary.651.87132bf.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "7dc8dca491feccbc4bc9933b971ac8044155efb3"
+    "gitHead": "87132bf8f734ff6733c582630a606170e86a5dc2"
 }