squarefi-bff-api-module 1.36.47 → 1.36.48

package/dist/api/frontend.d.ts

@@ -23,8 +23,18 @@ export declare const frontend: {
             limits: {
                 update: ({ card_id, ...data }: API.Frontend.Issuing.Cards.Limits.Request) => Promise<API.Frontend.Issuing.Cards.Limits.Response>;
             };
-            /** Card PAN/CVV, encrypted for the caller's key. */
+            /**
+             * PLAINTEXT PAN/CVV — server-to-server only. In a browser or mobile client use
+             * `sensitiveEncrypted` instead, so the card number never travels readable.
+             */
             sensitive: ({ card_id, }: API.Frontend.Issuing.Cards.Sensitive.Request) => Promise<API.Frontend.Issuing.Cards.Sensitive.Response>;
+            /**
+             * PAN/CVV over the encrypted channel: generates an AES-256 key, sends it encrypted to
+             * the server's RSA public key (`SERVER_PUBLIC_KEY_BASE64`) and decrypts the answer —
+             * the same exchange as the legacy `issuing.cards.sensitiveData.encrypted.secretKey`,
+             * against the frontend route.
+             */
+            sensitiveEncrypted: ({ card_id, }: API.Frontend.Issuing.Cards.SensitiveEncrypted.Request) => Promise<API.Frontend.Issuing.Cards.SensitiveEncrypted.Response>;
             transactions: ({ card_id, ...params }: API.Frontend.Issuing.Cards.Transactions.Request) => Promise<API.Frontend.Issuing.Cards.Transactions.Response>;
             create: (data: API.Frontend.Issuing.Cards.Create.Request) => Promise<API.Frontend.Issuing.Cards.Create.Response>;
         };

package/dist/api/frontend.js

@@ -1,4 +1,5 @@
 import { apiClientV1, apiClientV1Frontend } from '../utils/apiClientFactory';
