@cobre-npm/library-portal-core 0.53.0 → 0.54.0

package/README.md

@@ -485,8 +485,9 @@ import type {
 
 ### `exports`
 
-Interfaces only (pure types) — the export engine's (`util-platform-exports`) request/response contract,
-verified against its real DTO and entity, not against what any consumer had guessed:
+The export engine's (`util-platform-exports`) request/response contract, verified against its real DTO and
+entity, not against what any consumer had guessed, plus its operator constants and a pure search → export filter
+translator:
 
 ```ts
 import {
@@ -494,6 +495,7 @@ import {
   type ExportResponse, type ExportStatus, type ExportCreator, type ExportStatusState,
   EXPORT_FORMATS, type ExportFormat,
   EXPORT_QUERY_OPERATORS, type ExportQueryOperator,
+  toExportFilterConditions, type ExportFilterTranslation, type ExportFilterTranslationOptions,
 } from "@cobre-npm/library-portal-core/exports"
 ```
 
@@ -502,10 +504,26 @@ import {
   `status`/`updated_at`/`export_path` in place as it processes. Both the exports list/status view in
   `portal` and any widget that creates exports read/write this one shape; keeping two hand-typed copies
   is what let each one drift from the real contract in its own way (see the two fixes below).
-- `EXPORT_QUERY_OPERATORS` is the engine's **real** allow-list (`eq`, `neq`, `gt`, `lt`, `lte`, `gte`) — narrower
-  than what a layout's catalog is allowed to declare (`between`, `in`, `like` are valid catalog
-  entries the engine still rejects at request time). A consumer validating a filter before sending it
-  needs the intersection of both, not just the catalog's.
+- `EXPORT_QUERY_OPERATORS` is the engine's **real** allow-list (`eq`, `neq`, `gt`, `lt`, `lte`, `gte`, `in`, `like`,
+  `between`); `in` and `between` take comma-separated values. A layout's catalog declares which ones each column
+  accepts, so a consumer validating a filter before sending it needs the intersection of both.
+- `toExportFilterConditions(filter, { fieldMap })` translates the `SearchFilter` a table sends to the search API into
+  `ExportFilterCondition[]`, so the file holds exactly the rows the table shows. `eq` stays, `not_eq` → `neq`,
+  `contains` → `like` (both case-insensitive substring matches), `gte`/`lte` stay, and an OR of `eq` on one field (a
+  multi-select filter) → `in`. Date conditions are translated like any other; checking them against the export's
+  31-day limit is the caller's job. What has no export equivalent — `exists`, a blank `contains`, an OR across
+  fields or operators (a table's text search), an `in` value holding a comma, an empty OR (which matches nothing in
+  the search) — comes back in `untranslatable` instead of being dropped, so the caller can block the export rather
+  than ship a wider file. `fieldMap` renames only the fields whose layout column differs:
+
+  ```ts
+  // filter: the same SearchFilter the view sends to the search API
+  toExportFilterConditions(filter, { fieldMap: { currency: "currency_pair" } })
+  // { conditions: [
+  //   { column: "currency_pair", operator: "in", value: "usd/cop,usd/mxn" },
+  //   { column: "created_at", operator: "gte", value: "2026-10-01T00:00:00" }
+  // ], untranslatable: [] }
+  ```
 - `ExportFilterCondition` is an `ExportQueryFilter` before its `type` is resolved
   (`{ column: "state", operator: "neq", value: "pending_funds" }`). The type belongs to the layout's catalog,
   so whoever reads the catalog fills it in and the column's type keeps one source of truth.

package/dist/cjs/exports/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./interfaces/common.interface";
+export * from "./interfaces/translation.interface";
 export * from "./interfaces/request.interface";
 export * from "./interfaces/response.interface";
