@edge-markets/connect-link 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { EdgeEnvironment, EdgeLinkSuccess, EdgeLinkExit, EdgeScope } from '@edge-markets/connect';
-export { ALL_EDGE_SCOPES, EDGE_SCOPES, EdgeEnvironment, EdgeError, EdgeLinkExit, EdgeLinkSuccess, EdgePopupBlockedError, EdgeScope, EdgeStateMismatchError, isEdgeError } from '@edge-markets/connect';
+import { EdgeLinkConfigBase, EdgeScope, EdgeLinkSuccess, EdgeLinkExit, PKCEPair } from '@edge-markets/connect';
+export { ALL_EDGE_SCOPES, EDGE_SCOPES, EdgeEnvironment, EdgeError, EdgeLinkEvent, EdgeLinkEventName, EdgeLinkExit, EdgeLinkSuccess, EdgePopupBlockedError, EdgeScope, EdgeStateMismatchError, PKCEPair, isEdgeError } from '@edge-markets/connect';
 
 /**
  * EdgeLink - Popup Authentication for EDGE Connect
@@ -51,99 +51,7 @@ export { ALL_EDGE_SCOPES, EDGE_SCOPES, EdgeEnvironment, EdgeError, EdgeLinkExit,
  * Only `clientId`, `environment`, and `onSuccess` are required.
  * Everything else has sensible defaults.
  */
