@movmo_app/payments 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -17,6 +17,21 @@ declare interface CardFieldFocus {
     cvv: boolean;
 }
 
+/**
+ * The failure sources that can arise while the hook boots: fetching the
+ * tokenization session, loading the Spreedly iframe script, or registering
+ * handlers / calling `spreedly.init` (the latter two are Spreedly-side, so
+ * they're tagged `spreedly-script`). The bare rejection reason doesn't identify
+ * which step failed, so each is wrapped in an `InitError` carrying its source —
+ * letting `MovmoCardForm` forward the right `PaymentErrorSource` to the
+ * manager's `onError`.
+ *
+ * Declared as a slice of `PaymentErrorSource` via `Extract` so a rename or
+ * removal of either literal in `types.ts` is caught here at compile time rather
+ * than silently drifting from the forwarded value in `MovmoCardForm`.
+ */
+declare type CardFieldsInitErrorSource = Extract<PaymentErrorSource, 'tokenization-session' | 'spreedly-script'>;
+
 declare interface CardFieldValidity {
     /** True only when the card-number field has a complete, length-valid value. */
     number: boolean;
@@ -126,12 +141,20 @@ export declare interface CreateMovmoAuthFetchOptions {
     readCookie?: (name: string) => string | null;
 }
 
+/**
+ * The cardholder/zip subset of {@link UpdatePaymentMethodPatch} that the Edit
+ * flow (MOVMO-381) can mutate. Derived via `Pick` so it stays in sync if the
+ * editable field set grows — shared by the modal, the manager, and
+ * `useUpdatePaymentMethod` so the patch shape isn't restated in three places.
+ */
+declare type EditablePaymentMethodFields = Pick<UpdatePaymentMethodPatch, 'cardholderName' | 'zip'>;
+
 export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 
 /* Excluded from this release type: InternalPaymentsConfig */
 
 export declare const MovmoCardForm: {
-    ({ userId, onSuccess, onError, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, onSavingChange, autoFocus, }: MovmoCardFormProps): JSX_2.Element;
+    ({ userId, onSuccess, onError, onErrorDetail, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, onSavingChange, autoFocus, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -139,6 +162,14 @@ export declare interface MovmoCardFormProps {
     userId: string;
     onSuccess: (paymentMethod: PaymentMethodSummary) => void;
     onError: (error: string) => void;
+    /**
+     * Optional structured-error sink for SDK observability. Fires alongside the
+     * string `onError` (which still drives the banner) with the originating
+     * `source` — `save-from-token`, `card-tokenize`, `tokenization-session`, or
+     * `spreedly-script` — so the parent (`PaymentMethodsManager`) can forward it
+     * to telemetry without losing the failure kind.
+     */
+    onErrorDetail?: (error: PaymentManagerError) => void;
     isDefault?: boolean;
     className?: string;
     /**
@@ -192,6 +223,39 @@ export declare interface MovmoCardFormProps {
     autoFocus?: 'number' | 'cvv';
 }
 
+/**
+ * Identifies which SDK-internal operation produced an error surfaced to the
+ * user. Lets a consumer route `PaymentMethodsManager`'s `onError` to telemetry
+ * (Sentry, console) or UI gates (e.g. mute a Book button) per failure kind.
+ *
+ * - `tokenization-session` — `GET /v1/payments/tokenization-session` failed.
+ * - `spreedly-script`       — the Spreedly Hosted Fields iframe script failed to load or init.
+ * - `card-tokenize`         — Spreedly rejected the card while tokenizing. NOTE: this
+ *                             covers both ordinary inline field validation (a mistyped
+ *                             or incomplete card number / CVV) and genuine vault-internal
+ *                             tokenize failures, so it is high-volume and driven by normal
+ *                             user typos. Treat it as a signal for UI/UX work, not as an
+ *                             alertable error rate on its own.
+ * - `save-from-token`       — `POST /v1/users/.../payment-methods/from-token` failed.
+ * - `list`                  — `GET /v1/users/.../payment-methods` failed.
+ * - `set-default`           — the set-default PUT failed.
+ * - `update`                — the edit-card (cardholder/zip) PUT failed.
+ * - `delete`                — the delete request failed.
+ */
+export declare type PaymentErrorSource = 'tokenization-session' | 'card-tokenize' | 'save-from-token' | 'list' | 'delete' | 'set-default' | 'update' | 'spreedly-script';
+
+/**
+ * Structured error surfaced by `PaymentMethodsManager`'s `onError` callback.
+ * `message` is the same user-facing string rendered in the SDK's error banner;
+ * `cause` carries the original `Error`/rejection where available so consumers
+ * can forward it to `Sentry.captureException`.
+ */
+export declare interface PaymentManagerError {
+    source: PaymentErrorSource;
+    message: string;
+    cause?: unknown;
+}
+
 /**
  * Compact preview of a single saved card: brand icon + label. Used by
  * consumers (e.g. flights-ui's collapsed checkout drawer) to show the
@@ -224,7 +288,7 @@ export declare interface PaymentMethodPreviewProps {
 }
 
 export declare const PaymentMethodsManager: {
-    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, className, }: PaymentMethodsManagerProps): JSX_2.Element;
+    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, onError, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, className, }: PaymentMethodsManagerProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -245,6 +309,16 @@ export declare interface PaymentMethodsManagerProps {
     onSelect?: (method: PaymentMethodSummary) => void;
     /** Fires when the list state changes (add, delete, set-default). */
     onChange?: (items: PaymentMethodSummary[]) => void;
+    /**
+     * SDK-level observability hook. Fires whenever the manager surfaces a failure
+     * to the user, with a discriminated `source`: `list` (load), the add-card
+     * paths (`tokenization-session`, `spreedly-script`, `card-tokenize`,
+     * `save-from-token`), `set-default`, `update` (edit), or `delete`. `message`
+     * matches the rendered banner copy; `cause` carries the original error where
+     * available. Wire it to telemetry (e.g. `Sentry.captureException`) and/or UI
+     * gates. Additive and non-intrusive — errors are still rendered in-SDK.
+     */
+    onError?: (error: PaymentManagerError) => void;
     /**
      * Show the Credit card / PayPal / GooglePay / Klarna / ACH radios above
      * the card-capture form. Only Credit card is functional today; the others
@@ -296,6 +370,22 @@ export declare interface PaymentMethodSummary {
     expMonth: number;
     expYear: number;
     isDefault: boolean;
+    /**
+     * Which vault the row lives in. monolith-api returns this on every row
+     * post-MOVMO-381. Only `'spreedly'` rows accept cardholder/zip metadata
+     * edits — Stripe rows are immutable on those fields and the backend rejects
+     * the patch (4xx). The Edit menu item in PaymentMethodsManager is gated on
+     * this value.
+     *
+     * Optional so the UI doesn't crash on pre-MOVMO-381 monolith deployments
+     * that haven't shipped the new field yet — those rows behave as if
+     * Edit isn't available.
+     */
+    vault?: 'stripe' | 'spreedly';
+    /** Current cardholder name (MOVMO-381). Empty/absent for legacy rows. */
+    cardholderName?: string;
+    /** Current billing ZIP (MOVMO-381). Empty/absent for legacy rows. */
+    zip?: string;
 }
 
 export declare interface PaymentsConfig {
@@ -319,6 +409,14 @@ export declare interface PaymentsConfig {
 
 export declare const setPaymentsConfig: (config: Partial<PaymentsConfig>) => void;
 
+export declare interface UpdatePaymentMethodPatch {
+    isDefault?: boolean;
+    /** MOVMO-381 — editable on Spreedly rows only; monolith-api rejects (4xx) Stripe rows. */
+    cardholderName?: string;
+    /** MOVMO-381 — editable on Spreedly rows only; monolith-api rejects (4xx) Stripe rows. */
+    zip?: string;
+}
+
 /**
  * Calls `DELETE /v1/users/:userId/payment-methods/:methodId`.
  *
@@ -370,6 +468,19 @@ export declare interface UseMovmoCardFieldsOptions {
 export declare interface UseMovmoCardFieldsResult {
     status: 'idle' | 'loading' | 'ready' | 'error';
     error: string | null;
+    /**
+     * When `status === 'error'` from a boot failure, identifies whether the
+     * tokenization-session fetch or the Spreedly script load / init was at fault.
+     * `null` otherwise (field-validation/tokenize errors are reported via
+     * `onFieldErrors`).
+     */
+    errorSource: CardFieldsInitErrorSource | null;
+    /**
+     * The original rejection / thrown value behind a boot failure (the
+     * `InitError`'s `cause`), so consumers can forward it to
+     * `Sentry.captureException`. `null` when not in a boot-error state.
+     */
+    errorCause: unknown;
     tokenize: (data: CardholderTokenizeData) => void;
     /** Latest validity snapshot — also pushed via `onValidityChange`. */
     validity: CardFieldValidity;
@@ -407,6 +518,27 @@ export declare interface UseSetDefaultPaymentMethodResult {
 
 export declare type UseSetDefaultPaymentMethodStatus = 'idle' | 'pending' | 'error';
 
+/**
+ * Calls `PUT /v1/users/:userId/payment-methods/:methodId` with the
+ * cardholder-name + zip subset (MOVMO-381). The backend forwards to Spreedly
+ * for vault-backed rows and rejects the request (4xx) for Stripe-backed rows;
+ * the resulting `Error` carries the server's message so callers can surface it
+ * in the modal.
+ *
+ * Follows the same idle→pending→idle/error contract as
+ * `useSetDefaultPaymentMethod` (throws on failure so optimistic-update
+ * consumers can roll back), with a `(methodId, patch)` signature.
+ */
+export declare const useUpdatePaymentMethod: (userId: string) => UseUpdatePaymentMethodResult;
+
+export declare interface UseUpdatePaymentMethodResult {
+    updatePaymentMethod: (methodId: string, patch: EditablePaymentMethodFields) => Promise<void>;
+    status: UseUpdatePaymentMethodStatus;
+    error: string | null;
+}
+
+export declare type UseUpdatePaymentMethodStatus = 'idle' | 'pending' | 'error';
+
 /**
  * Fetches a user's saved payment methods from monolith-api.
  *