@friggframework/core 2.0.0--canary.651.87132bf.0 → 2.0.0--canary.651.bc0e60a.0

package/CLAUDE.md

@@ -211,7 +211,31 @@ packages/core/
 - `integration-repository-factory.js` - Creates database-specific repositories
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
-- `integration-mapping-repository-*.js` - Mapping data persistence
+- `integration-mapping-repository-*.js` - Mapping data persistence.
+  `queryMappings(integrationId, { where, orderBy, skip, take, omit })`
+  returns `{ mappings, total }`: one filtered, ordered page of an
+  integration's mappings, for callers that cannot load every row through
+  `findMappingsByIntegration`. `where` is an array of ANDed conditions
+  (at most 20); an entry may be `{ anyOf: [...] }`, ORed, one level deep.
+  Conditions are `{ path: 'mapping.<segment>...', op: 'exists' | 'notExists' }`
+  (JSON null counts as absent), `{ path: 'mapping.…', op: 'in', value: string[] }`
+  (1–500 strings) and `{ path: 'sourceId', op: 'notStartsWith', value }`
+  (a NULL sourceId matches). `orderBy` is `{ path: 'mapping.…', direction:
+  'asc' | 'desc' }`, nulls last, ties broken by id in the same direction;
+  without it rows come in id order. `take` is 1–500. `omit` lists top-level
+  mapping keys to leave out of the rows; never write such rows back. Path
+  segments must match `^[A-Za-z_][A-Za-z0-9_]*$`. **PostgreSQL only**: the
+  MongoDB, DocumentDB and legacy repositories inherit the port's
+  "not supported by this database adapter yet" error. It also refuses to run
+  while field-level encryption still encrypts `IntegrationMapping.mapping` on
+  write (see `database/encryption/README.md`). Validation lives in
+  `integration-mapping-query.js`; a new operator is one entry in its
+  `OPERATORS` table and one in the Postgres adapter's `CONDITION_SQL`.
+  **Cost**: one SQL statement per call, which reads every row of the
+  integration and evaluates the JSON paths per row, because no JSON index
+  exists. With ~4 KB mappings on PostgreSQL 16 that is about 0.3 s per call
+  at 10⁴ rows per integration and 2.5–3 s at 10⁵; a deep offset or an empty
+  page past the end costs about the same as the first page.
 - `process-repository-*.js` - Process (long-running job) persistence.
   Implements `applyProcessUpdate(processId, ops)` — a race-safe alternative
   to `update(id, patch)` that routes increments, sets, and bounded-array

package/database/encryption/README.md

@@ -814,6 +814,22 @@ export AES_KEY=$(openssl rand -hex 16)  # Generate 32-char key
 ❌ Query on encrypted fields (not supported)
 ❌ Manually decrypt data (use extension)
 
+`IntegrationMappingRepository.queryMappings()` (PostgreSQL) filters and sorts
+inside the `mapping` JSON, so it refuses to run while field-level encryption
+still encrypts `IntegrationMapping.mapping` on write. Opt the field out in the
+app definition, together with any nested `mapping.*` path that
+`encryption.schema` encrypts:
+
+```javascript
+encryption: {
+    disable: { IntegrationMapping: ['mapping'] },
+}
+```
+
+The opt-out applies to writes only. Rows written encrypted before it stay
+readable, but `queryMappings()` does not match them until they are written
+again.
+
 ## Future Enhancements
 
 ### Planned

package/database/encryption/integration-mapping-encryption.js

