squarefi-bff-api-module 1.36.84 → 1.36.85

package/dist/api/counterparties.d.ts

@@ -9,7 +9,8 @@ export declare const counterparties: {
     destinations: {
         getAll: ({ wallet_id, ...params }: API.Counterparties.Destination.List.Request) => Promise<API.Counterparties.Destination.List.Response>;
         getById: ({ counterparty_destination_id, }: API.Counterparties.Destination.Detail.Request) => Promise<API.Counterparties.Destination.Detail.Response>;
-        create: ({ wallet_id: _wallet_id, external_banking_data, external_crypto_data, internal_data, ...rest }: API.Counterparties.Destination.Create.Request) => Promise<API.Counterparties.Destination.Create.Response>;
+        create: (request: API.Counterparties.Destination.Create.Request) => Promise<API.Counterparties.Destination.Create.Response>;
+        validate: (request: API.Counterparties.Destination.Validate.Request) => Promise<API.Counterparties.Destination.Validate.Response>;
         update: ({ counterparty_destination_id, wallet_id: _wallet_id, counterparty_account_id: _counterparty_account_id, ...data }: API.Counterparties.Destination.Update.Request) => Promise<API.Counterparties.Destination.Update.Response>;
         delete: ({ counterparty_destination_id, request_id, }: API.Counterparties.Destination.Delete.Request) => Promise<void>;
         internalTransfer: ({ counterparty_destination_id, }: API.Counterparties.Destination.InternalTransfer.Request) => Promise<API.Counterparties.Destination.InternalTransfer.Response>;

package/dist/api/counterparties.js

@@ -16,8 +16,20 @@ const mapDestination = (destination) => {
     if (destination.type === 'INTERNAL') {
         return { ...common, internal_data: destination.internal_data };
     }
-    return { ...common, external_banking_data: destination.banking_data };
+    return {
+        ...common,
+        external_banking_data: destination.banking_data,
+        ...(destination.validation_issues ? { validation_issues: destination.validation_issues } : {}),
+    };
 };
+// Тело create/validate: наружу external_* контракт, на провод — ключи фронт-модуля. wallet_id бэкенду
+// не нужен (кошелёк берётся из счёта контрагента) и не отправляется.
+const toDestinationBody = ({ wallet_id: _wallet_id, external_banking_data, external_crypto_data, internal_data, ...rest }) => ({
+    ...rest,
+    ...(external_banking_data ? { banking_data: external_banking_data } : {}),
+    ...(external_crypto_data ? { crypto_data: external_crypto_data } : {}),
+    ...(internal_data ? { internal_data } : {}),
+});
 export const counterparties = {
     getAll: async ({ wallet_id, ...params }) => {
         const res = await apiClientV1Frontend.getRequest(`/frontend/counterparty/accounts/wallet/${wallet_id}`, { params });
@@ -65,16 +77,18 @@ export const counterparties = {
             const res = await apiClientV1Frontend.getRequest(`/frontend/counterparty/destinations/${counterparty_destination_id}`);
             return mapDestination(res.data.destination);
         },
-        create: async ({ wallet_id: _wallet_id, external_banking_data, external_crypto_data, internal_data, ...rest }) => {
-            const data = {
-                ...rest,
-                ...(external_banking_data ? { banking_data: external_banking_data } : {}),
-                ...(external_crypto_data ? { crypto_data: external_crypto_data } : {}),
-                ...(internal_data ? { internal_data } : {}),
-            };
+        create: async (request) => {
+            const data = toDestinationBody(request);
             const res = await apiClientV1Frontend.postRequest(`/frontend/counterparty/destinations`, { data });
             return mapDestination(res.data.destination);
         },
+        // Пробный прогон create: те же проверки реквизитов, ничего не сохраняет. Правила живут
+        // только на бэкенде — формы спрашивают этот вызов вместо собственных проверок формата.
+        validate: async (request) => {
+            const data = toDestinationBody(request);
+            const res = await apiClientV1Frontend.postRequest(`/frontend/counterparty/destinations/validate`, { data });
+            return res.data;
+        },
         update: async ({ counterparty_destination_id, wallet_id: _wallet_id, counterparty_account_id: _counterparty_account_id, ...data }) => {
             const res = await apiClientV1Frontend.patchRequest(`/frontend/counterparty/destinations/${counterparty_destination_id}`, { data });
             return mapDestination(res.data.destination);

package/dist/api/types/autogen/apiV1Frontend.types.d.ts

@@ -1226,7 +1226,8 @@ export interface paths {
          *     Matching is by full code — prefix search is not supported, so `data`
          *     carries at most one element today. A well-formed code that matches no
          *     bank is `200` with an empty `data`, not a 404. Banks that do not accept
-         *     the selected method also resolve to an empty `data`.
+         *     the selected method also resolve to an empty `data` — for `sepa`, that
+         *     includes a bank outside the SEPA zone.
          *
          *     **Authentication**: Bearer token + x-tenant-id header
          *
@@ -1958,6 +1959,183 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/frontend/counterparty/destinations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create destination
+         * @description counterparty_account_id in body. Caller must be owner or admin of the account's wallet and the wallet's KYC must be APPROVED; other members receive 403.
+         *
+         *     **Banking types**: banking_data required. `banking_data.address` (the bank address) is mandatory; `banking_data.beneficiary_address` (the recipient's own postal address, same shape) is optional — when present it must be complete (city, country_id, postcode, street1; state_id on US rails), is never overwritten by bank-directory enrichment, is exempt from the bank-country check, and payouts use it in place of the bank address.
+         *     **Crypto types**: crypto_data required
+         *     **Internal type**: internal_data required (target wallet on the same platform)
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** Format: uuid */
+                        counterparty_account_id: string;
+                        /** @enum {string} */
+                        type: "ACH" | "RTP" | "SWIFT" | "SEPA" | "CRYPTO_EXTERNAL" | "CRYPTO_INTERNAL" | "CHAPS" | "FPS" | "FEDWIRE" | "INTERNAL";
+                        nickname?: string;
+                        banking_data?: Record<string, never>;
+                        crypto_data?: Record<string, never>;
+                        /** @description Required for type INTERNAL — points at the receiver wallet. An account holds one INTERNAL destination per wallet; if it already has an active one to this wallet, that destination is returned instead of a new one. */
+                        internal_data?: {
+                            /**
+                             * Format: uuid
+                             * @description Target (receiver) wallet uuid on the same platform.
+                             */
+                            wallet_id: string;
+                            /** @description Optional, reserved for future use. */
+                            description?: string;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Created */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                destination: components["schemas"]["CounterpartyDestination"];
+                                /** @example Destination created successfully */
+                                message: string;
+                            };
+                        };
+                    };
+                };
+                /** @description Validation error: type-specific payload missing or invalid, target wallet inactive, or the address country contradicts the bank code country (`BANK_COUNTRY_MISMATCH`).
+                 *
+                 *     Bank details are checked per payment method — IBAN (country, length, account format, check digits), SWIFT/BIC, ABA routing number, US/UK account number, sort code, IBAN inside the SEPA zone on SEPA. Every problem is listed in `error.details.issues` (`field`, `code`, `message`, optional `country` / `detected`), so a form can mark each field; `POST /frontend/counterparty/destinations/validate` returns the same list without saving.
+                 *      */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Access denied, or (Clerk tenants) the second-factor verification is
+                 *     stale — `TWO_FACTOR_REVERIFICATION_REQUIRED`: re-verify and retry.
+                 *      */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Account not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/frontend/counterparty/destinations/validate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Validate destination details without saving
+         * @description Dry run of `POST /frontend/counterparty/destinations`: the same body, the same checks —
+         *     bank details per payment method, address completeness, location reference data, the
+         *     bank-country check — and nothing is saved. Answers `200` whether or not the details are
+         *     valid; `valid: false` comes with every problem in `issues`. A form calls it as bank fields
+         *     are left and before submitting, and shows each issue's `message` under its `field`.
+         *
+         *     No counterparty account is needed and no second-factor step-up is asked. Without an account it
+         *     cannot tell whether an INTERNAL target wallet is active — creation still checks that. Rate limited
+         *     to 60 requests per minute per user.
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @enum {string} */
+                        type: "ACH" | "RTP" | "SWIFT" | "SEPA" | "CRYPTO_EXTERNAL" | "CRYPTO_INTERNAL" | "CHAPS" | "FPS" | "FEDWIRE" | "INTERNAL";
+                        banking_data?: Record<string, never>;
+                        crypto_data?: Record<string, never>;
+                        internal_data?: Record<string, never>;
+                    };
+                };
+            };
+            responses: {
+                /** @description Validation result */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: components["schemas"]["DestinationValidationResult"];
+                        };
+                    };
+                };
+                /** @description Too many validation requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/frontend/crypto_wallets/wallet/{wallet_id}": {
         parameters: {
             query?: never;
@@ -15950,9 +16128,38 @@ export interface components {
             banking_data?: components["schemas"]["CounterpartyBankingData"] | null;
             crypto_data?: components["schemas"]["CounterpartyCryptoData"] | null;
             internal_data?: components["schemas"]["CounterpartyInternalData"] | null;
+            /** @description Banking destinations only: problems that make the stored bank details unpayable (an IBAN that fails its checks, an IBAN outside SEPA on a SEPA destination, a routing number that fails the ABA check). Non-empty means withdrawals to this destination are refused with `DESTINATION_INVALID` — details cannot be edited, so add a new destination. Empty for valid banking destinations; absent for crypto and internal ones. */
+            validation_issues?: components["schemas"]["DestinationValidationIssue"][];
             /** @description Embedded on the list and get-by-id reads; absent on create/update. */
             counterparty_account?: components["schemas"]["CounterpartyAccountRef"] | null;
         };
