@cobre-npm/library-portal-core 0.42.0 → 0.43.0

package/README.md

@@ -46,6 +46,7 @@ import { getCountries }    from "@cobre-npm/library-portal-core/countries"
 | `@cobre-npm/library-portal-core/canonicalTransactions` | Canonical transaction/money-movement detail interfaces |
 | `@cobre-npm/library-portal-core/search` | Search / aggregation interfaces |
 | `@cobre-npm/library-portal-core/trustedSessions` | Trusted session (OTP elevation window) interfaces + constants |
+| `@cobre-npm/library-portal-core/exports` | Export request/response entity + the engine's format/operator allow-lists |
 | `@cobre-npm/library-portal-core/lang` | Supported locales (`Locale`, defaults) |
 | `@cobre-npm/library-portal-core` (root) | ⚠️ **Legacy / deprecated** — see [below](#legacy-code--and-its-deprecation) |
 
@@ -448,6 +449,41 @@ import type {
   doc comment for one case that's a superset of two non-overlapping shapes rather than a clean merge,
   and revisit it once the real payload is confirmed.
 
+### `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:
+
+```ts
+import {
+  type ExportRequest, type ExportQueryConfig, type ExportQueryFilter, type ExportQuerySort,
+  type ExportResponse, type ExportStatus, type ExportCreator, type ExportStatusState,
+  EXPORT_FORMATS, type ExportFormat,
+  EXPORT_QUERY_OPERATORS, type ExportQueryOperator,
+} from "@cobre-npm/library-portal-core/exports"
+```
+
+- `ExportResponse` is the **same entity** whether it just came back from `POST /v1/exports` (creating it)
+  or from a later `GET` (reading it) — the engine stores one record per export and updates
+  `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`, `gt`, `lt`, `lte`, `gte`) — narrower
+  than what a layout's catalog is allowed to declare (`between`, `in`, `like`, `neq` 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.
+- `ExportQuerySort` uses `field`; `ExportQueryFilter` uses `column` — not a typo, the engine's own DTOs
+  name the two differently.
+- `column_aggregations` is a required `boolean` (apply aggregations or don't), not a per-column map — the
+  catalog's `aggregation: "sum"` markers describe what *can* be aggregated, not the request shape.
+- `language` is deliberately typed `string`, not `Locale`: the engine validates it against
+  `/^[a-z]{2}(-[A-Z]{2})?$/` (a BCP-47-shaped language tag), and `Locale`'s `"es-mex"` value doesn't match
+  that pattern — the two look interchangeable because they happen to cover the same two languages today,
+  but `Locale` names a translation-file convention (`locales/es-mex.json`), not this engine's contract.
+- **Deliberately excludes the export catalog** (`GET .../catalog/{layout}`, i.e. which columns/operators a
+  given layout allows) — that stays with whichever widget owns fetching it, not here; it isn't a shape
+  two independent consumers need to agree on today.
+
 ---
 
 ## i18n / languages

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

@@ -0,0 +1,21 @@
+export * from "./interfaces/common.interface";
+export * from "./interfaces/request.interface";
+export * from "./interfaces/response.interface";
+export declare const EXPORT_FORMATS: {
+    readonly CSV: "csv";
+    readonly JSON: "json";
+};
+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", "neq") — those are rejected by the engine at request time.
+ */
+export declare const EXPORT_QUERY_OPERATORS: {
+    readonly EQ: "eq";
+    readonly GT: "gt";
+    readonly LT: "lt";
+    readonly LTE: "lte";
+    readonly GTE: "gte";
+};
+export type ExportQueryOperator = typeof EXPORT_QUERY_OPERATORS[keyof typeof EXPORT_QUERY_OPERATORS];

package/dist/cjs/exports/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_QUERY_OPERATORS = exports.EXPORT_FORMATS = void 0;
+__exportStar(require("./interfaces/common.interface"), exports);
+__exportStar(require("./interfaces/request.interface"), exports);
+__exportStar(require("./interfaces/response.interface"), 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", "neq") — those are rejected by the engine at request time.
+ */
+exports.EXPORT_QUERY_OPERATORS = {
+    EQ: "eq",
+    GT: "gt",
+    LT: "lt",
+    LTE: "lte",
+    GTE: "gte"
+};

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

@@ -0,0 +1,11 @@
+import type { ExportQueryOperator } from "../index";
+export interface ExportQueryFilter {
+    column: string;
+    type: string;
+    operator: ExportQueryOperator;
+    value: string;
+}
+export interface ExportQuerySort {
+    field: string;
+    order: "asc" | "desc";
+}

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

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

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

@@ -0,0 +1,17 @@
+import type { ExportFormat } from "../index";
+import type { ExportQueryFilter, ExportQuerySort } from "./common.interface";
+export interface ExportQueryConfig {
+    format: ExportFormat;
+    language: string;
+    timezone: string;
+    start_date: string;
+    end_date: string;
+    columns: string[];
+    column_aggregations: boolean;
+    query_filters?: ExportQueryFilter[];
+    query_sorting?: ExportQuerySort[];
+}
+export interface ExportRequest {
+    layout: string;
+    query_config: ExportQueryConfig;
+}

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

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

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

@@ -0,0 +1,32 @@
+import type { ExportQueryConfig } from "./request.interface";
+/** Verified against util-platform-exports' ExportStatusState enum. */
+export type ExportStatusState = "initiated" | "processing" | "created" | "failed";
+export interface ExportCreator {
+    user_id: string;
+    email: string;
+    role_id: string;
+    sensitive_data: boolean;
+}
+export interface ExportStatus {
+    state: ExportStatusState;
+    code: string;
+    description: string;
+}
+/**
+ * The export entity — same shape whether it just came back from POST /v1/exports
+ * (creating it) or from a later GET (reading it): the engine stores one record per
+ * export and updates status/updated_at/export_path in place as it processes.
+ * Verified against util-platform-exports' ExportData entity.
+ */
+export interface ExportResponse {
+    id: string;
+    client_id: string;
+    creator: ExportCreator;
+    status: ExportStatus;
+    layout: string;
+    query_config: ExportQueryConfig;
+    created_at: string;
+    updated_at: string;
+    ttl?: number;
+    export_path?: string;
+}

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

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

package/dist/esm/exports/index.js

@@ -0,0 +1,19 @@
+export * from "./interfaces/common.interface";
+export * from "./interfaces/request.interface";
+export * from "./interfaces/response.interface";
+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", "neq") — those are rejected by the engine at request time.
+ */
+export const EXPORT_QUERY_OPERATORS = {
+    EQ: "eq",
+    GT: "gt",
+    LT: "lt",
+    LTE: "lte",
+    GTE: "gte"
+};

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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cobre-npm/library-portal-core",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Shared configurations and resources for Portal MFEs",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -70,6 +70,11 @@
       "types": "./dist/cjs/lang/index.d.ts",
       "import": "./dist/esm/lang/index.js",
       "require": "./dist/cjs/lang/index.js"
+    },
+    "./exports": {
+      "types": "./dist/cjs/exports/index.d.ts",
+      "import": "./dist/esm/exports/index.js",
+      "require": "./dist/cjs/exports/index.js"
     }
   },
   "files": [