@flopay/node 1.10.5 → 1.11.0

package/README.md

@@ -49,7 +49,7 @@ Type the setup request body with `CreateCardSetupSessionRequest` from `@flopay/s
 
 - `country`: the ISO 3166-1 alpha-2 country the card will be used in.
 - `currency`: the three-letter currency later payments will be charged in. A supplied `currency` becomes the setup session's currency.
-- `futureUse`: `'on_session'` or `'off_session'` (`CardSetupFutureUse`). Send `'on_session'` only when the card will be charged only while the customer is present. For cards charged without the customer present, including cards used both ways, leave it out or send `'off_session'`.
+- `futureUse`: **deprecated** (`CardSetupFutureUse`, `'on_session'` or `'off_session'`). Future use is platform policy: the billing API sets every saved method up `'off_session'` and ignores this value. It is still accepted so existing requests keep working; leave it out of new code.
 
 The context needs billing API v1.9.48 or later. Older billing APIs silently ignore it and set the card up exactly as before. Send values as you hold them: the billing API trims and uppercases `country` and `currency`, validates all three fields, and rejects an invalid value with a `400`. The context describes the transaction and never selects a gateway; the billing API alone decides which gateway verifies the card.
 
@@ -59,9 +59,10 @@ Customers can keep saved payment methods of any type, not only cards, and the se
 
 `@flopay/shared` types the mixed method types for list and delete:
 
-- `SavedPaymentMethodType` is `'card'`, `'wallet'`, `'paypal'`, or `'apm'`. `SAVED_PAYMENT_METHOD_TYPES` lists every value for exhaustive handling.
-- `SavedPaymentMethodDisplay` is one display-only saved method of any type, discriminated by `type`. Every variant has an `id` and a lifecycle `status`. A wallet, PayPal, or APM method always has a safe display `label`. A card has `brand`, `lastFour`, `expiryMonth`, and `expiryYear`, and its `label` is optional: when it is missing, build the display text from `brand` and `lastFour`, as the example below does. No variant carries a reusable credential, token, or card number. An existing `SavedCardDisplay` is a valid `SavedPaymentMethodDisplay` without a `type`, so card-only code keeps compiling.
-- `ListSavedPaymentMethodsQuery` is the list request's optional `type` filter. Leave it out to list every saved method, as card-only integrations do today.
+- `SavedPaymentMethodFamily` is `'card'`, `'wallet'`, `'paypal'`, or `'apm'`: the family a saved method belongs to, for grouping. `SAVED_PAYMENT_METHOD_FAMILIES` lists every value for exhaustive handling. `SavedPaymentMethodType` and `SAVED_PAYMENT_METHOD_TYPES` are deprecated aliases with the same values.
+- `SavedPaymentMethodDisplay` is one display-only saved method of any type, discriminated by its family `type`. Every variant has an `id` and a lifecycle `status`, and may carry the billing API row's `methodType` and `displayLabel`. `methodType` tells methods of one family apart: an Apple Pay row and a Google Pay row are both `type: 'wallet'`, with `methodType` `apple_pay` and `google_pay`. A wallet, PayPal, or APM method always has a safe display `label`, deprecated in favour of `displayLabel`, which holds the same value. A card has `brand`, `lastFour`, `expiryMonth`, and `expiryYear`, its `methodType` is `card`, and its `label` is optional and its `displayLabel` is `null`: build the display text from `brand` and `lastFour` instead, as the example below does. No variant carries a reusable credential, token, or card number. An existing `SavedCardDisplay` is a valid `SavedPaymentMethodDisplay` without a `type`, so card-only code keeps compiling.
+- `ListSavedPaymentMethodsQuery` is the list request's optional `type` filter, a `SavedPaymentMethodListType`. Leave it out to list every saved method, as card-only integrations do today.
+- `SavedPaymentMethodListType` is a method type the billing API accepts for that filter: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, or `us_bank_account`, and `SAVED_PAYMENT_METHOD_LIST_TYPES` lists every value. It filters by method type, never by family, so there is no `wallet` or `apm` filter: ask for `apple_pay` or `google_pay` instead. PayPal is `paypal`, not the setup flow's `paypal_vaulted`.
 - `isSetupCheckoutSession` is `true` for a no-charge setup session (`checkoutMode: 'setup'`, zero amount, no products), whatever methods its `advertisedPaymentMethods` list. `isCardSetupCheckoutSession` is unchanged.
 
 Deleting a saved method works the same way for every type, with the same `PaymentMethodRemovalError` responses.
@@ -138,7 +139,6 @@ export async function createCardSetupSession(post: AuthenticatedPost, userId: st
     userId,
     country: 'GB',
     currency: 'GBP',
-    futureUse: 'off_session',
   };
   const { data } = await post('/v1/checkouts/sessions/setup', request);
 
@@ -146,7 +146,7 @@ export async function createCardSetupSession(post: AuthenticatedPost, userId: st
 }
 ```
 
