@movmo_app/payments 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -7,6 +7,23 @@ export declare interface CardFieldError {
     message: string;
 }
 
+/**
+ * Focus state of each Spreedly-hosted iframe. The browser's `focus-within`
+ * CSS pseudo-class can't see across iframe boundaries, so the consumer needs
+ * an explicit signal to render the "active border" on the iframe shell.
+ */
+declare interface CardFieldFocus {
+    number: boolean;
+    cvv: boolean;
+}
+
+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 +42,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, onSavingChange, autoFocus, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -36,13 +53,151 @@ 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;
+    /**
+     * Fires whenever the form transitions in / out of the "saving" state
+     * (tokenize call or save POST in flight). A parent rendering its own
+     * Save button (e.g. a modal footer) uses this to swap the button label
+     * for a spinner. The hook's loading state is internal and not surfaced
+     * directly — this callback is the single source of truth.
+     */
+    onSavingChange?: (isSaving: boolean) => void;
+    /**
+     * When set, the named Spreedly hosted-fields iframe receives keyboard
+     * focus the moment the field becomes ready. Use `"number"` for the
+     * accounts-ui add-card modal so the user can start typing immediately.
+     */
+    autoFocus?: 'number' | 'cvv';
+}
+
+/**
+ * Compact preview of a single saved card: brand icon + label. 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.
+ *
+ * Brand icon is sized to match flights-ui main's `w-[34px]` collapsed view.
+ * No vertical padding — the parent controls spacing.
+ */
+export declare const PaymentMethodPreview: ({ method, trailing, onClick, cardLabelFormat, 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;
+    /**
+     * Controls how the card label is rendered.
+     * - `'branded'` (default): "Visa 4242" — brand name + last4
+     * - `'masked'`: "•••• 4242" — masked bullets + last4 (flights-ui collapsed-drawer style)
+     */
+    cardLabelFormat?: 'masked' | 'branded';
+    className?: string;
+}
+
+export declare const PaymentMethodsManager: {
+    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, 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;
+    /**
+     * When `true` AND the user has at least one saved card, the list collapses
+     * into a compact preview row with a chevron-down toggle. Expanding shows the
+     * full list + Add button. Defaults to `false` (accounts-ui behaviour).
+     * flights-ui passes `true`.
+     */
+    collapsible?: boolean;
+    /**
+     * Controls the card label format inside rows.
+     * - `'branded'` (default): "Visa 4242" — brand name + last4
+     * - `'masked'`: "•••• 4242" — masked bullets + last4 (flights-ui style)
+     */
+    cardLabelFormat?: 'masked' | 'branded';
+    className?: string;
 }
 
 export declare interface PaymentMethodSummary {
@@ -56,10 +211,42 @@ 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;
+    /**
+     * Custom `fetch` impl used by every API call in this package. Defaults to
+     * `globalThis.fetch`. Consumers that need auth-token refresh, CSRF-token
+     * injection, or any other request-shaping logic should provide their own
+     * wrapper here (e.g. one that retries on 401/403 after refreshing the
+     * session cookie). The package never adds business headers — that's the
+     * consumer's responsibility.
+     */
+    fetch?: typeof fetch;
 }
 
 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 +266,76 @@ 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;
+    /**
+     * Live focus state for each iframe. True while the user is editing that
+     * field. Consumers use this to apply an "active" border on the iframe shell
+     * (the browser's `:focus-within` CSS doesn't propagate across iframes).
+     */
+    focused: CardFieldFocus;
+    /**
+     * 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 { }