+import { makeSecureRequest } from '../utils/encrypt';
 export const frontend = {
     access: {
         keys: {
@@ -39,8 +40,27 @@ export const frontend = {
             limits: {
                 update: ({ card_id, ...data }) => apiClientV1Frontend.putRequest(`/frontend/issuing/cards/${card_id}/limits`, { data }),
             },
-            /** Card PAN/CVV, encrypted for the caller's key. */
+            /**
+             * PLAINTEXT PAN/CVV — server-to-server only. In a browser or mobile client use
+             * `sensitiveEncrypted` instead, so the card number never travels readable.
+             */
             sensitive: ({ card_id, }) => apiClientV1Frontend.getRequest(`/frontend/issuing/cards/${card_id}/sensitive`),
+            /**
+             * PAN/CVV over the encrypted channel: generates an AES-256 key, sends it encrypted to
+             * the server's RSA public key (`SERVER_PUBLIC_KEY_BASE64`) and decrypts the answer —
+             * the same exchange as the legacy `issuing.cards.sensitiveData.encrypted.secretKey`,
+             * against the frontend route.
+             */
+            sensitiveEncrypted: async ({ card_id, }) => {
+                const serverPublicKey = process.env.SERVER_PUBLIC_KEY_BASE64;
+                if (!serverPublicKey) {
+                    throw new Error('SERVER_PUBLIC_KEY_BASE64 is not set');
+                }
+                return makeSecureRequest({
+                    callback: (props) => apiClientV1Frontend.postRequest(`/frontend/issuing/cards/${card_id}/sensitive/secretkey`, { data: props }),
+                    publicKey: serverPublicKey,
+                });
+            },
             transactions: ({ card_id, ...params }) => apiClientV1Frontend.getRequest(`/frontend/issuing/cards/${card_id}/transactions`, { params }),
             create: (data) => apiClientV1Frontend.postRequest('/frontend/issuing/cards', {
                 data,

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

@@ -2058,6 +2058,8 @@ export interface paths {
                     wallet_id?: string;
                     /** @description Filter cards by program ID */
                     program_id?: string;
+                    /** @description Only cards drawing from this sub-account. */
+                    sub_account_id?: string;
                     /** @description Filter cards by program sub-account type (prepaid or balance) */
                     sub_account_type?: "prepaid" | "balance";
                     /** @description Filter cards by status (matches issuing_cards.card_status).
@@ -2595,6 +2597,89 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/frontend/issuing/cards/{card_id}/sensitive/secretkey": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Get card sensitive data over an encrypted channel
+         * @description PAN / CVV without ever putting them in a readable response body — prefer this
+         *     over `GET /sensitive` in any browser or mobile client.
+         *
+         *     The client generates a 32-byte AES-256 key, encrypts it to the server's RSA
+         *     public key (`RSA-OAEP`; `PKCS1` is accepted for older clients) and sends it
+         *     base64-encoded as `encrypted_key`. The response carries the card data
+         *     AES-256-CBC encrypted with that same key, plus the `iv` used.
+         *
+         *     Decrypting `data` with the key and IV yields
+         *     `{ success, data: { card_number, cvv, expiry_month, expiry_year, security_code }, timestamp }`.
+         *
+         *     **Access**: ADMIN on the card's wallet, or the scoped `user` role on their OWN card.
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    card_id: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description Base64 of the AES-256 key encrypted to the server's RSA public key. */
+                        encrypted_key: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Encrypted sensitive data */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            /** @example true */
+                            encrypted: boolean;
+                            /** @description Base64 AES-256-CBC ciphertext of the sensitive-data envelope. */
+                            data: string;
+                            /** @description Base64 IV used for the AES encryption. */
+                            iv: string;
+                        };
+                    };
+                };
+                /** @description Missing or undecryptable `encrypted_key`, or a key that is not 32 bytes */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Server key not configured, or encryption failed */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/frontend/issuing/cards/{card_id}/freeze": {
         parameters: {
             query?: never;
@@ -12257,11 +12342,12 @@ export interface components {
                 [key: string]: unknown;
             } | null;
         };
-        /** @description Sub-account funding a card — the subset of `fiat_accounts` columns joined onto each card. */
+        /** @description Sub-account funding a card — the `fiat_accounts` row joined onto each card, with the same `currency` / `issuing_program` / `account_details` enrichment `GET /sub-accounts` applies, so a card page can drive top-up and render balances without a second request. */
         IssuingCardSubAccount: {
             /** Format: uuid */
             id: string;
             nick_name?: string | null;
+            /** @description Live balance from the issuing ledger (falls back to the cached column). */
             balance?: number | null;
             /** @enum {string} */
             type: "balance" | "prepaid";
@@ -12275,6 +12361,11 @@ export interface components {
              * @description crypto.uuid of the account currency
              */
             account_currency: string;
+            currency?: components["schemas"]["CurrencyRef"];
+            /** @description Program embed (carries `order_types`, which the top-up flow reads); null when program_id is null. */
+            issuing_program?: components["schemas"]["IssuingProgram"] | null;
+            /** @description Bank details from the vendor meta; empty string `""` when none are available. */
+            account_details?: components["schemas"]["BankAccountDetails"] | "";
             /** Format: uuid */
             program_id?: string | null;
             /** Format: uuid */

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

@@ -788,13 +788,28 @@ export declare namespace API {
                     } & CardLimitsRoot['put']['requestBody']['content']['application/json'];
                     type Response = CardLimitsRoot['put']['responses']['200']['content']['application/json'];
                 }
-                /** Card PAN/CVV, encrypted for the caller's key. */
+                /**
+                 * Card PAN/CVV in PLAINTEXT. Server-to-server only — a browser or mobile client
+                 * should use `SensitiveEncrypted`, which never puts the PAN in a readable body.
+                 */
                 namespace Sensitive {
                     type Request = {
                         card_id: string;
                     };
                     type Response = CardSensitiveRoot['get']['responses']['200']['content']['application/json'];
                 }
+                /**
+                 * Card PAN/CVV over an end-to-end encrypted channel: the client's AES-256 key is
+                 * sent encrypted to the server's RSA public key, and the answer comes back
+                 * encrypted with that same key. The SDK does the key exchange and the decryption,
+                 * so the caller just receives the decrypted payload.
+                 */
+                namespace SensitiveEncrypted {
+                    type Request = {
+                        card_id: string;
+                    };
+                    type Response = API.Cards.SensitiveData;
+                }
                 namespace Transactions {
                     type Request = {
                         card_id: string;

package/package.json

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