@movmo_app/payments 0.4.0 → 0.5.1

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;
@@ -139,7 +154,7 @@ 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;
 };
 
@@ -147,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;
     /**
@@ -200,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
@@ -232,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;
 };
 
@@ -253,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
@@ -402,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;