squarefi-bff-api-module 1.36.52 → 1.36.54

package/dist/api/mass-payouts.d.ts

@@ -7,6 +7,11 @@ import { API } from './types/types';
  *
  * `list` / `items` filter by a single status value (not an array), so they need none of the
  * comma-joining the issuing list endpoints do.
+ *
+ * Two limits live outside this client. The recipient caps are per-tenant and come from
+ * `tenants.config.get()` under `mass_payouts` (`API.MassPayouts.Config`) — never hardcode them.
+ * The batch a payment belongs to is read off the order (`mass_payout`), and a feed is narrowed to
+ * one batch with the `mass_payout_id` order-list filter, not from here.
  */
 export declare const massPayouts: {
     list: ({ wallet_id, ...params }: API.MassPayouts.List.Request) => Promise<API.MassPayouts.List.Response>;

package/dist/api/mass-payouts.js

@@ -7,6 +7,11 @@ import { apiClientV1Frontend } from '../utils/apiClientFactory';
  *
  * `list` / `items` filter by a single status value (not an array), so they need none of the
  * comma-joining the issuing list endpoints do.
+ *
+ * Two limits live outside this client. The recipient caps are per-tenant and come from
+ * `tenants.config.get()` under `mass_payouts` (`API.MassPayouts.Config`) — never hardcode them.
+ * The batch a payment belongs to is read off the order (`mass_payout`), and a feed is narrowed to
+ * one batch with the `mass_payout_id` order-list filter, not from here.
  */
 export const massPayouts = {
     list: ({ wallet_id, ...params }) => apiClientV1Frontend.getRequest(`/frontend/mass-payouts/${wallet_id}`, { params }),
@@ -22,6 +27,11 @@ export const massPayouts = {
     }),
     preview: ({ wallet_id, id }) => apiClientV1Frontend.getRequest(`/frontend/mass-payouts/${wallet_id}/${id}/preview`),
     submit: ({ wallet_id, id }) => apiClientV1Frontend.postRequest(`/frontend/mass-payouts/${wallet_id}/${id}/submit`),
+    // Second factor is mandatory and per-batch: run the `totp.otp_verification` flow with the batch
+    // id as `request_id` and let the user complete it BEFORE calling this, or approve answers 403
+    // `VERIFICATION_NOT_APPROVED` (404 `REQUEST_ID_NOT_FOUND` when none was ever requested). The
+    // check runs before anything is claimed, so a refusal leaves the batch untouched and approve can
+    // simply be retried. Clerk tenants additionally need a step-up verified within the last 10 min.
     approve: ({ wallet_id, id }) => apiClientV1Frontend.postRequest(`/frontend/mass-payouts/${wallet_id}/${id}/approve`),
     cancel: ({ wallet_id, id }) => apiClientV1Frontend.postRequest(`/frontend/mass-payouts/${wallet_id}/${id}/cancel`),
     // `text/csv`, not the JSON envelope — the raw CSV body is resolved as a string. `responseType`

package/dist/api/storage.d.ts

@@ -5,4 +5,13 @@ export declare const storage: {
         getFileUrl: ({ path }: API.Storage.KYC.GetFileUrl.Request) => Promise<API.Storage.KYC.GetFileUrl.Response>;
         getFileById: ({ folderId, fileId, }: API.Storage.KYC.GetFileById.Request) => Promise<API.Storage.KYC.GetFileById.Response>;
     };
+    /**
+     * Supporting documents for orders and mass payouts. Separate bucket from KYC. Upload the file
+     * first, then pass the returned path as `documents[].url` on the order or the mass payout row —
+     * the payout schemas carry the link only, never the bytes. PDF/JPEG/PNG, up to 20 MB.
+     */
+    orderDocuments: {
+        upload: (file: File) => Promise<API.Storage.OrderDocuments.Upload.Response>;
+        getFileById: ({ folderId, fileId, }: API.Storage.OrderDocuments.GetFileById.Request) => Promise<API.Storage.OrderDocuments.GetFileById.Response>;
+    };
 };

package/dist/api/storage.js

@@ -13,4 +13,19 @@ export const storage = {
         }),
         getFileById: ({ folderId, fileId, }) => apiClientV2.getRequest(`/storage/kyc/${folderId}/${fileId}`),
     },
+    /**
+     * Supporting documents for orders and mass payouts. Separate bucket from KYC. Upload the file
+     * first, then pass the returned path as `documents[].url` on the order or the mass payout row —
+     * the payout schemas carry the link only, never the bytes. PDF/JPEG/PNG, up to 20 MB.
+     */
+    orderDocuments: {
+        upload: (file) => {
+            const formData = new FormData();
+            formData.append('file', file);
+            return apiClientV2.postRequest('/storage/order-documents', {
+                data: formData,
+            });
+        },
+        getFileById: ({ folderId, fileId, }) => apiClientV2.getRequest(`/storage/order-documents/${folderId}/${fileId}`),
+    },
 };

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

