@cobre-npm/library-portal-core 0.56.0 → 0.57.0

package/README.md

@@ -440,8 +440,10 @@ And two on rule 1: `{ minAmount: 1 }` is equality, not `>=`, which is rarely wha
 ```ts
 import {
   getTransactionTypes, queryTransactionTypes, type TransactionType, type TransactionTypeQuery,
+  collapseTransactionTypes, type TransactionTypeGroup, type TransactionTypeGroupOption,
   type Transaction, type EnrichedTransaction, /* ...interfaces */
 } from "@cobre-npm/library-portal-core/transactions"
+import { isGroupOption, expandGroupSelection } from "@cobre-npm/library-portal-core/filterClassification"
 
 getTransactionTypes("en").spei_debit.label            // "Outgoing transfer · SPEI"
 getTransactionTypes("es-mex").spei_debit.label        // "Transferencia enviada · SPEI"
@@ -458,6 +460,33 @@ queryTransactionTypes({ lang: "en", category: "top_up" })  // col_top_up_credit
   "· débito" / "· crédito" (en "· debit" / "· credit") suffix, except `offramp_treasury_credit`, whose label has none; elsewhere the direction is in the verb
   ("Outgoing transfer", "Incoming transfer"). `col_cb_*` keeps "Cobre Balance" in its label. `misc_*`,
   `internal_*` and `adjustment_*` have `line: "unclassified"`, and `misc_*` also `category: "unclassified"`.
+  Each type also carries a required `section: FilterClassificationSection`, the heading it is listed under in the
+  grouped filter (group members take their group's section; `internal_spei_*`, `col_cb_debit` → `internal`,
+  `misc_*` → `connected_account`).
+- **conditional marker**: five rarely used types (`misc_debit`, `misc_credit`, `col_cb_debit`, `internal_spei_debit`,
+  `internal_spei_credit`) carry `filterDisplay: "when_present"`: the grouped filter should list them only when the
+  data has them. It is descriptive, not a visibility switch: there is no default, `queryTransactionTypes()` still
+  returns them and their labels are unchanged, so flat filters see no difference. The field is absent on every
+  other type, so read it with `"filterDisplay" in type`.
+- **group**: every type carries a required `group: TransactionTypeGroup | null`. The 14 debit/credit legs name
+  one of 7 UI-only groups (`cbmm`, `global_pay_to_usa`, `usa_pay_to_global`, `on_ramp`, `off_ramp`,
+  `stable_payout`, `internal`); every other type is `null`. A group code is **never** a transaction type and is
+  never sent to the API: selecting a group means selecting its member codes (`expandGroupSelection`). There is no
+  separate groups catalog; group labels come out of `collapseTransactionTypes`.
+- **collapse** (i18n): `collapseTransactionTypes({ lang, ...filters })` takes the same query as
+  `queryTransactionTypes`, filters first, then folds each group into one `TransactionTypeGroupOption`
+  `{ code, members, line, category, section, label }`, placed at its first member's position. A group collapses
+  only if **all** its legs survive the filter; otherwise the surviving legs come out as plain options. Tell the
+  two apart with `isGroupOption` (from [`filterClassification`](#filterclassification)), which also feeds
+  `expandGroupSelection` / `getGroupSelectionState`:
+
+  ```ts
+  collapseTransactionTypes({ lang: "en", category: "conversions" }).map(option => option.code)
+  // 7 conversion types → 4 options: ["on_ramp", "off_ramp", "stable_payout", "offramp_treasury_credit"]
+  collapseTransactionTypes({ lang: "en", creditDebitType: "debit" })  // no group survives: plain legs only
+  const groups = collapseTransactionTypes({ lang: "en" }).filter(isGroupOption)
+  expandGroupSelection(["cbmm", "spei_debit"], groups)  // ["cbmm_debit", "cbmm_credit", "spei_debit"]
+  ```
 - **types query** (i18n `queryX()`): `queryTransactionTypes({ lang, ...filters })` — `lang` is **required inside
   the query object**, not a separate argument, so the result is already localized. There is no default field
   (unlike `currencies`' `scope`): every transaction type comes back when only `lang` is given.
@@ -483,7 +512,7 @@ the headings inside a chip, and **types** (movement / transaction types) are the
 ```ts
 import {
   getFilterClassificationCategoryFamilies, getFilterClassificationSections, splitTypeLabel,
-  expandGroupSelection, getGroupSelectionState,
+  expandGroupSelection, getGroupSelectionState, isGroupOption,
   type FilterClassificationCategoryFamily, type FilterClassificationSection,
   type FilterClassificationCategory, type FilterClassificationRecord,
 } from "@cobre-npm/library-portal-core/filterClassification"