-List saved payment methods of any type, optionally filtered by `type`, and label each one without branching on a gateway:
+List saved payment methods of any type, optionally filtered by method `type`, and label each one without branching on a gateway:
 
 ```ts
 import type { ListSavedPaymentMethodsQuery, SavedPaymentMethodDisplay } from '@flopay/shared';
@@ -159,16 +159,17 @@ export function describeSavedMethod(method: SavedPaymentMethodDisplay): string {
     case 'wallet':
     case 'paypal':
     case 'apm':
-      return method.label;
+      return method.displayLabel ?? method.label;
     default:
-      // A card; card-only responses may omit `type`.
-      return method.label ?? `${method.brand} ending ${method.lastFour}`;
+      // A card; card-only responses may omit `type`, and a card's `displayLabel` is null.
+      return method.displayLabel ?? method.label ?? `${method.brand} ending ${method.lastFour}`;
   }
 }
 
-export async function listSavedWallets(list: AuthenticatedList): Promise<string[]> {
-  const wallets = await list({ type: 'wallet' });
-  return wallets.map(describeSavedMethod);
+export async function listSavedApplePay(list: AuthenticatedList): Promise<string[]> {
+  // Filter by method type: the billing API accepts `apple_pay`, never the `wallet` family.
+  const methods = await list({ type: 'apple_pay' });
+  return methods.map(describeSavedMethod);
 }
 ```
 
@@ -262,7 +263,7 @@ The parameter and result types (`CreateSessionParams`, `CheckoutSessionResult`,
 
 `@flopay/node` has no card-setup method and holds no merchant credential. `CreateCardSetupSessionRequest` and `CardSetupFutureUse`, also exported by `@flopay/shared`, type the body your server sends to the authenticated `POST /v1/checkouts/sessions/setup` route with its own billing API client.
 
-Saved payment methods of any type are typed by `@flopay/shared` too: `SavedPaymentMethodDisplay`, `SavedPaymentMethodType`, `ListSavedPaymentMethodsQuery`, `AdvertisedPaymentMethod`, and the `isSetupCheckoutSession` guard. `@flopay/node` adds no list or delete method for them.
+Saved payment methods of any type are typed by `@flopay/shared` too: `SavedPaymentMethodDisplay`, `SavedPaymentMethodFamily` (with the deprecated alias `SavedPaymentMethodType`), `ListSavedPaymentMethodsQuery` and its `SavedPaymentMethodListType` filter values, `AdvertisedPaymentMethod`, and the `isSetupCheckoutSession` guard. `@flopay/node` adds no list or delete method for them.
 
 ## Errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flopay/node",
-  "version": "1.10.5",
+  "version": "1.11.0",
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "stripe": "^22.2.1",
-    "@flopay/shared": "1.10.5"
+    "@flopay/shared": "1.11.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",