@coinbase/cdp-core 0.0.107 → 0.0.108

package/dist/web-types/index.native.d.ts

@@ -48,7 +48,8 @@ export { submitMfaEnrollment, type SubmitMfaEnrollmentOptions, type SubmitMfaEnr
 export { initiateMfaVerification } from './actions/initiateMfaVerification.js';
 export { submitMfaVerification, type SubmitMfaVerificationOptions, } from './actions/submitMfaVerification.js';
 export { cancelMfaVerification } from './actions/cancelMfaVerification.js';
-export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, registerMfaListener, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaListenerOptions, type MfaVerificationContext, } from './mfa/index.js';
+export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaVerificationContext, } from './mfa/index.js';
+export { registerMfaListener, type MfaListenerOptions } from './mfa/state.js';
 export * from './auth/authManager.js';
 export * from './auth/types.js';
 export * from './types.js';

package/dist/web-types/index.web.d.ts

@@ -48,7 +48,8 @@ export { submitMfaEnrollment, type SubmitMfaEnrollmentOptions, type SubmitMfaEnr
 export { initiateMfaVerification } from './actions/initiateMfaVerification.js';
 export { submitMfaVerification, type SubmitMfaVerificationOptions, } from './actions/submitMfaVerification.js';
 export { cancelMfaVerification } from './actions/cancelMfaVerification.js';
-export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, registerMfaListener, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaListenerOptions, type MfaVerificationContext, } from './mfa/index.js';
+export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaVerificationContext, } from './mfa/index.js';
+export { registerMfaListener, type MfaListenerOptions } from './mfa/state.web.js';
 export * from './auth/authManager.js';
 export * from './auth/types.js';
 export * from './shared/types.js';

package/dist/web-types/mfa/index.d.ts

@@ -1,4 +1,4 @@
-export { hasPendingMfaVerification, registerMfaListener, resolvePendingMfaVerification, rejectPendingMfaVerification, triggerMfaVerification, type MfaListener, type MfaVerificationContext, type MfaListenerOptions, } from './state.js';
+export { hasPendingMfaVerification, resolvePendingMfaVerification, rejectPendingMfaVerification, triggerMfaVerification, type MfaListener, type MfaVerificationContext, } from './state.js';
 export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa } from './utils.js';
 export { withMfa, ensureMfaVerified, isMfaRequired } from './withMfa.js';
 export { MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, isMfaProtectedAction, type MfaProtectedAction, } from './protectedActions.js';

package/dist/web-types/mfa/state.d.ts