+        /** @description One problem with a destination payload. `field` is the request path of the offending value (`iban`, `routing_number`, `address.city`…); `message` is ready to show under that field. */
+        DestinationValidationIssue: {
+            /** @example iban */
+            field: string;
+            /**
+             * @description Machine-readable reason. Bank details: `REQUIRED`, `IBAN_WRONG_FORMAT`, `IBAN_INVALID_CHARACTERS`, `IBAN_COUNTRY_NOT_SUPPORTED`, `IBAN_WRONG_LENGTH`, `IBAN_WRONG_BBAN_FORMAT`, `IBAN_WRONG_CHECKSUM`, `IBAN_WRONG_NATIONAL_CHECKSUM`, `IBAN_QR_NOT_ALLOWED`, `IBAN_NOT_SEPA`, `IBAN_BIC_COUNTRY_MISMATCH`, `BIC_WRONG_FORMAT`, `BIC_UNKNOWN_COUNTRY`, `BIC_TEST_CODE`, `ROUTING_NUMBER_INVALID`, `ACCOUNT_NUMBER_INVALID`, `SORT_CODE_INVALID`, `WRONG_IDENTIFIER_TYPE`, `INVALID_VALUE`; reference data: `BANK_COUNTRY_MISMATCH`, `VALIDATION_ERROR`; dry run only: `INVALID_TYPE`. New codes may be added — show `message` for an unknown one.
+             * @example IBAN_NOT_SEPA
+             */
+            code: string;
+            /** @example IBAN country AE is outside the SEPA zone — SEPA transfers cannot reach it */
+            message: string;
+            /**
+             * @description ISO 3166-1 alpha-2 country the problem is about, when there is one
+             * @example AE
+             */
+            country?: string;
+            /**
+             * @description For `WRONG_IDENTIFIER_TYPE`: what the value looks like (an IBAN typed into a US account-number field…)
+             * @enum {string}
+             */
+            detected?: "IBAN" | "BIC" | "ROUTING_NUMBER";
+        };
+        DestinationValidationResult: {
+            /** @description True when creating the destination with this payload would pass every check */
+            valid: boolean;
+            issues: components["schemas"]["DestinationValidationIssue"][];
+        };
         /** @description Whether an instant internal transfer is available for a counterparty destination. Two states: available (available=true, target_wallet_id set) and not available (available=false, target_wallet_id=null). Any recipient that cannot receive an instant internal transfer is uniformly reported as not available — the check does not disclose the reason. */
         InternalTransferAvailability: {
             /** @description True when the recipient is an on-platform wallet that can currently receive an instant internal transfer. */

package/dist/api/types/types.d.ts

@@ -481,6 +481,7 @@ export declare namespace API {
             type CryptoDestinationType = Extract<CounterpartyDestinationType, 'CRYPTO_EXTERNAL'> | Extract<CounterpartyDestinationType, 'CRYPTO_INTERNAL'>;
             type InternalDestinationType = Extract<CounterpartyDestinationType, 'INTERNAL'>;
             type DestinationType = BankingDestinationType | CryptoDestinationType | InternalDestinationType;
+            type ValidationIssue = componentsV1Frontend['schemas']['DestinationValidationIssue'];
             namespace List {
                 interface DestinationListItemCommonFields {
                     id: string;
@@ -496,18 +497,21 @@ export declare namespace API {
                     external_banking_data: DestinationListItemExternalBankingData;
                     external_crypto_data?: never;
                     internal_data?: never;
+                    validation_issues?: ValidationIssue[];
                 }
                 interface DestinationListItemWithExternalCryptoData extends DestinationListItemCommonFields {
                     type: CryptoDestinationType;
                     external_banking_data?: never;
                     external_crypto_data: DestinationListItemExternalCryptoData;
                     internal_data?: never;
+                    validation_issues?: never;
                 }
                 interface DestinationListItemWithInternalData extends DestinationListItemCommonFields {
                     type: InternalDestinationType;
                     external_banking_data?: never;
                     external_crypto_data?: never;
                     internal_data: DestinationInternalData;
+                    validation_issues?: never;
                 }
                 type CounterpartyDestinationListItem = DestinationListItemWithExternalBankingData | DestinationListItemWithExternalCryptoData | DestinationListItemWithInternalData;
                 type Request = pathsV1Frontend['/frontend/counterparty/destinations/wallet/{wallet_id}']['get']['parameters']['path'] & NonNullable<pathsV1Frontend['/frontend/counterparty/destinations/wallet/{wallet_id}']['get']['parameters']['query']>;
@@ -550,6 +554,10 @@ export declare namespace API {
                 }
                 type Response = Detail.DestinationDetailItem;
             }
+            namespace Validate {
+                type Request = Omit<Create.Request, 'counterparty_account_id' | 'nickname'>;
+                type Response = componentsV1Frontend['schemas']['DestinationValidationResult'];
+            }
             namespace Delete {
                 type Request = {
                     counterparty_destination_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.36.84",
+  "version": "1.36.85",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",