@movmo_app/payments 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -7,6 +7,13 @@ export declare interface CardFieldError {
     message: string;
 }
 
+declare interface CardFieldValidity {
+    /** True only when the card-number field has a complete, length-valid value. */
+    number: boolean;
+    /** True only when the CVV field has a complete value (3 or 4 digits). */
+    cvv: boolean;
+}
+
 export declare type CardFormStatus = 'idle' | 'loading' | 'ready' | 'tokenizing' | 'saving' | 'error';
 
 export declare interface CardholderTokenizeData {
@@ -25,7 +32,7 @@ export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 /* Excluded from this release type: InternalPaymentsConfig */
 
 export declare const MovmoCardForm: {
-    ({ userId, onSuccess, onError, isDefault, className, defaultCardholderFirstName, defaultCardholderLastName, }: MovmoCardFormProps): JSX_2.Element;
+    ({ userId, onSuccess, onError, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -36,13 +43,115 @@ export declare interface MovmoCardFormProps {
     isDefault?: boolean;
     className?: string;
     /**
-     * Pre-fills the cardholder first-name input. Cardholders aren't always the
+     * Pre-fills the cardholder name input. Cardholders aren't always the
      * logged-in user (spouse card, corporate card), so the field remains
-     * editable — pass `user.firstName` as a sensible default.
+     * editable — pass `user.fullName` as a sensible default.
+     */
+    defaultCardholderName?: string;
+    /**
+     * @deprecated Prefer `defaultCardholderName`. Concatenated with
+     * `defaultCardholderLastName` to seed the single cardholder name field.
      */
     defaultCardholderFirstName?: string;
-    /** Pre-fills the cardholder last-name input. See `defaultCardholderFirstName`. */
+    /** @deprecated See `defaultCardholderFirstName`. */
     defaultCardholderLastName?: string;
+    /**
+     * When true, the form submits automatically the moment all fields are valid —
+     * no Save button is rendered. Matches the flights-ui "first card" auto-save UX.
+     * Defaults to `false`.
+     */
+    autoSave?: boolean;
+    /**
+     * HTML `id` for the underlying `<form>` element. Lets a parent (e.g. modal
+     * footer) wire its own submit button via `<button type="submit" form="...">`
+     * — useful when `hideInternalSaveButton` is true. Defaults to `movmo-card-form`.
+     */
+    formId?: string;
+    /**
+     * When true, the form omits its internal Save button. Use together with
+     * `formId` to drive submit from a parent (e.g. a modal footer's Save button).
+     */
+    hideInternalSaveButton?: boolean;
+    /**
+     * Fires whenever the "ready to submit" state changes (all fields valid +
+     * not in flight). Use to enable / disable an external Save button.
+     */
+    onCanSubmitChange?: (canSubmit: boolean) => void;
+}
+
+/**
+ * Compact preview of a single saved card: brand icon + "Brand last4".
+ * Used by consumers (e.g. flights-ui's collapsed checkout drawer) to show
+ * the currently-selected card outside the full `<PaymentMethodsManager />`
+ * list view. Keeps the brand-icon styling consistent with the expanded list.
+ */
+export declare const PaymentMethodPreview: ({ method, trailing, onClick, className, }: PaymentMethodPreviewProps) => JSX_2.Element;
+
+export declare interface PaymentMethodPreviewProps {
+    /**
+     * The card to render. Consumers typically derive this from
+     * `useUserPaymentMethods(userId)` — e.g. the selected card in a checkout
+     * drawer, or the default card on a summary line.
+     */
+    method: PaymentMethodSummary;
+    /** Trailing slot — flights-ui drops an expand-chevron button here. */
+    trailing?: React.ReactNode;
+    /** Whole-row click handler — typically toggles the drawer open. */
+    onClick?: () => void;
+    className?: string;
+}
+
+export declare const PaymentMethodsManager: {
+    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, className, }: PaymentMethodsManagerProps): JSX_2.Element;
+    displayName: string;
+};
+
+export declare interface PaymentMethodsManagerProps {
+    userId: string;
+    /**
+     * Pre-fill the single cardholder-name input in the add-card form.
+     * Falls back to `defaultCardholderFirstName + " " + defaultCardholderLastName`
+     * for backward compatibility with the legacy MovmoCardForm props.
+     */
+    defaultCardholderName?: string;
+    /** @deprecated Use `defaultCardholderName`. */
+    defaultCardholderFirstName?: string;
+    /** @deprecated Use `defaultCardholderName`. */
+    defaultCardholderLastName?: string;
+    /** Selection (opt-in). When `onSelect` is provided, each row renders a radio. */
+    selectedId?: string;
+    onSelect?: (method: PaymentMethodSummary) => void;
+    /** Fires when the list state changes (add, delete, set-default). */
+    onChange?: (items: PaymentMethodSummary[]) => void;
+    /**
+     * Show the Credit card / PayPal / GooglePay / Klarna / ACH radios above
+     * the card-capture form. Only Credit card is functional today; the others
+     * render as "Coming soon" to match the existing flights-ui design without
+     * dropping the visual cues. Defaults to `true`. accounts-ui can opt out
+     * by passing `false`.
+     */
+    paymentTypeSelector?: boolean;
+    /**
+     * When `true` AND the user has zero saved cards, the card form auto-submits
+     * the moment all fields are valid. Matches the flights-ui first-card UX.
+     * Defaults to `true`.
+     */
+    autoSaveFirstCard?: boolean;
+    /**
+     * When `true`, clicking a row both fires `onSelect` AND sets that method
+     * as the default (the flights-ui checkout model: "selected = default").
+     * Also hides the "Set as default" menu item since the row click already
+     * does it. Requires `onSelect` to be useful. Defaults to `false`.
+     */
+    selectionSetsDefault?: boolean;
+    /**
+     * Render the green "Default" pill on the default row. accounts-ui keeps
+     * this on; flights-ui passes `false` (the thick selected-border alone
+     * communicates default since `selectionSetsDefault` couples the two).
+     * Defaults to `true`.
+     */
+    showDefaultBadge?: boolean;
+    className?: string;
 }
 
 export declare interface PaymentMethodSummary {
@@ -56,10 +165,33 @@ export declare interface PaymentMethodSummary {
 
 export declare interface PaymentsConfig {
     baseUrl: string;
+    /**
+     * Base URL for Movmo's payment-icon assets (Visa / MC / Amex / Discover SVGs
+     * + PayPal / GooglePay / Klarna PNGs). Defaults to the e2e CDN; prod
+     * consumers should override at boot once a prod CDN is set up.
+     */
+    iconCdnBaseUrl?: string;
 }
 
 export declare const setPaymentsConfig: (config: Partial<PaymentsConfig>) => void;
 
+/**
+ * Calls `DELETE /v1/users/:userId/payment-methods/:methodId`.
+ *
+ * The hook owns the network call + status; consumers own list state so they
+ * can apply optimistic updates / rollback at their layer. The returned promise
+ * resolves on success and rejects on failure so callers can roll back.
+ */
+export declare const useDeletePaymentMethod: (userId: string) => UseDeletePaymentMethodResult;
+
+export declare interface UseDeletePaymentMethodResult {
+    deletePaymentMethod: (methodId: string) => Promise<void>;
+    status: UseDeletePaymentMethodStatus;
+    error: string | null;
+}
+
+export declare type UseDeletePaymentMethodStatus = 'idle' | 'pending' | 'error';
+
 /**
  * Mounts PCI-safe card-capture fields into the DOM containers identified by
  * `numberEl` and `cvvEl`, fetches a signed tokenization session from
@@ -79,12 +211,70 @@ export declare interface UseMovmoCardFieldsOptions {
     cvvEl?: string;
     onCardTokenized?: (token: string) => void;
     onFieldErrors?: (errors: CardFieldError[]) => void;
+    /**
+     * Fires whenever per-field validity changes (number length valid, CVV length valid).
+     * Use to gate the save button at the form layer.
+     */
+    onValidityChange?: (validity: CardFieldValidity) => void;
+    /**
+     * Fires whenever the detected card brand changes (visa/master/american_express/discover/etc).
+     * Use to render the brand icon inline with the card-number field.
+     */
+    onBrandChange?: (brand: string | null) => void;
 }
 
 export declare interface UseMovmoCardFieldsResult {
     status: 'idle' | 'loading' | 'ready' | 'error';
     error: string | null;
     tokenize: (data: CardholderTokenizeData) => void;
+    /** Latest validity snapshot — also pushed via `onValidityChange`. */
+    validity: CardFieldValidity;
+    /** Latest detected brand (or null if unknown). */
+    brand: string | null;
+    /**
+     * Programmatically move keyboard focus into one of the Spreedly iframes.
+     * No-op when the hook is not in the `'ready'` state. Used to auto-advance
+     * focus from an outer form input (e.g. expiry) into a hosted field (CVV).
+     */
+    focusField: (field: 'number' | 'cvv') => void;
 }
 
+/**
+ * Calls `PUT /v1/users/:userId/payment-methods/:methodId` with
+ * `{ isDefault: true }`. Server clears the previous default automatically.
+ *
+ * The hook owns the network call + status; consumers own list state so they
+ * can apply optimistic updates / rollback at their layer. The returned promise
+ * resolves on success and rejects on failure so callers can roll back.
+ */
+export declare const useSetDefaultPaymentMethod: (userId: string) => UseSetDefaultPaymentMethodResult;
+
+export declare interface UseSetDefaultPaymentMethodResult {
+    setDefault: (methodId: string) => Promise<void>;
+    status: UseSetDefaultPaymentMethodStatus;
+    error: string | null;
+}
+
+export declare type UseSetDefaultPaymentMethodStatus = 'idle' | 'pending' | 'error';
+
+/**
+ * Fetches a user's saved payment methods from monolith-api.
+ *
+ * Auto-runs on mount and whenever `userId` changes. Cancels the in-flight
+ * request on unmount or refetch so consumers don't see stale results land
+ * after a navigation. Status mirrors `useMovmoCardFields`:
+ * `idle` → `loading` → `ready | error`.
+ */
+export declare const useUserPaymentMethods: (userId: string) => UseUserPaymentMethodsResult;
+
+export declare interface UseUserPaymentMethodsResult {
+    items: PaymentMethodSummary[];
+    status: UseUserPaymentMethodsStatus;
+    error: string | null;
+    /** Re-issues the GET request. Cancels any in-flight request first. */
+    refetch: () => void;
+}
+
+export declare type UseUserPaymentMethodsStatus = 'idle' | 'loading' | 'ready' | 'error';
+
 export { }