-interface EdgeLinkConfig {
-    /**
-     * Your OAuth client ID from the EdgeBoost partner portal.
-     * This is public and safe to include in frontend code.
-     */
-    clientId: string;
-    /**
-     * Environment to connect to.
-     * - `'production'` - Live environment with real money
-     * - `'staging'` - Test environment for development
-     * - `'sandbox'` - Isolated mock environment (coming soon)
-     */
-    environment: EdgeEnvironment;
-    /**
-     * Called when user successfully authenticates and grants consent.
-     *
-     * Send the `code` and `codeVerifier` to your backend for token exchange.
-     * **Never exchange tokens in the frontend** - that would expose your client secret.
-     *
-     * @example
-     * ```typescript
-     * onSuccess: async (result) => {
-     *   const response = await fetch('/api/edge/exchange', {
-     *     method: 'POST',
-     *     headers: { 'Content-Type': 'application/json' },
-     *     body: JSON.stringify({
-     *       code: result.code,
-     *       codeVerifier: result.codeVerifier,
-     *     }),
-     *   })
-     *   if (response.ok) {
-     *     showSuccess('EdgeBoost connected!')
-     *   }
-     * }
-     * ```
-     */
-    onSuccess: (result: EdgeLinkSuccess) => void;
-    /**
-     * Called when user exits the Link flow (closes popup, error, etc.).
-     *
-     * Use this to handle errors and provide user feedback.
-     *
-     * @example
-     * ```typescript
-     * onExit: (metadata) => {
-     *   switch (metadata.reason) {
-     *     case 'user_closed':
-     *       // User closed popup - maybe show "Connect later" option
-     *       break
-     *     case 'popup_blocked':
-     *       showMessage('Please allow popups and try again')
-     *       break
-     *     case 'error':
-     *       showError(metadata.error?.message || 'Something went wrong')
-     *       break
-     *   }
-     * }
-     * ```
-     */
-    onExit?: (metadata: EdgeLinkExit) => void;
-    /**
-     * Called for various events during the Link flow.
-     * Useful for analytics and debugging.
-     *
-     * @example
-     * ```typescript
-     * onEvent: (event) => {
-     *   analytics.track('edge_link_event', {
-     *     eventName: event.eventName,
-     *     timestamp: event.timestamp,
-     *   })
-     * }
-     * ```
-     */
-    onEvent?: (event: EdgeLinkEvent) => void;
-    /**
-     * OAuth scopes to request.
-     * @default All available scopes
-     *
-     * @example
-     * ```typescript
-     * // Request only what you need
-     * scopes: ['user.read', 'balance.read']
-     * ```
-     */
-    scopes?: EdgeScope[];
-    /**
-     * Custom URL for the Link page.
-     * Only use for local development.
-     *
-     * @default Derived from environment config
-     */
-    linkUrl?: string;
+interface EdgeLinkConfig extends EdgeLinkConfigBase {
     /**
      * Custom redirect URI after authentication.
      * Must be registered in your OAuth client settings.
@@ -152,21 +60,6 @@ interface EdgeLinkConfig {
      */
     redirectUri?: string;
 }
-/**
- * Event emitted during the Link flow.
- */
-interface EdgeLinkEvent {
-    /** Name of the event */
-    eventName: EdgeLinkEventName;
-    /** Unix timestamp when event occurred */
-    timestamp: number;
-    /** Additional event-specific data */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Possible Link events.
- */
-type EdgeLinkEventName = 'OPEN' | 'CLOSE' | 'HANDOFF' | 'TRANSITION' | 'ERROR' | 'SUCCESS';
 /**
  * Options for opening Link.
  */
@@ -317,6 +210,514 @@ interface UseEdgeLinkReturn {
 }
 declare function useEdgeLink(config: UseEdgeLinkConfig): UseEdgeLinkReturn;
 
+/**
+ * EdgeTransferVerify - Transfer Verification Launcher for EDGE Connect
+ *
+ * EdgeTransferVerify provides a simple, reliable way to verify transfers
+ * using either an embedded iframe or a popup window. It mirrors the EdgeLink
+ * ergonomics but is purpose-built for the post-auth transfer verification flow.
+ *
+ * **Key Features:**
+ * - Callback-based API (onSuccess, onError, onCancel, onExpired, onLoaded, onEvent)
+ * - Supports both iframe (default) and popup display modes
+ * - Cross-origin communication via postMessage with strict origin validation
+ * - Nonce correlation to prevent replay attacks
+ * - Automatic cleanup on destroy
+ *
+ * @module @edge-markets/connect-link
+ *
+ * @example
+ * ```typescript
+ * import { EdgeTransferVerify } from '@edge-markets/connect-link'
+ *
+ * const verify = new EdgeTransferVerify({
+ *   verificationUrl: session.verificationUrl,
+ *   sessionId: session.sessionId,
+ *   mode: 'iframe',
+ *   container: document.getElementById('verify-container')!,
+ *   onSuccess: (event) => {
+ *     console.log(`Transfer ${event.transferId} verified!`)
+ *   },
+ *   onError: (event) => {
+ *     console.error(`Verification failed: ${event.error}`)
+ *   },
+ *   onCancel: (event) => {
+ *     console.log('User cancelled verification')
+ *   },
+ * })
+ *
+ * // Launch the verification UI
+ * verify.open()
+ *
+ * // Clean up when done
+ * verify.destroy()
+ * ```
+ */
+/**
+ * Event types emitted during the transfer verification flow.
+ *
+ * The verification page posts these message types back to the parent window:
+ * - `success` - User completed verification (OTP accepted)
+ * - `error` - Verification failed (invalid OTP, server error, etc.)
+ * - `cancel` - User cancelled the verification flow
+ * - `expired` - Verification session or OTP expired
+ * - `loaded` - Verification UI finished loading and is ready
+ */
+type TransferVerifyEventType = 'edge:transfer-verify:success' | 'edge:transfer-verify:error' | 'edge:transfer-verify:cancel' | 'edge:transfer-verify:expired' | 'edge:transfer-verify:loaded';
+/**
+ * Event emitted from the transfer verification UI via postMessage.
+ *
+ * All events include the sessionId, transferId, and nonce for correlation.
+ * Error events also include an `error` string with a description.
+ */
+interface TransferVerifyEvent {
+    /** The type of verification event */
+    type: TransferVerifyEventType;
+    /** The verification session ID */
+    sessionId: string;
+    /** The transfer ID being verified */
+    transferId: string;
+    /** Nonce for replay protection — must match the value sent at launch */
+    nonce: string;
+    /** ISO 8601 timestamp of when the event was generated */
+    timestamp: string;
+    /** Error description (only present on error events) */
+    error?: string;
+}
+/**
+ * Display mode for the verification UI.
+ *
+ * - `'iframe'` (default) — Embeds verification inline within a container element.
+ *   Best for desktop flows where you want the verification to appear seamlessly
+ *   within your page layout.
+ *
+ * - `'popup'` — Opens verification in a popup window.
+ *   Useful when you want a modal-like experience or when there's no suitable
+ *   container element. Must be called from a user click handler.
+ */
+type TransferVerifyMode = 'iframe' | 'popup';
+/**
+ * Configuration for EdgeTransferVerify.
+ *
+ * `verificationUrl` and `sessionId` are required. Everything else has sensible defaults.
+ */
+interface EdgeTransferVerifyConfig {
+    /**
+     * The URL for the verification page.
+     * Obtained from the `createVerificationSession` API response.
+     */
+    verificationUrl: string;
+    /**
+     * The verification session ID.
+     * Obtained from the `createVerificationSession` API response.
+     */
+    sessionId: string;
+    /**
+     * Optional nonce for replay protection.
+     * If not provided, a cryptographically random nonce is generated automatically.
+     * The nonce is appended to the verification URL and validated on all incoming messages.
+     */
+    nonce?: string;
+    /**
+     * Display mode for the verification UI.
+     * @default 'iframe'
+     */
+    mode?: TransferVerifyMode;
+    /**
+     * Container element for iframe mode.
+     * **Required** when `mode` is `'iframe'` (or when mode is omitted, since iframe is the default).
+     * The iframe will be appended as a child of this element.
+     *
+     * @example
+     * ```typescript
+     * container: document.getElementById('verify-container')!
+     * ```
+     */
+    container?: HTMLElement;
+    /**
+     * Called when transfer verification succeeds.
+     *
+     * The transfer has been verified — you can now poll the transfer status API
+     * to confirm completion on your backend.
+     *
+     * @example
+     * ```typescript
+     * onSuccess: (event) => {
+     *   console.log(`Transfer ${event.transferId} verified at ${event.timestamp}`)
+     *   pollTransferStatus(event.transferId)
+     * }
+     * ```
+     */
+    onSuccess?: (event: TransferVerifyEvent) => void;
+    /**
+     * Called when verification fails.
+     *
+     * Check `event.error` for the reason (invalid OTP, server error, etc.).
+     *
+     * @example
+     * ```typescript
+     * onError: (event) => {
+     *   showError(`Verification failed: ${event.error}`)
+     * }
+     * ```
+     */
+    onError?: (event: TransferVerifyEvent) => void;
+    /**
+     * Called when the user cancels the verification flow.
+     *
+     * @example
+     * ```typescript
+     * onCancel: (event) => {
+     *   showMessage('Verification was cancelled')
+     * }
+     * ```
+     */
+    onCancel?: (event: TransferVerifyEvent) => void;
+    /**
+     * Called when the verification session or OTP expires.
+     *
+     * You may want to create a new verification session and retry.
+     *
+     * @example
+     * ```typescript
+     * onExpired: (event) => {
+     *   showMessage('Verification expired — please try again')
+     *   createNewSession()
+     * }
+     * ```
+     */
+    onExpired?: (event: TransferVerifyEvent) => void;
+    /**
+     * Called when the verification UI has finished loading and is ready.
+     *
+     * Useful for hiding your own loading indicators.
+     *
+     * @example
+     * ```typescript
+     * onLoaded: () => {
+     *   hideSpinner()
+     * }
+     * ```
+     */
+    onLoaded?: (event: TransferVerifyEvent) => void;
+    /**
+     * Called for ALL verification events.
+     * Useful for analytics, logging, and debugging.
+     *
+     * This fires in addition to the specific callbacks above.
+     *
+     * @example
+     * ```typescript
+     * onEvent: (event) => {
+     *   analytics.track('transfer_verify_event', {
+     *     type: event.type,
+     *     sessionId: event.sessionId,
+     *     timestamp: event.timestamp,
+     *   })
+     * }
+     * ```
+     */
+    onEvent?: (event: TransferVerifyEvent) => void;
+}
+/**
+ * EdgeTransferVerify - Transfer verification launcher for EDGE Connect.
+ *
+ * Create one instance per verification session. Call `open()` to launch the
+ * verification UI. Call `destroy()` when done or when unmounting.
+ *
+ * @example
+ * ```typescript
+ * // Iframe mode (default) — embedded in your page
+ * const verify = new EdgeTransferVerify({
+ *   verificationUrl: session.verificationUrl,
+ *   sessionId: session.sessionId,
+ *   container: document.getElementById('verify-container')!,
+ *   onSuccess: (event) => {
+ *     console.log(`Transfer ${event.transferId} verified!`)
+ *   },
+ *   onError: (event) => {
+ *     console.error(`Verification failed: ${event.error}`)
+ *   },
+ * })
+ *
+ * verify.open()
+ *
+ * // Popup mode — opens in a new window
+ * const verify = new EdgeTransferVerify({
+ *   verificationUrl: session.verificationUrl,
+ *   sessionId: session.sessionId,
+ *   mode: 'popup',
+ *   onSuccess: handleSuccess,
+ * })
+ *
+ * // Must be called from a click handler for popup mode
+ * button.onclick = () => verify.open()
+ *
+ * // Clean up
+ * verify.destroy()
+ * ```
+ */
+declare class EdgeTransferVerify {
+    private readonly config;
+    private readonly nonce;
+    private readonly expectedOrigin;
+    private readonly mode;
+    private popupManager;
+    private iframeManager;
+    private messageHandler;
+    private isDestroyed;
+    private isOpened;
+    /**
+     * Creates a new EdgeTransferVerify instance.
+     *
+     * @param config - Configuration options
+     * @throws Error if required config is missing or invalid
+     */
+    constructor(config: EdgeTransferVerifyConfig);
+    /**
+     * Opens the transfer verification UI.
+     *
+     * In iframe mode, this mounts the iframe into the configured container.
+     * In popup mode, this opens a popup window.
+     *
+     * **Popup mode MUST be called directly from a user click handler!**
+     * Iframe mode can be called from any context.
+     *
+     * @throws EdgePopupBlockedError if popup mode and popup is blocked
+     * @throws Error if the instance has been destroyed or is already open
+     *
+     * @example
+     * ```typescript
+     * // Iframe mode — can call anywhere
+     * verify.open()
+     *
+     * // Popup mode — must call from click handler
+     * button.onclick = () => verify.open()
+     * ```
+     */
+    open(): void;
+    /**
+     * Closes the verification UI.
+     *
+     * In popup mode, closes the popup window.
+     * In iframe mode, removes the iframe from the container.
+     * Does not trigger any callbacks.
+     */
+    close(): void;
+    /**
+     * Destroys the EdgeTransferVerify instance.
+     *
+     * Closes the UI, removes the postMessage listener, and cleans up all resources.
+     * After destroy(), the instance cannot be reused.
+     *
+     * @example
+     * ```typescript
+     * // React cleanup
+     * useEffect(() => {
+     *   const verify = new EdgeTransferVerify({ ... })
+     *   verify.open()
+     *   return () => verify.destroy()
+     * }, [])
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Checks if the verification UI is currently displayed.
+     */
+    isOpen(): boolean;
+    /**
+     * Returns the nonce being used for this verification session.
+     * Useful for debugging and logging.
+     */
+    getNonce(): string;
+    /**
+     * Builds the verification URL with nonce and parent origin parameters.
+     *
+     * Appends:
+     * - `nonce` — for replay protection / message correlation
+     * - `origin` — so the verification page knows where to postMessage back to
+     */
+    private buildVerificationUrl;
+    /**
+     * Opens the verification UI in a popup window.
+     *
+     * Uses PopupManager from the existing EdgeLink infrastructure.
+     * The popup opens immediately (preserving user gesture) and navigates
+     * to the verification URL.
+     *
+     * @param url - The verification URL to load
+     * @throws EdgePopupBlockedError if the popup is blocked
+     */
+    private openPopup;
+    /**
+     * Opens the verification UI in an iframe.
+     *
+     * Uses IframeManager to create and mount the iframe into the configured container.
+     *
+     * @param url - The verification URL to load
+     */
+    private openIframe;
+    /**
+     * Sets up the postMessage listener for receiving events from the verification page.
+     *
+     * SECURITY: Every incoming message is validated for:
+     * 1. Origin matches the expected EDGE verification origin
+     * 2. Message schema matches TransferVerifyMessage
+     * 3. Nonce matches the nonce we sent
+     * 4. SessionId matches the session we opened
+     */
+    private setupMessageListener;
+    /**
+     * Removes the postMessage listener.
+     */
+    private removeMessageListener;
+    /**
+     * Handles a successful verification event.
+     *
+     * Closes the UI and notifies the consumer.
+     */
+    private handleSuccess;
+    /**
+     * Handles a verification error event.
+     *
+     * Does NOT close the UI — the verification page may allow retry.
+     * The consumer can call close() or destroy() if they want to dismiss.
+     */
+    private handleError;
+    /**
+     * Handles a cancellation event from the user.
+     *
+     * Closes the UI and notifies the consumer.
+     */
+    private handleCancel;
+    /**
+     * Handles a session/OTP expiration event.
+     *
+     * Closes the UI and notifies the consumer.
+     */
+    private handleExpired;
+    /**
+     * Handles the loaded event from the verification page.
+     *
+     * The verification UI is ready for user interaction.
+     */
+    private handleLoaded;
+    /**
+     * Handles user closing the popup manually (popup mode only).
+     *
+     * Treated as a cancellation — we fire onCancel with a synthetic event.
+     */
+    private handleUserClose;
+}
+
+/**
+ * Iframe Manager
+ *
+ * Manages an embedded iframe for EDGE Connect transfer verification.
+ * This is the iframe counterpart to PopupManager — it creates, configures,
+ * and cleans up an iframe element within a provided container.
+ *
+ * **Why iframe for verification?**
+ * Unlike authentication (which uses a popup to avoid phishing), transfer
+ * verification is a post-auth flow that benefits from inline embedding:
+ * - No popup blockers
+ * - Better mobile experience
+ * - Feels native to the partner's UI
+ *
+ * @module @edge-markets/connect-link/iframe-manager
+ */
+/**
+ * Configuration for the iframe element.
+ */
+interface IframeConfig {
+    /** URL to load in the iframe */
+    url: string;
+    /** Container element to append the iframe to */
+    container: HTMLElement;
+    /** Width of the iframe (default: '100%') */
+    width?: string;
+    /** Height of the iframe (default: '100%') */
+    height?: string;
+    /** Title for accessibility (screen readers) */
+    title?: string;
+}
+/**
+ * Callbacks for iframe lifecycle events.
+ */
+interface IframeCallbacks {
+    /** Called when the iframe finishes loading */
+    onLoad?: () => void;
+    /** Called if the iframe fails to load */
+    onError?: (error: Error) => void;
+}
+/**
+ * Manages the EDGE Connect transfer verification iframe.
+ *
+ * Handles:
+ * - Creating and configuring the iframe element
+ * - Rendering a loading state while the iframe loads
+ * - Clean removal of DOM elements on destroy
+ * - Sandbox permissions for security
+ *
+ * @example
+ * ```typescript
+ * const manager = new IframeManager()
+ *
+ * manager.mount({
+ *   url: verificationUrl,
+ *   container: document.getElementById('verify-container')!,
+ * }, {
+ *   onLoad: () => console.log('Verification UI ready'),
+ *   onError: (err) => console.error('Failed to load:', err),
+ * })
+ *
+ * // Later, clean up
+ * manager.destroy()
+ * ```
+ */
+declare class IframeManager {
+    private iframe;
+    private loadingEl;
+    private container;
+    private callbacks;
+    /**
+     * Creates and mounts the iframe into the provided container.
+     *
+     * Displays a branded loading state while the iframe loads,
+     * then swaps to the iframe once it's ready.
+     *
+     * @param config - Iframe configuration
+     * @param callbacks - Optional lifecycle callbacks
+     */
+    mount(config: IframeConfig, callbacks?: IframeCallbacks): void;
+    /**
+     * Gets the iframe's content window for postMessage communication.
+     *
+     * @returns The iframe's contentWindow, or null if not mounted
+     */
+    getContentWindow(): WindowProxy | null;
+    /**
+     * Checks if the iframe is currently mounted in the DOM.
+     */
+    isMounted(): boolean;
+    /**
+     * Removes the iframe and loading state from the DOM.
+     * Cleans up all references for garbage collection.
+     */
+    destroy(): void;
+    /**
+     * Renders a branded loading state in the container.
+     *
+     * This displays immediately while the iframe loads the verification URL.
+     * Matches the visual style of the PopupManager loading state.
+     */
+    private renderLoadingState;
+    /**
+     * Hides the loading state and shows the iframe.
+     */
+    private hideLoadingState;
+}
+
 /**
  * PKCE (Proof Key for Code Exchange) Utilities
  *
@@ -335,24 +736,7 @@ declare function useEdgeLink(config: UseEdgeLinkConfig): UseEdgeLinkReturn;
  *
  * @module @edge-markets/connect-link/pkce
  */
-/**
- * A PKCE code verifier and challenge pair.
- *
- * Keep the `verifier` secret until token exchange.
- * Send the `challenge` in the authorization URL.
- */
-interface PKCEPair {
-    /**
-     * High-entropy random string (43-128 characters).
-     * Keep this secret - only send during token exchange.
-     */
-    verifier: string;
-    /**
-     * SHA-256 hash of verifier, base64url encoded.
-     * This is public - include in authorization URL.
-     */
-    challenge: string;
-}
+
 /**
  * Generates a PKCE code verifier and challenge pair.
  *
@@ -418,4 +802,4 @@ declare function generateState(): string;
  */
 declare function assertCryptoAvailable(): void;
 
-export { EdgeLink, type EdgeLinkConfig, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkOpenOptions, type PKCEPair, type UseEdgeLinkConfig, type UseEdgeLinkReturn, assertCryptoAvailable, generatePKCE, generateState, useEdgeLink };
+export { EdgeLink, type EdgeLinkConfig, type EdgeLinkOpenOptions, EdgeTransferVerify, type EdgeTransferVerifyConfig, type IframeCallbacks, type IframeConfig, IframeManager, type TransferVerifyEvent, type TransferVerifyEventType, type TransferVerifyMode, type UseEdgeLinkConfig, type UseEdgeLinkReturn, assertCryptoAvailable, generatePKCE, generateState, useEdgeLink };