@@ -493,6 +522,7 @@ declare const record: { section: FilterClassificationSection }     // one of tho
 declare const groups: FilterClassificationRecord<string>[]         // the UI's group records
 declare const group: FilterClassificationRecord<string>            // one of them
 declare const selectedCodes: string[]                              // what the user has ticked
+declare const options: ({ code: string } | FilterClassificationRecord<string>)[]  // a mixed list: plain and group options
 
 const families = getFilterClassificationCategoryFamilies("en")
 families.between_accounts.label                            // "Between accounts"
@@ -503,6 +533,7 @@ splitTypeLabel("Transfer · ACH")                           // { title: "Transfe
 splitTypeLabel("International")                            // { title: "International" } — no empty rail
 expandGroupSelection(["stablecoin_group", "ach"], groups)  // member codes + "ach"; the group code is never returned
 getGroupSelectionState(group, selectedCodes)               // "checked" | "indeterminate" | "unchecked"
+options.filter(isGroupOption)                              // only the group options, typed as such
 ```
 
 - **Family** (`FilterClassificationCategoryFamily`): the chips of the grouped type filter, in chip order: `payments`, `collections`,
@@ -517,9 +548,9 @@ getGroupSelectionState(group, selectedCodes)               // "checked" | "indet
   never sent to an API. `getFilterClassificationSections(lang)`. `internal` and `connected_account` exist but no movement type uses
   them yet.
 - **`splitTypeLabel(label)`**: splits at the first `" · "` into `{ title, rail? }` for two-line options.
-- **group helpers**: `FilterClassificationRecord<Code>` (`code`, `members`, `line`, `category`, `section`). A group code is a UI
-  identifier: `expandGroupSelection` swaps it for its members before calling an API, and `getGroupSelectionState`
-  gives the checkbox state from the selected member codes.
+- **group helpers**: `FilterClassificationRecord<Code, Member = Code>` (`code`, `members`, `line`, `category`, `section`). A group code is a UI
+  identifier: `expandGroupSelection` swaps it for its members before calling an API, `getGroupSelectionState`
+  gives the checkbox state from the selected member codes, and `isGroupOption` tells group options from plain ones in a mixed list.
 
 ### `trustedSessions`
 

package/dist/cjs/filterClassification/interfaces/filter-classification.interface.d.ts

@@ -5,9 +5,9 @@ import type { FilterClassificationSection } from "../sections/catalog";
  * A selectable group of type codes (one checkbox that stands for several types). The group `code` is a UI
  * identifier: it is never sent to an API, only its `members` are — see `expandGroupSelection`.
  */
-export type FilterClassificationRecord<Code extends string> = {
+export type FilterClassificationRecord<Code extends string, Member extends string = Code> = {
     readonly code: Code;
-    readonly members: readonly Code[];
+    readonly members: readonly Member[];
     readonly line: BusinessLine;
     readonly category: FilterClassificationCategory;
     readonly section: FilterClassificationSection;

package/dist/cjs/filterClassification/utils/type-group.utils.d.ts

@@ -1,9 +1,13 @@
 import type { FilterClassificationRecord } from "../interfaces/filter-classification.interface";
 export type GroupSelectionState = "checked" | "indeterminate" | "unchecked";
+/** Tells a group option (it has `members`) from a plain option, narrowing a mixed list of both. */
+export declare const isGroupOption: <Option extends object>(option: Option) => option is Extract<Option, {
+    readonly members: readonly string[];
+}>;
 /**
  * The codes to send to an API: each selected group code is replaced by its members, anything else passes
  * through. The group code itself never appears in the output, and repeated codes are dropped.
  */
-export declare const expandGroupSelection: <Code extends string>(selected: readonly Code[], groups: readonly FilterClassificationRecord<Code>[]) => Code[];
+export declare const expandGroupSelection: <Code extends string, Member extends string = Code>(selected: readonly (Code | Member)[], groups: readonly FilterClassificationRecord<Code, Member>[]) => Member[];
 /** checked = every member selected, indeterminate = some, unchecked = none (or a group without members). */
-export declare const getGroupSelectionState: <Code extends string>(group: FilterClassificationRecord<Code>, selected: readonly Code[]) => GroupSelectionState;
+export declare const getGroupSelectionState: <Code extends string, Member extends string = Code>(group: FilterClassificationRecord<Code, Member>, selected: readonly Member[]) => GroupSelectionState;

package/dist/cjs/filterClassification/utils/type-group.utils.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getGroupSelectionState = exports.expandGroupSelection = void 0;
+exports.getGroupSelectionState = exports.expandGroupSelection = exports.isGroupOption = void 0;
+/** Tells a group option (it has `members`) from a plain option, narrowing a mixed list of both. */
+const isGroupOption = (option) => "members" in option;
+exports.isGroupOption = isGroupOption;
 /**
  * The codes to send to an API: each selected group code is replaced by its members, anything else passes
  * through. The group code itself never appears in the output, and repeated codes are dropped.

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

@@ -1,3 +1,3 @@
-export type { TransactionType } from "./types/catalog";
+export type { TransactionType, TransactionTypeGroup } from "./types/catalog";
 export * from "./types/utils/transaction-type.utils";
 export * from "./interfaces/response.interface";

package/dist/cjs/transactions/types/catalog.d.ts

@@ -4,289 +4,397 @@ export declare const TRANSACTION_TYPES: {
         readonly code: "spei_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "mxn";
+        readonly group: null;
     };
     readonly spei_credit: {
         readonly creditDebitType: "credit";
         readonly code: "spei_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "mxn";
+        readonly group: null;
     };
     readonly spei_return: {
         readonly creditDebitType: "credit";
         readonly code: "spei_return";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "mxn";
+        readonly group: null;
     };
     readonly spei_rejected: {
         readonly creditDebitType: "credit";
         readonly code: "spei_rejected";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "mxn";
+        readonly group: null;
     };
     readonly internal_spei_debit: {
         readonly creditDebitType: "debit";
         readonly code: "internal_spei_debit";
         readonly line: "unclassified";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: null;
+        readonly filterDisplay: "when_present";
     };
     readonly internal_spei_credit: {
         readonly creditDebitType: "credit";
         readonly code: "internal_spei_credit";
         readonly line: "unclassified";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: null;
+        readonly filterDisplay: "when_present";
     };
     readonly adjustment_credit: {
         readonly creditDebitType: "credit";
         readonly code: "adjustment_credit";
         readonly line: "unclassified";
         readonly category: "adjustment";
+        readonly section: "internal";
+        readonly group: null;
     };
     readonly adjustment_debit: {
         readonly creditDebitType: "debit";
         readonly code: "adjustment_debit";
         readonly line: "unclassified";
         readonly category: "adjustment";
+        readonly section: "internal";
+        readonly group: null;
     };
     readonly mex_debit: {
         readonly creditDebitType: "debit";
         readonly code: "mex_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "connected_account";
+        readonly group: null;
     };
     readonly mex_credit: {
         readonly creditDebitType: "credit";
         readonly code: "mex_credit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "connected_account";
+        readonly group: null;
     };
     readonly col_debit: {
         readonly creditDebitType: "debit";
         readonly code: "col_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "connected_account";
+        readonly group: null;
     };
     readonly col_credit: {
         readonly creditDebitType: "credit";
         readonly code: "col_credit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "connected_account";
+        readonly group: null;
     };
     readonly misc_debit: {
         readonly creditDebitType: "debit";
         readonly code: "misc_debit";
         readonly line: "unclassified";
         readonly category: "unclassified";
+        readonly section: "connected_account";
+        readonly group: null;
+        readonly filterDisplay: "when_present";
     };
     readonly misc_credit: {
         readonly creditDebitType: "credit";
         readonly code: "misc_credit";
         readonly line: "unclassified";
         readonly category: "unclassified";
+        readonly section: "connected_account";
+        readonly group: null;
+        readonly filterDisplay: "when_present";
     };
     readonly internal_credit: {
         readonly creditDebitType: "credit";
         readonly code: "internal_credit";
         readonly line: "unclassified";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: "internal";
     };
     readonly internal_debit: {
         readonly creditDebitType: "debit";
         readonly code: "internal_debit";
         readonly line: "unclassified";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: "internal";
     };
     readonly r2p_credit: {
         readonly creditDebitType: "credit";
         readonly code: "r2p_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly cbmm_debit: {
         readonly creditDebitType: "debit";
         readonly code: "cbmm_debit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "cbmm";
     };
     readonly cbmm_credit: {
         readonly creditDebitType: "credit";
         readonly code: "cbmm_credit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "cbmm";
     };
     readonly dd_credit: {
         readonly creditDebitType: "credit";
         readonly code: "dd_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly col_cb_credit: {
         readonly creditDebitType: "credit";
         readonly code: "col_cb_credit";
         readonly line: "payin";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: null;
     };
     readonly col_cb_debit: {
         readonly creditDebitType: "debit";
         readonly code: "col_cb_debit";
         readonly line: "payin";
         readonly category: "between_accounts";
+        readonly section: "internal";
+        readonly group: null;
+        readonly filterDisplay: "when_present";
     };
     readonly breb_credit: {
         readonly creditDebitType: "credit";
         readonly code: "breb_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly breb_debit: {
         readonly creditDebitType: "debit";
         readonly code: "breb_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly r2p_breb_credit: {
         readonly creditDebitType: "credit";
         readonly code: "r2p_breb_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly breb_rejected: {
         readonly creditDebitType: "credit";
         readonly code: "breb_rejected";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "cop";
+        readonly group: null;
     };
     readonly col_top_up_credit: {
         readonly creditDebitType: "credit";
         readonly code: "col_top_up_credit";
         readonly line: "payin";
         readonly category: "top_up";
+        readonly section: "internal";
+        readonly group: null;
     };
     readonly global_debit: {
         readonly creditDebitType: "debit";
         readonly code: "global_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly global_credit: {
         readonly creditDebitType: "credit";
         readonly code: "global_credit";
         readonly line: "cbmm";
         readonly category: "collections";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly r2p_spei_credit: {
         readonly creditDebitType: "credit";
         readonly code: "r2p_spei_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "mxn";
+        readonly group: null;
     };
     readonly transfer_credit: {
         readonly creditDebitType: "credit";
         readonly code: "transfer_credit";
         readonly line: "payin";
         readonly category: "collections";
+        readonly section: "connected_account";
+        readonly group: null;
     };
     readonly fedwire_debit: {
         readonly creditDebitType: "debit";
         readonly code: "fedwire_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly fedwire_credit: {
         readonly creditDebitType: "credit";
         readonly code: "fedwire_credit";
         readonly line: "cbmm";
         readonly category: "collections";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly reward_credit: {
         readonly creditDebitType: "credit";
         readonly code: "reward_credit";
         readonly line: "stable";
         readonly category: "reward";
+        readonly section: "internal";
+        readonly group: null;
     };
     readonly global_pay_to_usa_debit: {
         readonly creditDebitType: "debit";
         readonly code: "global_pay_to_usa_debit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "global_pay_to_usa";
     };
     readonly global_pay_to_usa_credit: {
         readonly creditDebitType: "credit";
         readonly code: "global_pay_to_usa_credit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "global_pay_to_usa";
     };
     readonly usa_pay_to_global_debit: {
         readonly creditDebitType: "debit";
         readonly code: "usa_pay_to_global_debit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "usa_pay_to_global";
     };
     readonly usa_pay_to_global_credit: {
         readonly creditDebitType: "credit";
         readonly code: "usa_pay_to_global_credit";
         readonly line: "cbmm";
         readonly category: "international";
+        readonly section: "corridors";
+        readonly group: "usa_pay_to_global";
     };
     readonly onramp_credit: {
         readonly creditDebitType: "credit";
         readonly code: "onramp_credit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "on_ramp";
     };
     readonly offramp_debit: {
         readonly creditDebitType: "debit";
         readonly code: "offramp_debit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "off_ramp";
     };
     readonly stable_payout_debit: {
         readonly creditDebitType: "debit";
         readonly code: "stable_payout_debit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "stable_payout";
     };
     readonly stable_payout_credit: {
         readonly creditDebitType: "credit";
         readonly code: "stable_payout_credit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "stable_payout";
     };
     readonly global_pay_to_generic_debit: {
         readonly creditDebitType: "debit";
         readonly code: "global_pay_to_generic_debit";
         readonly line: "payout";
         readonly category: "payments";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly global_pay_to_generic_credit: {
         readonly creditDebitType: "credit";
         readonly code: "global_pay_to_generic_credit";
         readonly line: "cbmm";
         readonly category: "collections";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly global_rejected: {
         readonly creditDebitType: "credit";
         readonly code: "global_rejected";
         readonly line: "cbmm";
         readonly category: "collections";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly offramp_treasury_credit: {
         readonly creditDebitType: "credit";
         readonly code: "offramp_treasury_credit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: null;
     };
     readonly onramp_debit: {
         readonly creditDebitType: "debit";
         readonly code: "onramp_debit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "on_ramp";
     };
     readonly offramp_credit: {
         readonly creditDebitType: "credit";
         readonly code: "offramp_credit";
         readonly line: "stable";
         readonly category: "conversions";
+        readonly section: "usd_global";
+        readonly group: "off_ramp";
     };
 };
+/** `when_present`: shown in the grouped type filter only when the data contains it. */
+export type TransactionTypeFilterDisplay = "when_present";
 export type TransactionType = keyof typeof TRANSACTION_TYPES;
 export type TransactionTypeRecord = (typeof TRANSACTION_TYPES)[TransactionType];
+/**
+ * UI-only code for the debit/credit legs shown as one option in the grouped type filter. Derived from the
+ * catalog's `group` values; never a key of TRANSACTION_TYPES and never sent to an API (see `expandGroupSelection`).
+ */
+export type TransactionTypeGroup = Exclude<TransactionTypeRecord["group"], null>;