@movmo_app/payments 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -39,6 +39,8 @@ declare interface CardFieldValidity {
     cvv: boolean;
 }
 
+export declare type CardFormField = 'number' | 'expiry' | 'cvv' | 'zip' | 'name';
+
 export declare type CardFormStatus = 'idle' | 'loading' | 'ready' | 'tokenizing' | 'saving' | 'error';
 
 export declare interface CardholderTokenizeData {
@@ -52,6 +54,18 @@ export declare interface CardholderTokenizeData {
     zip?: string;
 }
 
+/**
+ * PII-free validation snapshot: field KEYS only, never values. Lets a parent
+ * (e.g. `PaymentMethodsManager`) turn touched-invalid streaks into a
+ * consumer-side friction signal without the SDK importing an analytics
+ * library or leaking anything the traveler typed.
+ */
+export declare interface CardValidationState {
+    valid: boolean;
+    missing: CardFormField[];
+    touchedInvalid: CardFormField[];
+}
+
 /**
  * Builds an auth-aware `fetch` that the payments package (or any other
  * consumer that registers it via `setPaymentsConfig({ fetch })`) can call.
@@ -154,7 +168,7 @@ export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 /* Excluded from this release type: InternalPaymentsConfig */
 
 export declare const MovmoCardForm: {
-    ({ userId, onSuccess, onError, onErrorDetail, 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, onValidationChange, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -221,6 +235,14 @@ export declare interface MovmoCardFormProps {
      * accounts-ui add-card modal so the user can start typing immediately.
      */
     autoFocus?: 'number' | 'cvv';
+    /**
+     * Fires whenever the validation snapshot changes (missing fields or
+     * touched-invalid fields). PII-free by design — carries field KEYS only,
+     * never values — so a parent can turn a touched-invalid streak into an
+     * analytics-neutral friction event without the SDK importing an analytics
+     * library.
+     */
+    onValidationChange?: (state: CardValidationState) => void;
 }
 
 /**
@@ -256,6 +278,30 @@ export declare interface PaymentManagerError {
     cause?: unknown;
 }
 
+/**
+ * Payment-domain action reported by `PaymentMethodsManager`'s `onEvent`
+ * callback (MOVMO-479). Success-only — failures are covered by `onError`
+ * above. The package is analytics-agnostic: it never imports an analytics
+ * SDK, it just emits these action strings (plus PII-free props) for a
+ * consumer to map onto its own telemetry catalog.
+ *
+ * - `autoselected` — the manager auto-selected the default card on first load.
+ * - `selected`     — a genuine user row click (NOT the internal reselection
+ *                     fired after `added`/`deleted`).
+ * - `added`         — a new card was saved.
+ * - `edited`        — the cardholder/zip PUT succeeded.
+ * - `deleted`       — the delete request succeeded.
+ * - `set_default`   — the set-default PUT succeeded.
+ * - `validation_error` — a touched card-form field is invalid (fires once per
+ *                     invalid streak, not per keystroke). This is a friction
+ *                     signal, not a failure — it's the analytics-neutral
+ *                     counterpart to `onError`'s `card-tokenize` source, meant
+ *                     to surface which fields trip people up. Props are
+ *                     `field_count` and `fields` (touched-invalid field KEYS
+ *                     only, e.g. `'zip'` — never card values).
+ */
+export declare type PaymentMethodEvent = 'autoselected' | 'selected' | 'added' | 'edited' | 'deleted' | 'set_default' | 'validation_error';
+
 /**
  * Compact preview of a single saved card: brand icon + label. Used by
  * consumers (e.g. flights-ui's collapsed checkout drawer) to show the
@@ -288,7 +334,7 @@ export declare interface PaymentMethodPreviewProps {
 }
 
 export declare const PaymentMethodsManager: {
-    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, onError, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, className, }: PaymentMethodsManagerProps): JSX_2.Element;
+    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, onError, onEvent, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, className, }: PaymentMethodsManagerProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -319,6 +365,20 @@ export declare interface PaymentMethodsManagerProps {
      * gates. Additive and non-intrusive — errors are still rendered in-SDK.
      */
     onError?: (error: PaymentManagerError) => void;
+    /**
+     * Analytics-agnostic observability hook (MOVMO-479). Fires for successful
+     * payment-domain actions only — `onError` above already covers failures.
+     * The package never imports an analytics SDK; it just emits a
+     * `PaymentMethodEvent` action string plus PII-free props, and it's up to
+     * the consumer to map that to whatever telemetry system it uses (e.g.
+     * flights-ui's `@movmo_app/analytics` catalog). Fire points: `autoselected`
+     * (first-load default selection), `selected` (a genuine user row click —
+     * NOT the internal reselection after add/delete), `added`, `edited`
+     * (`fields` is key names only, never card values), `deleted`, and
+     * `set_default`. Kept referentially stable via a ref, same discipline as
+     * `onError`/`reportError`.
+     */
+    onEvent?: (action: PaymentMethodEvent, props?: Record<string, unknown>) => void;
     /**
      * Show the Credit card / PayPal / GooglePay / Klarna / ACH radios above
      * the card-capture form. Only Credit card is functional today; the others
@@ -384,7 +444,7 @@ export declare interface PaymentMethodSummary {
     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. */
+    /** Current billing postal code (MOVMO-381). Empty/absent for legacy rows. */
     zip?: string;
 }