@@ -4236,6 +4236,8 @@ export interface paths {
                  *     - Missing required fields
                  *     - Invalid reference_id format
                  *     - Invalid amount (must be positive number)
+                 *     - `TOPUP_BELOW_MINIMUM` — credited amount is below the program's
+                 *       `min_topup` threshold (`error.details.min_topup`, program currency)
                  *      */
                 400: {
                     headers: {
@@ -4852,7 +4854,11 @@ export interface paths {
                     limit?: number;
                     sort_by?: string;
                     sort_order?: "asc" | "desc";
-                    /** @description JSON-encoded filters */
+                    /** @description JSON-encoded array of filters, e.g. `[{"status":"COMPLETE"}]`.
+                     *     Besides order columns it accepts `mass_payout_id` (uuid), which narrows the
+                     *     result to the orders of one mass payout batch — the same batch reported by
+                     *     the `mass_payout_id` field of each order. A non-uuid value is rejected with 400.
+                     *      */
                     filters?: string;
                     date_from?: string;
                     date_to?: string;
@@ -8139,6 +8145,12 @@ export interface components {
             sub_account_id?: string | null;
             info?: string | null;
             meta?: components["schemas"]["OrderMeta"];
+            /** @description Batch this order was created by, when it was sent as part of a mass payout; null for a standalone order. Filter the list by it with `filters=[{"mass_payout_id":"<uuid>"}]`. */
+            mass_payout?: {
+                /** Format: uuid */
+                id?: string;
+                name?: string | null;
+            } | null;
             /**
              * Format: date-time
              * @description Requested execution time for scheduled payments (status EXPECTED); null for immediate orders

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

@@ -3632,7 +3632,10 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Validation error */
+                /** @description Validation error. Includes `TOPUP_BELOW_MINIMUM` — credited amount is
+                 *     below the program's `min_topup` threshold (`error.details.min_topup`,
+                 *     program currency). No order created, wallet not debited.
+                 *      */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -4283,6 +4286,9 @@ export interface paths {
                  *     - Invalid reference_id format
                  *     - Invalid amount (must be positive number)
                  *     - Insufficient wallet balance (`INSUFFICIENT_BALANCE`)
+                 *     - `TOPUP_BELOW_MINIMUM` — credited amount is below the program's
+                 *       `min_topup` threshold; `error.details.min_topup` carries the
+                 *       threshold (program currency). No order created, wallet not debited.
                  *      */
                 400: {
                     headers: {
@@ -6693,7 +6699,10 @@ export interface paths {
             parameters: {
                 query?: {
                     status?: "DRAFT" | "PENDING_APPROVAL" | "SCHEDULED" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELED";
-                    /** @description Case-insensitive substring match against the batch name */
+                    /** @description Search box of the batch list: a case-insensitive PARTIAL match
+                     *     against the batch name, so a fragment finds it. LIKE metacharacters
+                     *     in the term are matched literally.
+                     *      */
                     name?: string;
                     /** @description Only batches created at or after this moment */
                     date_from?: string;
@@ -7170,9 +7179,18 @@ export interface paths {
          *     standard order flow, funds are debited per order). The estimated total
          *     debit is checked against the wallet balance first — a batch that
          *     cannot cover all payouts is refused instead of paying only part of the
-         *     list. Requires an administrative wallet role. On Clerk-authenticated
-         *     tenants a second factor verified within the last 10 minutes is also
-         *     required — a stale one is rejected with
+         *     list. Requires an administrative wallet role.
+         *
+         *     **Second factor, per action and mandatory.** Request an OTP
+         *     verification for THIS batch id and have the user complete it before
+         *     calling approve — the endpoint checks that verification and refuses
+         *     unless it came back APPROVED. Releasing a whole batch of payments is
+         *     verified exactly like approving a single order. The check runs before
+         *     anything is claimed or estimated, so a failed one leaves the batch
+         *     untouched and approve can simply be retried.
+         *
+         *     On Clerk-authenticated tenants a second factor verified within the last
+         *     10 minutes is required on top of that — a stale one is rejected with
          *     `TWO_FACTOR_REVERIFICATION_REQUIRED` (Supabase-authenticated tenants
          *     have no step-up check). Execution continues past failed items;
          *     progress is visible through the batch counters.
@@ -7213,7 +7231,10 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Caller lacks an administrative wallet role, or (Clerk tenants) the second-factor verification is stale */
+                /** @description Caller lacks an administrative wallet role, the OTP verification for
+                 *     this batch is not APPROVED (`VERIFICATION_NOT_APPROVED`), or (Clerk
+                 *     tenants) the second-factor verification is stale.
+                 *      */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -7222,6 +7243,15 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description Batch not found, or no OTP verification was requested for it (`REQUEST_ID_NOT_FOUND`) */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
                 /** @description Batch is not awaiting approval, or another operation on it is in flight */
                 409: {
                     headers: {
@@ -9111,7 +9141,11 @@ export interface paths {
                     limit?: number;
                     sort_by?: string;
                     sort_order?: "asc" | "desc";
-                    /** @description JSON-encoded filters */
+                    /** @description JSON-encoded array of filters, e.g. `[{"status":"COMPLETE"}]`.
+                     *     Besides order columns it accepts `mass_payout_id` (uuid), which narrows the
+                     *     result to the orders of one mass payout batch — the same batch reported by
+                     *     the `mass_payout_id` field of each order. A non-uuid value is rejected with 400.
+                     *      */
                     filters?: string;
                     date_from?: string;
                     date_to?: string;
@@ -9178,7 +9212,11 @@ export interface paths {
                 query?: {
                     date_from?: string;
                     date_to?: string;
-                    /** @description JSON-encoded filters */
+                    /** @description JSON-encoded array of filters, e.g. `[{"status":"COMPLETE"}]`.
+                     *     Besides order columns it accepts `mass_payout_id` (uuid), which narrows the
+                     *     result to the orders of one mass payout batch — the same batch reported by
+                     *     the `mass_payout_id` field of each order. A non-uuid value is rejected with 400.
+                     *      */
                     filters?: string;
                     /** @description If `true`, includes dust orders (amount below render threshold for either currency). Defaults to `false` — dust orders are hidden. */
                     show_low_balance?: "true" | "false";
@@ -13543,6 +13581,8 @@ export interface components {
             card_issuing_fee?: number | null;
             card_monthly_fee?: number | null;
             initial_topup?: number | null;
+            /** @description Minimum top-up amount in program currency, compared against the credited amount (0 = no minimum) */
+            min_topup?: number;
             card_design?: {
                 [key: string]: unknown;
             } | null;
@@ -14394,6 +14434,13 @@ export interface components {
             /** @description Computed dust flag — amount below the render threshold for either currency. Returned by the list endpoint (GET /frontend/orders/wallet/{wallet_uuid}); absent from single-order reads. */
             is_threshold_amount?: boolean;
             meta?: components["schemas"]["OrderMeta"];
+            /** @description Batch this order was created by, when it was sent as part of a mass payout; null for a standalone order. Filter the list by it with `filters=[{"mass_payout_id":"<uuid>"}]`. */
+            mass_payout?: {
+                /** Format: uuid */
+                id?: string;
+                /** @description Batch name — null only when the batch can no longer be resolved. */
+                name?: string | null;
+            } | null;
             /**
              * Format: date-time
              * @description Requested execution time for scheduled payments (status EXPECTED); null for immediate orders
@@ -14813,9 +14860,17 @@ export interface components {
             currency_id?: string;
             /**
              * Format: uuid
-             * @description Source virtual account for banking payouts (required only when the batch contains banking recipients)
+             * @description Source virtual account, required for a banking batch — its
+             *     methods are what such a batch sends through.
+             *
+             *     A batch sends ONE way only: internal, crypto or banking, never a
+             *     mix. The first recipient by upload position sets the kind and the
+             *     rest must match it; a recipient of another kind is reported as a
+             *     problem by preview and blocks submit/approve.
+             *
              */
             virtual_account_id?: string | null;
+            /** @description Batch name — required, free-form and NOT unique. Two batches of one wallet may share a name. */
             name?: string;
             /**
              * @description SCHEDULED = approved with a future send date; execution starts automatically at that moment
@@ -14896,7 +14951,13 @@ export interface components {
             amount: number;
             /**
              * Format: uuid
-             * @description Payout currency of this row; omit for the batch source currency. A differing value makes the payout a cross-currency one (the debit is converted at execution time)
+             * @description Payout currency of this row; omit for the batch source currency.
+             *     A differing value makes the payout a cross-currency one (the debit
+             *     is converted at execution time) and is accepted on banking rows
+             *     only — their off-ramp settles in the target currency. Crypto and
+             *     internal rows have no exchange leg, so they must stay in the batch
+             *     source currency.
+             *
              */
             to_currency_id?: string;
             /** @description Optional payment reference for this row */
@@ -14904,10 +14965,19 @@ export interface components {
             /** @description Supporting documents; an INVOICE attachment is required for rows at or above the invoice threshold */
             documents?: components["schemas"]["MassPayoutDocument"][];
         };
+        /** @description A template row has no documents field: an invoice belongs to one
+         *     concrete payment, never to the reusable recipient list. Attach
+         *     documents to the rows of a batch instead.
+         *      */
         MassPayoutTemplateItemInput: {
             /** Format: uuid */
             destination_id: string;
-            amount: number;
+            /** @description Optional in a template: omit it (or send null) to save a recipient
+             *     list whose amounts are filled in later. When present it must be
+             *     positive. A batch created from the template still requires an
+             *     amount on every row.
+             *      */
+            amount?: number | null;
             /** Format: uuid */
             to_currency_id?: string;
             reference?: string;
@@ -14917,7 +14987,8 @@ export interface components {
             id?: string;
             /** Format: uuid */
             destination_id?: string;
-            amount?: number;
+            /** @description Null when the template row has no amount yet. */
+            amount?: number | null;
             /** Format: uuid */
             to_currency_id?: string | null;
             reference?: string | null;

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

@@ -8794,6 +8794,12 @@ export interface components {
             info?: string | null;
             /** @description Filtered to META_ALLOWED_FIELDS */
             meta?: Record<string, never> | null;
+            /** @description Batch this order was created by, when it was sent as part of a mass payout; null for a standalone order. Filter the list by it with `filters=[{"mass_payout_id":"<uuid>"}]`. */
+            mass_payout?: {
+                /** Format: uuid */
+                id?: string;
+                name?: string | null;
+            } | null;
             /**
              * Format: date-time
              * @description Requested execution time for scheduled payments (status EXPECTED); null for immediate orders

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

@@ -313,6 +313,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/storage/order-documents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Upload an order / mass payout document
+         * @description Uploads a document attachment for an order or a mass payout into the dedicated bucket (separate from KYC files) and returns a URL suitable for documents[].url when creating the order / mass payout.
+         */
+        post: operations["StorageController_uploadOrderDocument"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/storage/{type}/{folder_id}/{file_id}": {
         parameters: {
             query?: never;
@@ -1976,6 +1996,18 @@ export interface components {
             default: string;
             supported: string[];
         };
+        SystemMassPayoutsConfigDto: {
+            /** @description Whether mass payouts are available to this tenant. When false, every mass payout endpoint answers as if the feature did not exist. */
+            enabled: boolean;
+            /** @description Recipient rows one batch may carry. Exceeding it is rejected on create/update. */
+            max_items: number;
+            /** @description Rows one template may carry — a template is materialized into a batch, so it shares the batch cap. */
+            max_template_items: number;
+            /** @description Templates one wallet may keep. */
+            max_templates_per_wallet: number;
+            /** @description Supporting documents allowed per recipient row of a batch (template rows carry none). */
+            max_item_documents: number;
+        };
         SystemConfigDto: {
             tenant_id: string;
             app_url: string | null;
@@ -2002,6 +2034,7 @@ export interface components {
             /** @enum {string} */
             auth_provider: "supabase" | "clerk";
             base_currency: string;
+            mass_payouts: components["schemas"]["SystemMassPayoutsConfigDto"];
         };
         SystemChainsResponseDto: {
             total: number;
@@ -2814,12 +2847,48 @@ export interface operations {
             };
         };
     };
+    StorageController_uploadOrderDocument: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    /**
+                     * Format: binary
+                     * @description Allowed types: PDF, JPEG, PNG. Max size: 20 MB.
+                     */
+                    file: string;
+                };
+            };
+        };
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StorageUploadFileResponseDto"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     StorageController_getFile: {
         parameters: {
             query?: never;
             header?: never;
             path: {
-                type: "kyc" | "logo";
+                type: "kyc" | "logo" | "order-documents";
                 folder_id: string;
                 file_id: string;
             };

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

@@ -115,6 +115,17 @@ export declare namespace API {
                 card_issuing_fee: number | null;
                 card_monthly_fee: number | null;
                 initial_topup: number | null;
+                /**
+                 * Minimum top-up in the program's currency, compared against the amount
+                 * CREDITED to the card (after fees and conversion) — the same figure the
+                 * server checks before it refuses a deposit with `TOPUP_BELOW_MINIMUM`.
+                 * `0` means the program sets no minimum. Does not apply to the initial
+                 * top-up at issuance.
+                 *
+                 * Optional on the type because programs served by a backend older than
+                 * the `issuing_programs.min_topup` migration omit it.
+                 */
+                min_topup?: number;
                 status?: IssuingProgramStatus | string;
             }
         }
@@ -270,7 +281,34 @@ export declare namespace API {
             adjustment_type: string;
             review_status: string;
             group: string;
+            /**
+             * What actually left the card: `billing_amount` plus `fee` for a debit
+             * (minus it for a credit, which arrives net of what the vendor keeps).
+             * Equals `billing_amount` when no fee sits inside the operation, so it is
+             * the figure to show as the transaction's amount.
+             */
             total_amount: number;
+            /**
+             * Fee charged INSIDE this operation, in billing currency. `0` for vendors
+             * that bill fees as their own transactions — those arrive as separate rows
+             * with `transaction_type: FEE`. Optional: older backends omit it.
+             */
+            fee?: number;
+            /** Vendor's itemisation of `fee`; empty when it gave none. */
+            fee_details?: TransactionFee[];
+            /**
+             * Units of billing currency per unit of transaction currency, so
+             * `transaction_amount * conversion_rate ≈ billing_amount`. 1 when the
+             * currencies match.
+             */
+            conversion_rate?: number;
+        }
+        /** One line of a transaction's fee itemisation (`TransactionItem.fee_details`). */
+        interface TransactionFee {
+            amount: number;
+            currency: string;
+            /** Vendor's own fee code — no cross-vendor meaning. */
+            type: string | null;
         }
         interface TransactionsList {
             data: TransactionItem[];
@@ -1365,6 +1403,17 @@ export declare namespace API {
         export type MassPayoutTemplateItem = componentsV1Frontend['schemas']['MassPayoutTemplateItem'];
         export type MassPayoutTemplateItemInput = componentsV1Frontend['schemas']['MassPayoutTemplateItemInput'];
         export type MassPayoutTemplateWithItems = componentsV1Frontend['schemas']['MassPayoutTemplateWithItems'];
+        /**
+         * The tenant's own mass payout limits and feature flag, delivered by `tenants.config.get()`
+         * under `mass_payouts`. Read them rather than hardcoding a recipient cap — every whitelabel
+         * tenant carries its own, and the only other way to learn one is to trip a 400.
+         */
+        export type Config = components['schemas']['SystemMassPayoutsConfigDto'];
+        /**
+         * Batch an order came from, as reported on the order itself — `null` for a standalone order.
+         * Filter a feed down to one batch with the `mass_payout_id` order-list filter.
+         */
+        export type OrderMassPayoutRef = componentsV1Frontend['schemas']['Order']['mass_payout'];
         /**
          * Status unions read off the schemas rather than re-declared, so a spec change lands here
          * automatically. `SCHEDULED` = approved with a future send date; `CANCELED` on an item means
@@ -2085,7 +2134,13 @@ export declare namespace API {
                     type OrderListOrderTypeFilter = Record<'order_type', OrderType[] | OrderType>;
                     type OrderListFromUuidFilter = Record<'from_uuid', string[] | string>;
                     type OrderListToUuidFilter = Record<'to_uuid', string[] | string>;
-                    type OrderListFilter = OrderListStatusFilter | OrderListOrderTypeFilter | OrderListFromUuidFilter | OrderListToUuidFilter;
+                    /**
+                     * Narrows the feed to the orders of one mass payout batch — the batch each order
+                     * reports back in `mass_payout`. A single uuid only (not an array); a non-uuid value
+                     * is refused with 400.
+                     */
+                    type OrderListMassPayoutFilter = Record<'mass_payout_id', string>;
+                    type OrderListFilter = OrderListStatusFilter | OrderListOrderTypeFilter | OrderListFromUuidFilter | OrderListToUuidFilter | OrderListMassPayoutFilter;
                     interface Request {
                         wallet_uuid: string;
                         offset?: number;
@@ -2993,6 +3048,22 @@ export declare namespace API {
                 type Response = operations['StorageController_getFile']['responses']['200']['content']['application/octet-stream'];
             }
         }
+        /**
+         * Attachments for orders and mass payouts, in a bucket of their own (not the KYC one). The
+         * uploaded file's link is what `documents[].url` expects on an order or a mass payout row.
+         */
+        namespace OrderDocuments {
+            namespace Upload {
+                type Response = operations['StorageController_uploadOrderDocument']['responses']['201']['content']['application/json'];
+            }
+            namespace GetFileById {
+                interface Request {
+                    folderId: string;
+                    fileId: string;
+                }
+                type Response = operations['StorageController_getFile']['responses']['200']['content']['application/octet-stream'];
+            }
+        }
     }
     namespace Referrals {
         namespace Levels {

package/package.json

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