@@ -12,50 +12,66 @@ export type MfaVerificationContext = {
  */
 export type MfaListener = (context: MfaVerificationContext) => void;
 /**
- * Options for registering an MFA listener.
+ * Options for registering an MFA listener at the core layer.
+ *
+ * The core registry is platform-agnostic. The optional `matches` predicate
+ * lets a listener express "only fire when the trigger value satisfies this
+ * predicate." Platform adapters (e.g. the web adapter) layer their own
+ * scoping semantics on top of this opaque predicate.
  */
 export type MfaListenerOptions = {
     /**
-     * Optional DOM element that defines the scope for this handler.
-     * When provided, this handler will only respond to MFA triggers
-     * that originate from within this element (e.g., button clicks inside a container).
-     * Handlers without a scope act as global handlers.
+     * Optional predicate that gates this listener.
+     *
+     * When provided, the listener only fires when `triggerMfaVerification` is
+     * called with a `trigger` value (or a default trigger supplied by the
+     * platform) that satisfies the predicate. When omitted, the listener is
+     * a "global" listener that fires only when no predicate-based listener
+     * matched the trigger.
      */
-    scope?: HTMLElement;
+    matches?: (trigger: unknown) => boolean;
 };
 /**
- * Registers an MFA verification listener.
+ * Installs (or clears) the default trigger provider.
  *
- * Listeners can be global (no scope) or scoped to a specific DOM element.
- * The event bubbles up from the trigger element through the DOM:
- * - Scoped listeners listen on their container and catch events from within
- * - Global listeners listen on document and catch anything that bubbles up
+ * The web entry point uses this to expose `document.activeElement` as the
+ * default trigger so scoped listeners can match against it. Native entry
+ * points have no DOM and therefore install nothing.
  *
- * @param {MfaListener} listener - The listener function to call when MFA is required.
- * @param {MfaListenerOptions} [options] - Optional configuration including scope element.
- * @returns {() => void} A function to unregister the listener.
+ * @param provider - Function that returns the trigger value, or `null` to clear.
+ * @internal
+ */
+export declare const setDefaultTriggerProvider: (provider: (() => unknown) | null) => void;
+/**
+ * Registers an MFA verification listener.
+ *
+ * Listeners can be global (no `matches` predicate) or scoped via an opaque
+ * predicate. When `triggerMfaVerification` fires:
+ * - If any predicate-based listener matches the trigger, only those listeners
+ *   are invoked.
+ * - Otherwise, all global listeners are invoked.
  *
- * @example
- * ```typescript
- * // Global listener (responds to any MFA trigger not handled by a scoped listener)
- * const unregisterGlobal = registerMfaListener(({ methods }) => {
- *   openMfaModal(methods);
- * });
+ * Platform adapters wrap this function to provide their own scoping shape
+ * (e.g. a DOM `scope: HTMLElement` on web).
  *
- * // Scoped listener (only responds to triggers inside the container)
- * const container = document.getElementById('my-flow');
- * if (container) {
- *   const unregisterScoped = registerMfaListener(
- *     ({ methods }) => showInlineMfa(methods),
- *     { scope: container }
- *   );
- *   // Later, when done:
- *   unregisterScoped();
- * }
+ * Notes:
+ * - Matched suppresses globals. When any predicate-based listener matches,
+ *   all global (unscoped) listeners are skipped, including the app's own
+ *   default modal. This mirrors the previous DOM implementation's
+ *   stopPropagation semantics. Prefer narrow predicates; a permissive
+ *   `matches: () => true` silently suppresses every global listener.
+ * - Coordination, not authz. This registry is a UX coordination layer for
+ *   which listener shows the verification UI. The server still enforces MFA
+ *   via `mfa_required` regardless of which listener fires (or whether one
+ *   fires at all).
+ * - React Native: RN does not install a default trigger provider, so
+ *   `matches` is invoked with `undefined`. Predicates that don't accept
+ *   `undefined` will never match — most RN consumers should omit `matches`
+ *   entirely and register a global listener.
  *
- * // Clean up global listener when done:
- * unregisterGlobal();
- * ```
+ * @param {MfaListener} listener - The listener function to call when MFA is required.
+ * @param {MfaListenerOptions} [options] - Optional configuration with an opaque predicate.
+ * @returns {() => void} A function to unregister the listener.
  */
 export declare const registerMfaListener: (listener: MfaListener, options?: MfaListenerOptions) => (() => void);
 /**
@@ -68,18 +84,22 @@ export declare const hasRegisteredMfaListeners: () => boolean;
  * Triggers the MFA verification flow and returns a Promise that resolves
  * when MFA is successfully completed.
  *
- * Dispatches a custom DOM event from the trigger element that bubbles up.
- * Scoped handlers catch events from within their container.
- * Global handlers catch anything that bubbles to document.
+ * Selection rule:
+ * - All registered listeners with a `matches` predicate are evaluated against
+ *   the trigger (the explicit `trigger` argument, or the value returned by
+ *   the default trigger provider if one is installed).
+ * - If any predicate matches, only the matching listeners are invoked.
+ * - Otherwise, all listeners without a predicate (global listeners) are invoked.
  *
- * If no handlers are registered, this is a no-op and resolves immediately.
+ * If no listeners are registered, this is a no-op and resolves immediately.
  * Use `hasRegisteredMfaListeners()` to check before calling if needed.
  *
  * @param {MfaMethod[]} methods - The MFA methods available for verification.
+ * @param {unknown} [trigger] - Optional opaque trigger value used by listener predicates.
  * @returns {Promise<void>} A Promise that resolves when MFA is complete.
  * @internal
  */
-export declare const triggerMfaVerification: (methods: MfaMethod[]) => Promise<void>;
+export declare const triggerMfaVerification: (methods: MfaMethod[], trigger?: unknown) => Promise<void>;
 /**
  * Resolves the pending MFA verification Promise.
  * Called internally after successful MFA submission.

package/dist/web-types/mfa/state.web.d.ts

@@ -0,0 +1,62 @@
+import { MfaListener } from './state.js';
+/**
+ * Options for registering an MFA listener on web.
+ *
+ * Web-specific shape: when a `scope` element is provided, the listener only
+ * fires for MFA triggers that originate from inside that element (based on
+ * `document.activeElement` at trigger time, supplied by the web entry point's
+ * default trigger provider).
+ *
+ * Listeners without a scope act as global listeners.
+ */
+export type MfaListenerOptions = {
+    /**
+     * Optional DOM element that defines the scope for this handler.
+     * When provided, this handler only responds to MFA triggers that originate
+     * from within this element. Handlers without a scope act as global handlers.
+     */
+    scope?: HTMLElement;
+};
+/**
+ * Registers an MFA verification listener (web).
+ *
+ * The web adapter translates the DOM-shaped `scope` option into an opaque
+ * predicate against the trigger element supplied by the web entry point's
+ * default trigger provider (`document.activeElement` or `document.body`).
+ *
+ * Notes:
+ * - Matched suppresses globals. When any scoped listener's `scope` contains
+ *   the trigger, all global (unscoped) listeners are skipped, including the
+ *   app's own default modal. Mirrors the previous DOM implementation's
+ *   stopPropagation semantics.
+ * - Innermost wins. When multiple scoped listeners contain the trigger
+ *   (e.g. a page container scope and a nested per-flow scope), only the
+ *   deepest scope's listener fires. Mirrors DOM bubble order.
+ * - Shadow DOM. `Element.contains` does not cross shadow DOM boundaries.
+ *   A trigger inside an open shadow tree whose host is inside `scope` will
+ *   not match. Workaround: register a global listener.
+ * - Coordination, not authz. Same caveat as the core registry — the server
+ *   still enforces MFA via `mfa_required`.
+ *
+ * @param {MfaListener} listener - The listener function to call when MFA is required.
+ * @param {MfaListenerOptions} [options] - Optional configuration including a DOM scope element.
+ * @returns {() => void} A function to unregister the listener.
+ *
+ * @example
+ * ```typescript
+ * // Global listener (responds to any MFA trigger not handled by a scoped listener)
+ * const unregisterGlobal = registerMfaListener(({ methods }) => {
+ *   openMfaModal(methods);
+ * });
+ *
+ * // Scoped listener (only responds to triggers inside the container)
+ * const container = document.getElementById('my-flow');
+ * if (container) {
+ *   const unregisterScoped = registerMfaListener(
+ *     ({ methods }) => showInlineMfa(methods),
+ *     { scope: container }
+ *   );
+ * }
+ * ```
+ */
+export declare const registerMfaListener: (listener: MfaListener, options?: MfaListenerOptions) => (() => void);

package/dist/web-types/version.d.ts

@@ -2,4 +2,4 @@
  * Current version of @coinbase/cdp-core package.
  * This file is auto-generated by scripts/sync-versions.js
  */
-export declare const VERSION = "0.0.106";
+export declare const VERSION = "0.0.108";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-core",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "module",
   "files": [
     "dist/**",
@@ -29,7 +29,7 @@
     "ox": "0.8.1",
     "viem": "^2.47.0",
     "zustand": "^5.0.6",
-    "@coinbase/cdp-api-client": "^0.0.107"
+    "@coinbase/cdp-api-client": "^0.0.108"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^2.0.0",