+export * from "./utils/search-filter.utils";
 export declare const EXPORT_FORMATS: {
     readonly CSV: "csv";
     readonly JSON: "json";
@@ -8,8 +10,8 @@ export declare const EXPORT_FORMATS: {
 export type ExportFormat = typeof EXPORT_FORMATS[keyof typeof EXPORT_FORMATS];
 /**
  * The export engine's real allow-list (verified against util-platform-exports'
- * QueryOperator enum). A layout's catalog can declare more operators than this
- * ("between", "in", "like") — those are rejected by the engine at request time.
+ * QueryOperator enum). `in` and `between` take comma-separated values. A layout's catalog declares which of
+ * them each column accepts, so a consumer validating a filter needs both lists.
  */
 export declare const EXPORT_QUERY_OPERATORS: {
     readonly EQ: "eq";
@@ -18,5 +20,8 @@ export declare const EXPORT_QUERY_OPERATORS: {
     readonly LT: "lt";
     readonly LTE: "lte";
     readonly GTE: "gte";
+    readonly IN: "in";
+    readonly LIKE: "like";
+    readonly BETWEEN: "between";
 };
 export type ExportQueryOperator = typeof EXPORT_QUERY_OPERATORS[keyof typeof EXPORT_QUERY_OPERATORS];

package/dist/cjs/exports/index.js

@@ -16,16 +16,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXPORT_QUERY_OPERATORS = exports.EXPORT_FORMATS = void 0;
 __exportStar(require("./interfaces/common.interface"), exports);
+__exportStar(require("./interfaces/translation.interface"), exports);
 __exportStar(require("./interfaces/request.interface"), exports);
 __exportStar(require("./interfaces/response.interface"), exports);
+__exportStar(require("./utils/search-filter.utils"), exports);
 exports.EXPORT_FORMATS = {
     CSV: "csv",
     JSON: "json"
 };
 /**
  * The export engine's real allow-list (verified against util-platform-exports'
- * QueryOperator enum). A layout's catalog can declare more operators than this
- * ("between", "in", "like") — those are rejected by the engine at request time.
+ * QueryOperator enum). `in` and `between` take comma-separated values. A layout's catalog declares which of
+ * them each column accepts, so a consumer validating a filter needs both lists.
  */
 exports.EXPORT_QUERY_OPERATORS = {
     EQ: "eq",
@@ -33,5 +35,8 @@ exports.EXPORT_QUERY_OPERATORS = {
     GT: "gt",
     LT: "lt",
     LTE: "lte",
-    GTE: "gte"
+    GTE: "gte",
+    IN: "in",
+    LIKE: "like",
+    BETWEEN: "between"
 };

package/dist/cjs/exports/interfaces/translation.interface.d.ts

@@ -0,0 +1,11 @@
+import type { SearchCondition, SearchOrFilter } from "../../search/interfaces/filters.interface";
+import type { ExportFilterCondition } from "./common.interface";
+export interface ExportFilterTranslationOptions {
+    /** Search field → layout column, only where the two names differ (e.g. `{ currency: "currency_pair" }`). */
+    fieldMap?: Readonly<Record<string, string>>;
+}
+export interface ExportFilterTranslation {
+    conditions: ExportFilterCondition[];
+    /** Parts of the search filter with no export equivalent, so the caller can block or warn instead of dropping them. */
+    untranslatable: Array<SearchCondition | SearchOrFilter>;
+}

package/dist/cjs/exports/interfaces/translation.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/exports/utils/search-filter.utils.d.ts

@@ -0,0 +1,19 @@
+import type { SearchFilter } from "../../search/interfaces/filters.interface";
+import type { ExportFilterTranslationOptions, ExportFilterTranslation } from "../interfaces/translation.interface";
+/**
+ * Translates the filter a table sends to the search API into the conditions the exports API takes, so an
+ * export can match what the table shows. What has no export equivalent comes back in `untranslatable`.
+ *
+ * @example
+ * toExportFilterConditions({
+ *   and: [
+ *     { or: [{ field: "state", operator: "eq", value: "completed" }, { field: "state", operator: "eq", value: "failed" }] },
+ *     { field: "created_at", operator: "gte", value: "2026-10-01T00:00:00" },
+ *   ],
+ * })
+ * // { conditions: [
+ * //   { column: "state", operator: "in", value: "completed,failed" },
+ * //   { column: "created_at", operator: "gte", value: "2026-10-01T00:00:00" }
+ * // ], untranslatable: [] }
+ */
+export declare const toExportFilterConditions: (filter: SearchFilter, options?: ExportFilterTranslationOptions) => ExportFilterTranslation;

package/dist/cjs/exports/utils/search-filter.utils.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toExportFilterConditions = void 0;
+/* Literals, not EXPORT_QUERY_OPERATORS: a value import from the barrel that re-exports this file is a runtime cycle. */
+const SEARCH_TO_EXPORT_OPERATORS = {
+    eq: "eq",
+    not_eq: "neq",
+    contains: "like",
+    gte: "gte",
+    lte: "lte",
+};
+/* The export splits an `in` value on commas, so a value that holds one can't travel in it. */
+const IN_SEPARATOR = ",";
+const isAndFilter = (filter) => "and" in filter;
+const isOrFilter = (part) => "or" in part;
+const toColumn = (field, { fieldMap = {} }) => fieldMap[field] ?? field;
+const toCondition = ({ field, operator, value }, options) => {
+    const exportOperator = SEARCH_TO_EXPORT_OPERATORS[operator];
+    const exportValue = String(value);
+    /* A blank contains matches every row with a value in the search; the export rejects a blank like and has no exists. */
+    if (!exportOperator || (exportOperator === "like" && exportValue.trim() === ""))
+        return null;
+    return { column: toColumn(field, options), operator: exportOperator, value: exportValue };
+};
+/* A multi-select filter reaches the search as an OR of eq on one field; the export reads it as in. */
+const toInCondition = ({ or }, options) => {
+    const field = or[0]?.field;
+    const values = or.map(({ value }) => String(value));
+    const isSingleFieldEq = field !== undefined && or.every(part => part.operator === "eq" && part.field === field);
+    if (!isSingleFieldEq || values.some(value => value.includes(IN_SEPARATOR)))
+        return null;
+    return { column: toColumn(field, options), operator: "in", value: values.join(IN_SEPARATOR) };
+};
+const toPartCondition = (part, options) => {
+    if (!isOrFilter(part))
+        return toCondition(part, options);
+    const [singleCondition] = part.or;
+    return part.or.length === 1 && singleCondition ? toCondition(singleCondition, options) : toInCondition(part, options);
+};
+/**
+ * Translates the filter a table sends to the search API into the conditions the exports API takes, so an
+ * export can match what the table shows. What has no export equivalent comes back in `untranslatable`.
+ *
+ * @example
+ * toExportFilterConditions({
+ *   and: [
+ *     { or: [{ field: "state", operator: "eq", value: "completed" }, { field: "state", operator: "eq", value: "failed" }] },
+ *     { field: "created_at", operator: "gte", value: "2026-10-01T00:00:00" },
+ *   ],
+ * })
+ * // { conditions: [
+ * //   { column: "state", operator: "in", value: "completed,failed" },
+ * //   { column: "created_at", operator: "gte", value: "2026-10-01T00:00:00" }
+ * // ], untranslatable: [] }
+ */
+const toExportFilterConditions = (filter, options = {}) => {
+    const parts = isAndFilter(filter) ? filter.and : [filter];
+    const translation = { conditions: [], untranslatable: [] };
+    parts.forEach(part => {
+        const condition = toPartCondition(part, options);
+        if (condition)
+            translation.conditions.push(condition);
+        else
+            translation.untranslatable.push(part);
+    });
+    return translation;
+};
+exports.toExportFilterConditions = toExportFilterConditions;

package/dist/esm/exports/index.js

@@ -1,14 +1,16 @@
 export * from "./interfaces/common.interface";
+export * from "./interfaces/translation.interface";
 export * from "./interfaces/request.interface";
 export * from "./interfaces/response.interface";
+export * from "./utils/search-filter.utils";
 export const EXPORT_FORMATS = {
     CSV: "csv",
     JSON: "json"
 };
 /**
  * The export engine's real allow-list (verified against util-platform-exports'
- * QueryOperator enum). A layout's catalog can declare more operators than this
- * ("between", "in", "like") — those are rejected by the engine at request time.
+ * QueryOperator enum). `in` and `between` take comma-separated values. A layout's catalog declares which of
+ * them each column accepts, so a consumer validating a filter needs both lists.
  */
 export const EXPORT_QUERY_OPERATORS = {
     EQ: "eq",
@@ -16,5 +18,8 @@ export const EXPORT_QUERY_OPERATORS = {
     GT: "gt",
     LT: "lt",
     LTE: "lte",
-    GTE: "gte"
+    GTE: "gte",
+    IN: "in",
+    LIKE: "like",
+    BETWEEN: "between"
 };

package/dist/esm/exports/interfaces/translation.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/exports/utils/search-filter.utils.js

@@ -0,0 +1,64 @@
+/* Literals, not EXPORT_QUERY_OPERATORS: a value import from the barrel that re-exports this file is a runtime cycle. */
+const SEARCH_TO_EXPORT_OPERATORS = {
+    eq: "eq",
+    not_eq: "neq",
+    contains: "like",
+    gte: "gte",
+    lte: "lte",
+};
+/* The export splits an `in` value on commas, so a value that holds one can't travel in it. */
+const IN_SEPARATOR = ",";
+const isAndFilter = (filter) => "and" in filter;
+const isOrFilter = (part) => "or" in part;
+const toColumn = (field, { fieldMap = {} }) => fieldMap[field] ?? field;
+const toCondition = ({ field, operator, value }, options) => {
+    const exportOperator = SEARCH_TO_EXPORT_OPERATORS[operator];
+    const exportValue = String(value);
+    /* A blank contains matches every row with a value in the search; the export rejects a blank like and has no exists. */
+    if (!exportOperator || (exportOperator === "like" && exportValue.trim() === ""))
+        return null;
+    return { column: toColumn(field, options), operator: exportOperator, value: exportValue };
+};
+/* A multi-select filter reaches the search as an OR of eq on one field; the export reads it as in. */
+const toInCondition = ({ or }, options) => {
+    const field = or[0]?.field;
+    const values = or.map(({ value }) => String(value));
+    const isSingleFieldEq = field !== undefined && or.every(part => part.operator === "eq" && part.field === field);
+    if (!isSingleFieldEq || values.some(value => value.includes(IN_SEPARATOR)))
+        return null;
+    return { column: toColumn(field, options), operator: "in", value: values.join(IN_SEPARATOR) };
+};
+const toPartCondition = (part, options) => {
+    if (!isOrFilter(part))
+        return toCondition(part, options);
+    const [singleCondition] = part.or;
+    return part.or.length === 1 && singleCondition ? toCondition(singleCondition, options) : toInCondition(part, options);
+};
+/**
+ * Translates the filter a table sends to the search API into the conditions the exports API takes, so an
+ * export can match what the table shows. What has no export equivalent comes back in `untranslatable`.
+ *
+ * @example
+ * toExportFilterConditions({
+ *   and: [
+ *     { or: [{ field: "state", operator: "eq", value: "completed" }, { field: "state", operator: "eq", value: "failed" }] },
+ *     { field: "created_at", operator: "gte", value: "2026-10-01T00:00:00" },
+ *   ],
+ * })
+ * // { conditions: [
+ * //   { column: "state", operator: "in", value: "completed,failed" },
+ * //   { column: "created_at", operator: "gte", value: "2026-10-01T00:00:00" }
+ * // ], untranslatable: [] }
+ */
+export const toExportFilterConditions = (filter, options = {}) => {
+    const parts = isAndFilter(filter) ? filter.and : [filter];
+    const translation = { conditions: [], untranslatable: [] };
+    parts.forEach(part => {
+        const condition = toPartCondition(part, options);
+        if (condition)
+            translation.conditions.push(condition);
+        else
+            translation.untranslatable.push(part);
+    });
+    return translation;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cobre-npm/library-portal-core",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Shared configurations and resources for Portal MFEs",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",