squarefi-bff-api-module 1.36.53 → 1.36.55

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

@@ -4854,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;
@@ -7375,6 +7379,8 @@ export interface components {
              * @description Associated issuing program ID
              */
             issuing_program_id?: string;
+            /** @description Cards issued to this person (every status, canceled included), including cards on sibling per-vendor rows of the same person. Always present on list/get/PATCH; 0 when none. */
+            cards_count?: number;
             address?: components["schemas"]["CardholderAddress"];
         };
         /** @description An uploaded KYC file, addressable before it is attached to a cardholder */
@@ -8141,6 +8147,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

@@ -4602,8 +4602,8 @@ export interface paths {
                                 code?: string | null;
                                 /** @description Initial topup amount */
                                 initial_topup?: number | null;
-                                /** @description Card design configuration */
-                                card_design?: Record<string, never> | null;
+                                /** @description Card artwork for this program; null = use the app's built-in design */
+                                card_design?: components["schemas"]["CardDesign"] | null;
                                 /** @description Legal consent text for card creation */
                                 consent_text?: string | null;
                                 /** @description One-time card issuing fee */
@@ -4702,7 +4702,8 @@ export interface paths {
                                 icon?: string | null;
                                 code?: string | null;
                                 initial_topup?: number | null;
-                                card_design?: Record<string, never> | null;
+                                /** @description Card artwork for this program; null = use the app's built-in design */
+                                card_design?: components["schemas"]["CardDesign"] | null;
                                 consent_text?: string | null;
                                 card_issuing_fee?: number | null;
                                 card_monthly_fee?: number | null;
@@ -6699,7 +6700,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;
@@ -7176,9 +7180,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.
@@ -7219,7 +7232,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;
@@ -7228,6 +7244,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: {
@@ -9117,7 +9142,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;
@@ -9184,7 +9213,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";
@@ -13501,6 +13534,27 @@ export interface components {
             /** Format: date-time */
             created_at: string;
         };
+        /** @description How a card issued on this program is painted. Normalized on read, so every field here is either absent or usable — the abandoned shapes still in the column (`style.color`, `front_img`/`back_img`, a double-encoded JSON string) never reach a client. `null` means the program has no design: fall back to the app's built-in artwork. */
+        CardDesign: {
+            /**
+             * @description Contract version.
+             * @enum {integer}
+             */
+            version: 1;
+            /** @description The card face. One artwork for both themes — a card is a printed object, it does not restyle when the app does. */
+            cover?: {
+                /**
+                 * Format: uri
+                 * @description Absolute https URL of the artwork, authored at 2x of 318×200 (636×400).
+                 */
+                image_url?: string;
+            };
+            /**
+             * @description Hex colour for every text on the card (balance, nickname, masked PAN). Set it when the artwork needs contrast the app-wide card text colour does not give.
+             * @example #ffffff
+             */
+            text_color?: string;
+        };
         /** @description Issuing program configuration (`issuing_programs` row). When joined it also carries nested `order_types`, `kyc_rails` and `integration_vendors` (hence additionalProperties). */
         IssuingProgram: {
             /** Format: uuid */
@@ -13551,9 +13605,7 @@ export interface components {
             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;
+            card_design?: components["schemas"]["CardDesign"] | null;
             /** Format: uuid */
             kyc_rails_id?: string | null;
             /** Format: uuid */
@@ -13660,6 +13712,8 @@ export interface components {
             /** @description Embedded sub-account summary, or null when no sub-account is linked. Present on the normal (vendor-enriched) response; omitted only in the degraded local-only error mode. */
             sub_account: components["schemas"]["IssuingCardSubAccount"] | null;
             limits?: components["schemas"]["IssuingCardLimits"] | null;
+            /** @description This card's artwork, copied from its issuing program so a client needs no second request to paint the card. `null` = the program has no design, use the app's built-in artwork. */
+            card_design?: components["schemas"]["CardDesign"] | null;
             /** Format: date-time */
             created_at?: string;
             /** Format: date-time */
@@ -13849,6 +13903,8 @@ export interface components {
              * @description CORE user this cardholder is linked to (user_data provisioning mode); null for manually-created cardholders.
              */
             user_data_uuid?: string | null;
+            /** @description Cards issued to this person (every status, canceled included), including cards on sibling per-vendor rows of the same person. Always present on list/get/PATCH; 0 when none. */
+            cards_count?: number;
             vendor_id?: string | null;
             vendor_name?: string | null;
             vendor_type?: string | null;
@@ -14402,6 +14458,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
@@ -14821,9 +14884,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
@@ -14904,7 +14975,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 */
@@ -14912,10 +14989,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;
@@ -14925,7 +15011,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/apiV1Legacy.types.d.ts

@@ -7528,6 +7528,60 @@ export interface components {
                 mon_min_usd?: number;
             } | null;
         };
+        AuthResponse: {
+            /** @description JWT access token */
+            access_token?: string;
+            /**
+             * @description Token type (bearer)
+             * @enum {string}
+             */
+            token_type?: "bearer";
+            /** @description Seconds until token expiration */
+            expires_in?: number;
+            /** @description Token expiration timestamp */
+            expires_at?: number;
+            /** @description Refresh token for obtaining new access token */
+            refresh_token?: string;
+            user?: components["schemas"]["User"];
+        };
+        User: {
+            /** @description User's unique identifier */
+            id?: string;
+            /** @description Audience for the token */
+            aud?: string;
+            /** @description User's role */
+            role?: string;
+            /** @description User's email address */
+            email?: string;
+            /**
+             * Format: date-time
+             * @description When email was confirmed
+             */
+            email_confirmed_at?: string;
+            /** @description User's phone number */
+            phone?: string;
+            /**
+             * Format: date-time
+             * @description When user was confirmed
+             */
+            confirmed_at?: string;
+            /**
+             * Format: date-time
+             * @description When recovery email was sent
+             */
+            recovery_sent_at?: string;
+            /**
+             * Format: date-time
+             * @description Last sign in timestamp
+             */
+            last_sign_in_at?: string;
+            identities?: Record<string, never>[];
+            /** Format: date-time */
+            created_at?: string;
+            /** Format: date-time */
+            updated_at?: string;
+            is_anonymous?: boolean;
+        };
         SubAccount: {
             /**
              * @description Unique identifier for the sub-account
@@ -8311,7 +8365,6 @@ export interface components {
                 [key: string]: unknown;
             };
         };
-        User: unknown;
         Wallet: unknown;
         WalletDetailed: unknown;
         CryptoAddress: unknown;

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

@@ -8043,6 +8043,8 @@ export interface components {
              * @description Associated issuing program ID
              */
             issuing_program_id?: string;
+            /** @description Cards issued to this person (every status, canceled included), including cards on sibling per-vendor rows of the same person. Always present on list/get/PATCH; 0 when none. */
+            cards_count?: number;
             address?: components["schemas"]["CardholderAddress"];
         };
         /** @description An uploaded KYC file, addressable before it is attached to a cardholder */
@@ -8794,6 +8796,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

@@ -88,6 +88,27 @@ export declare namespace API {
         }
     }
     namespace Cards {
+        /**
+         * How a card is painted: the artwork of the issuing program it belongs to.
+         *
+         * Normalized by the BFF on every read, so each field is either absent or
+         * usable — the abandoned shapes the `card_design` column still holds
+         * (`style.color`, `front_img`/`back_img`, a double-encoded JSON string)
+         * never reach a client. `null` means the program has no design and the app
+         * paints its own built-in artwork instead.
+         *
+         * One artwork covers both themes: a card face is a printed object, not a UI
+         * surface, so it does not restyle when the app does.
+         */
+        interface CardDesign {
+            version: 1;
+            cover?: {
+                /** Absolute https URL of the artwork, authored at 636×400 (2× the card). */
+                image_url?: string;
+            };
+            /** Hex colour for every text on the card face (balance, nickname, PAN). */
+            text_color?: string;
+        }
         namespace Config {
             type IssuingProgramOrderType = {
                 id: string;
@@ -127,6 +148,12 @@ export declare namespace API {
                  */
                 min_topup?: number;
                 status?: IssuingProgramStatus | string;
+                /**
+                 * The program's artwork. Present on DETAILED program responses only;
+                 * `null` when the program has none. Cards carry their own copy
+                 * (`IssuingCardListItem.card_design`) — read that when painting a card.
+                 */
+                card_design?: API.Cards.CardDesign | null;
             }
         }
         interface User {
@@ -204,6 +231,13 @@ export declare namespace API {
             type: CardType | string;
             form_factor: CardFormFactor | string;
             tokenizable: boolean;
+            /**
+             * This card's artwork, copied from its issuing program. Served WITH the
+             * card on purpose: joining against the program catalogue client-side
+             * costs a second request AND makes the card visibly swap artwork once
+             * that lands. `null` = no design, paint the app's built-in one.
+             */
+            card_design?: API.Cards.CardDesign | null;
         }
         interface IssuingCardDetailItem {
             id: string;
@@ -220,6 +254,8 @@ export declare namespace API {
             tokenizable: boolean;
             issuing_programs: API.Cards.Config.Program;
             limits?: API.Cards.Limits.Limits;
+            /** This card's artwork; see `IssuingCardListItem.card_design`. */
+            card_design?: API.Cards.CardDesign | null;
         }
         interface SubAccountCardListItem {
             type: string;
@@ -1403,6 +1439,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
@@ -2123,7 +2170,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;
@@ -3031,6 +3084,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.53",
+  "version": "1.36.55",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",