@@ -0,0 +1,41 @@
+const { getEncryptionConfig } = require('../prisma');
+const {
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('./encryption-schema-registry');
+
+let mappingWrittenPlain = false;
+
+/**
+ * The `IntegrationMapping` fields, `mapping` itself or a nested `mapping.*`
+ * path, that field-level encryption encrypts on write. An empty result is
+ * kept for the life of the process.
+ *
+ * @returns {string[]} Empty when every mapping path is written as plain JSON
+ */
+function getMappingFieldsEncryptedOnWrite() {
+    if (mappingWrittenPlain) return [];
+
+    const fields = encryptedMappingFields();
+    mappingWrittenPlain = fields.length === 0;
+    return fields;
+}
+
+function encryptedMappingFields() {
+    if (!getEncryptionConfig().enabled) return [];
+
+    loadCustomEncryptionSchema();
+    return getFieldsToEncryptOnWrite('IntegrationMapping').filter(
+        (field) => field === 'mapping' || field.startsWith('mapping.')
+    );
+}
+
+/** Test helper: forget a kept result. */
+function resetMappingEncryptionCheck() {
+    mappingWrittenPlain = false;
+}
+
+module.exports = {
+    getMappingFieldsEncryptedOnWrite,
+    resetMappingEncryptionCheck,
+};

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

@@ -1,23 +1,23 @@
-/**
- * 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 DIRECTIONS = ['asc', 'desc'];
 
-const OPS_BY_FIELD = {
-    mapping: ['exists', 'notExists', 'in'],
-    sourceId: ['notStartsWith'],
+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');
@@ -73,12 +73,12 @@ function toOrderBy(orderBy) {
             "queryMappings: orderBy.path must be a mapping path ('mapping.<segment>...')"
         );
     }
-    if (!Object.hasOwn(SQL_DIRECTIONS, orderBy.direction)) {
+    if (!DIRECTIONS.includes(orderBy.direction)) {
         throw new Error(
             "queryMappings: orderBy.direction must be 'asc' or 'desc'"
         );
     }
-    return { segments, direction: SQL_DIRECTIONS[orderBy.direction] };
+    return { path: segments, direction: orderBy.direction };
 }
 
 function toWhereEntry(entry) {
@@ -110,45 +110,62 @@ function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+/**
+ * `{ path: 'mapping.c2h.lastStatus', op: 'in', value: ['failed'] }` →
+ * `{ field: 'mapping', path: ['c2h', 'lastStatus'], 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 allowed = OPS_BY_FIELD[field];
-    if (!allowed.includes(op)) {
+    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: ${allowed.join(', ')})`
+            )} is not allowed on '${path}' (allowed: ${operatorsOn(field).join(
+                ', '
+            )})`
         );
     }
+    return {
+        field,
+        ...(segments.length > 0 && { path: segments }),
+        op,
+        ...(operator.value && { value: operator.value(value, path) }),
+    };
+}
 
-    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 };
-    }
+function operatorsOn(field) {
+    return Object.keys(OPERATORS).filter((op) =>
+        OPERATORS[op].fields.includes(field)
+    );
+}
 
-    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 };
+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;
+}
 
-    return { field, segments, op };
+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;
 }
 
 /**
@@ -173,4 +190,4 @@ function parsePath(path) {
     return { field, segments };
 }
 
-module.exports = { SEGMENT_REGEX, validateMappingQuery };
+module.exports = { validateMappingQuery };

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

@@ -179,14 +179,6 @@ 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

@@ -56,11 +56,6 @@ 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
@@ -91,10 +86,11 @@ class IntegrationMappingRepositoryInterface {
      *   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');
+        throw new Error(
+            'queryMappings is not supported by this database adapter yet'
+        );
     }
 
     /**

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

@@ -87,14 +87,6 @@ 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,18 +1,30 @@
-const { prisma, getEncryptionConfig } = require('../../database/prisma');
+const { prisma } = require('../../database/prisma');
 const {
-    getFieldsToEncryptOnWrite,
-    loadCustomEncryptionSchema,
-} = require('../../database/encryption/encryption-schema-registry');
+    getMappingFieldsEncryptedOnWrite,
+} = 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 encryptedMappingFields = () =>
-    getFieldsToEncryptOnWrite('IntegrationMapping').filter(
-        (field) => field === 'mapping' || field.startsWith('mapping.')
-    );
+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
@@ -227,15 +239,6 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
     }
 
     /**
-     * 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}>}
@@ -257,79 +260,52 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
             `jsonb_typeof("mapping") = 'object'`,
             ...where.map((entry) => this._whereEntrySql(entry, bind)),
         ].join(' AND ');
-        const whereParams = [...params];
-
+        const orderSql = orderBy ? this._orderSql(orderBy, bind) : `"id" ASC`;
         const mappingSql =
             omit.length > 0
                 ? `"mapping" - ${bind(omit)}::text[] AS "mapping"`
                 : `"mapping"`;
-        const orderSql = orderBy ? this._orderSql(orderBy, bind) : `"id" ASC`;
 
-        const pageSql = `
+        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",
-                (COUNT(*) OVER ())::int AS "__total"
-            FROM "IntegrationMapping"
-            WHERE ${whereSql}
+                (SELECT COUNT(*)::int FROM "matched") AS "__total"
+            FROM (VALUES (1)) AS "one"
+            LEFT JOIN "page" ON true
             ORDER BY ${orderSql}
-            OFFSET ${bind(skip)}::bigint
-            LIMIT ${bind(take)}::int
         `;
-        const rows = await this.prisma.$queryRawUnsafe(pageSql, ...params);
+        const rows = await this.prisma.$queryRawUnsafe(sql, ...params);
 
         return {
-            mappings: rows.map((row) => {
-                const mapping = this._convertMappingIds(row);
-                delete mapping.__total;
-                return mapping;
-            }),
-            total: await this._totalMatches(rows, skip, whereSql, whereParams),
+            mappings: rows
+                .filter((row) => row.id !== null)
+                .map(({ __total, ...row }) => this._convertMappingIds(row)),
+            total: rows[0].__total,
         };
     }
 
-    /**
-     * 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
-     */
+    /** @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;
+        const fields = getMappingFieldsEncryptedOnWrite();
+        if (fields.length === 0) return;
+
+        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.`
+        );
     }
 
     /**
@@ -349,30 +325,26 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
      * 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'`;
+    _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({ segments, direction }, bind) {
-        const path = bind(segments);
-        const value = `NULLIF("mapping" #> ${path}::text[], 'null'::jsonb)`;
-        return `${value} ${direction} NULLS LAST, "id" ${direction}`;
+    _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}`;
     }
 
     /**

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

@@ -82,17 +82,6 @@ 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.651.87132bf.0",
+    "version": "2.0.0--canary.651.bc0e60a.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.651.87132bf.0",
-        "@friggframework/prettier-config": "2.0.0--canary.651.87132bf.0",
-        "@friggframework/test": "2.0.0--canary.651.87132bf.0",
+        "@friggframework/eslint-config": "2.0.0--canary.651.bc0e60a.0",
+        "@friggframework/prettier-config": "2.0.0--canary.651.bc0e60a.0",
+        "@friggframework/test": "2.0.0--canary.651.bc0e60a.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": "87132bf8f734ff6733c582630a606170e86a5dc2"
+    "gitHead": "bc0e60a39a4ee32316d346a02ef8da77d4d41b1f"
 }