@edge-markets/connect-link 1.0.3 → 1.3.0

package/dist/index.mjs

@@ -155,7 +155,7 @@ var PopupManager = class {
    * Renders a branded loading state in the popup.
    *
    * This shows immediately while we do async work (PKCE, URL building).
-   * Creates a polished, professional feel like Plaid Link.
+   * Creates a polished, professional feel for the authentication flow.
    */
   renderLoadingState() {
     if (!this.popup) return;
@@ -562,9 +562,601 @@ var EdgeLink = class {
   }
 };
 
+// src/hooks.ts
+import { useEffect, useRef, useCallback, useState } from "react";
+function useEdgeLink(config) {
+  const linkRef = useRef(null);
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const configRef = useRef(config);
+  configRef.current = config;
+  useEffect(() => {
+    try {
+      linkRef.current = new EdgeLink({
+        ...configRef.current,
+        onSuccess: (result) => {
+          setIsOpen(false);
+          configRef.current.onSuccess?.(result);
+        },
+        onExit: (metadata) => {
+          setIsOpen(false);
+          configRef.current.onExit?.(metadata);
+        },
+        onEvent: (event) => {
+          if (event.eventName === "OPEN") setIsOpen(true);
+          if (event.eventName === "CLOSE") setIsOpen(false);
+          configRef.current.onEvent?.(event);
+        }
+      });
+      setReady(true);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to initialize EdgeLink"));
+      setReady(false);
+    }
+    return () => {
+      linkRef.current?.destroy();
+      linkRef.current = null;
+      setReady(false);
+    };
+  }, [config.clientId, config.environment]);
+  const open = useCallback((options) => {
+    if (!linkRef.current) {
+      setError(new Error("EdgeLink not initialized"));
+      return;
+    }
+    try {
+      linkRef.current.open(options);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to open EdgeLink"));
+    }
+  }, []);
+  return { open, ready, error, isOpen };
+}
+
+// src/edge-transfer-verify.ts
+import {
+  EdgePopupBlockedError as EdgePopupBlockedError2
+} from "@edge-markets/connect";
+
+// src/iframe-manager.ts
+var DEFAULT_TITLE = "EDGE Connect Transfer Verification";
+var IFRAME_SANDBOX = "allow-scripts allow-same-origin allow-forms";
+var IframeManager = class {
+  constructor() {
+    this.iframe = null;
+    this.loadingEl = null;
+    this.container = null;
+    this.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, callbacks = {}) {
+    this.destroy();
+    this.container = config.container;
+    this.callbacks = callbacks;
+    this.renderLoadingState(config.container);
+    this.iframe = document.createElement("iframe");
+    this.iframe.src = config.url;
+    this.iframe.width = config.width || "100%";
+    this.iframe.height = config.height || "100%";
+    this.iframe.title = config.title || DEFAULT_TITLE;
+    this.iframe.setAttribute("sandbox", IFRAME_SANDBOX);
+    this.iframe.setAttribute("allow", "clipboard-write");
+    this.iframe.style.border = "none";
+    this.iframe.style.display = "none";
+    this.iframe.style.width = config.width || "100%";
+    this.iframe.style.height = config.height || "100%";
+    this.iframe.style.minHeight = "400px";
+    this.iframe.style.borderRadius = "8px";
+    this.iframe.addEventListener("load", () => {
+      this.hideLoadingState();
+      this.callbacks.onLoad?.();
+    });
+    this.iframe.addEventListener("error", () => {
+      this.hideLoadingState();
+      const error = new Error("Failed to load transfer verification iframe");
+      this.callbacks.onError?.(error);
+    });
+    config.container.appendChild(this.iframe);
+  }
+  /**
+   * Gets the iframe's content window for postMessage communication.
+   *
+   * @returns The iframe's contentWindow, or null if not mounted
+   */
+  getContentWindow() {
+    return this.iframe?.contentWindow ?? null;
+  }
+  /**
+   * Checks if the iframe is currently mounted in the DOM.
+   */
+  isMounted() {
+    return this.iframe !== null && this.iframe.isConnected;
+  }
+  /**
+   * Removes the iframe and loading state from the DOM.
+   * Cleans up all references for garbage collection.
+   */
+  destroy() {
+    if (this.loadingEl && this.loadingEl.parentNode) {
+      this.loadingEl.parentNode.removeChild(this.loadingEl);
+    }
+    this.loadingEl = null;
+    if (this.iframe && this.iframe.parentNode) {
+      this.iframe.parentNode.removeChild(this.iframe);
+    }
+    this.iframe = null;
+    this.container = null;
+    this.callbacks = {};
+  }
+  // ===========================================================================
+  // PRIVATE METHODS
+  // ===========================================================================
+  /**
+   * 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.
+   */
+  renderLoadingState(container) {
+    this.loadingEl = document.createElement("div");
+    this.loadingEl.setAttribute("data-edge-loading", "true");
+    this.loadingEl.innerHTML = `
+      <div style="
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 400px;
+        background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+        border-radius: 8px;
+        color: white;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      ">
+        <div style="text-align: center; padding: 40px;">
+          <div style="
+            width: 64px;
+            height: 64px;
+            margin: 0 auto 24px;
+            background: linear-gradient(135deg, #00d4aa 0%, #00a080 100%);
+            border-radius: 16px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 28px;
+            font-weight: bold;
+            box-shadow: 0 8px 32px rgba(0, 212, 170, 0.3);
+          ">E</div>
+          <div style="
+            width: 40px;
+            height: 40px;
+            border: 3px solid rgba(255, 255, 255, 0.2);
+            border-top-color: #00d4aa;
+            border-radius: 50%;
+            animation: edge-spin 1s linear infinite;
+            margin: 0 auto 24px;
+          "></div>
+          <h1 style="
+            font-size: 22px;
+            font-weight: 600;
+            margin-bottom: 8px;
+            letter-spacing: -0.5px;
+          ">Transfer Verification</h1>
+          <p style="
+            font-size: 15px;
+            color: rgba(255, 255, 255, 0.7);
+            line-height: 1.5;
+          ">Loading secure verification...</p>
+          <div style="
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 6px;
+            margin-top: 32px;
+            font-size: 13px;
+            color: rgba(255, 255, 255, 0.5);
+          ">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
+              <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
+            </svg>
+            <span>256-bit encryption</span>
+          </div>
+        </div>
+      </div>
+      <style>
+        @keyframes edge-spin {
+          to { transform: rotate(360deg); }
+        }
+      </style>
+    `;
+    container.appendChild(this.loadingEl);
+  }
+  /**
+   * Hides the loading state and shows the iframe.
+   */
+  hideLoadingState() {
+    if (this.loadingEl && this.loadingEl.parentNode) {
+      this.loadingEl.parentNode.removeChild(this.loadingEl);
+      this.loadingEl = null;
+    }
+    if (this.iframe) {
+      this.iframe.style.display = "block";
+    }
+  }
+};
+
+// src/edge-transfer-verify.ts
+function generateNonce() {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function isValidTransferVerifyMessage(data) {
+  if (!data || typeof data !== "object") return false;
+  const msg = data;
+  const validTypes = [
+    "edge:transfer-verify:success",
+    "edge:transfer-verify:error",
+    "edge:transfer-verify:cancel",
+    "edge:transfer-verify:expired",
+    "edge:transfer-verify:loaded"
+  ];
+  if (typeof msg.type !== "string" || !validTypes.includes(msg.type)) {
+    return false;
+  }
+  if (typeof msg.sessionId !== "string" || msg.sessionId.length === 0) return false;
+  if (typeof msg.transferId !== "string" || msg.transferId.length === 0) return false;
+  if (typeof msg.nonce !== "string" || msg.nonce.length === 0) return false;
+  if (typeof msg.timestamp !== "string" || msg.timestamp.length === 0) return false;
+  if (msg.error !== void 0 && typeof msg.error !== "string") return false;
+  return true;
+}
+var EdgeTransferVerify = class {
+  /**
+   * Creates a new EdgeTransferVerify instance.
+   *
+   * @param config - Configuration options
+   * @throws Error if required config is missing or invalid
+   */
+  constructor(config) {
+    this.popupManager = null;
+    this.iframeManager = null;
+    this.messageHandler = null;
+    this.isDestroyed = false;
+    this.isOpened = false;
+    if (!config.verificationUrl) {
+      throw new Error("EdgeTransferVerify: verificationUrl is required");
+    }
+    if (!config.sessionId) {
+      throw new Error("EdgeTransferVerify: sessionId is required");
+    }
+    const mode = config.mode || "iframe";
+    if (mode === "iframe" && !config.container) {
+      throw new Error("EdgeTransferVerify: container is required for iframe mode");
+    }
+    this.config = config;
+    this.mode = mode;
+    this.nonce = config.nonce || generateNonce();
+    this.expectedOrigin = new URL(config.verificationUrl).origin;
+    this.setupMessageListener();
+  }
+  // ===========================================================================
+  // PUBLIC API
+  // ===========================================================================
+  /**
+   * 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() {
+    if (this.isDestroyed) {
+      throw new Error("EdgeTransferVerify: Cannot open - instance has been destroyed");
+    }
+    if (this.isOpened) {
+      if (this.mode === "popup" && this.popupManager?.isOpen()) {
+        this.popupManager.focus();
+        return;
+      }
+      if (this.mode === "iframe" && this.iframeManager?.isMounted()) {
+        return;
+      }
+    }
+    const url = this.buildVerificationUrl();
+    if (this.mode === "popup") {
+      this.openPopup(url);
+    } else {
+      this.openIframe(url);
+    }
+    this.isOpened = true;
+  }
+  /**
+   * 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() {
+    if (this.mode === "popup") {
+      this.popupManager?.close();
+      this.popupManager = null;
+    } else {
+      this.iframeManager?.destroy();
+      this.iframeManager = null;
+    }
+    this.isOpened = false;
+  }
+  /**
+   * 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() {
+    this.isDestroyed = true;
+    this.close();
+    this.removeMessageListener();
+  }
+  /**
+   * Checks if the verification UI is currently displayed.
+   */
+  isOpen() {
+    if (this.mode === "popup") {
+      return this.popupManager?.isOpen() ?? false;
+    }
+    return this.iframeManager?.isMounted() ?? false;
+  }
+  /**
+   * Returns the nonce being used for this verification session.
+   * Useful for debugging and logging.
+   */
+  getNonce() {
+    return this.nonce;
+  }
+  // ===========================================================================
+  // PRIVATE — LAUNCH METHODS
+  // ===========================================================================
+  /**
+   * 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
+   */
+  buildVerificationUrl() {
+    const url = new URL(this.config.verificationUrl);
+    url.searchParams.set("nonce", this.nonce);
+    url.searchParams.set("origin", window.location.origin);
+    return url.toString();
+  }
+  /**
+   * 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
+   */
+  openPopup(url) {
+    this.popupManager = new PopupManager();
+    const win = this.popupManager.open({
+      onUserClose: () => this.handleUserClose()
+    });
+    if (!win) {
+      this.popupManager = null;
+      this.config.onError?.({
+        type: "edge:transfer-verify:error",
+        sessionId: this.config.sessionId,
+        transferId: "",
+        nonce: this.nonce,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        error: "Popup was blocked by the browser. Please allow popups for this site."
+      });
+      throw new EdgePopupBlockedError2();
+    }
+    this.popupManager.navigateTo(url);
+  }
+  /**
+   * 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
+   */
+  openIframe(url) {
+    this.iframeManager = new IframeManager();
+    this.iframeManager.mount(
+      {
+        url,
+        container: this.config.container,
+        title: "EDGE Connect Transfer Verification"
+      },
+      {
+        onError: (error) => {
+          this.config.onError?.({
+            type: "edge:transfer-verify:error",
+            sessionId: this.config.sessionId,
+            transferId: "",
+            nonce: this.nonce,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            error: error.message
+          });
+        }
+      }
+    );
+  }
+  // ===========================================================================
+  // PRIVATE — MESSAGE HANDLING
+  // ===========================================================================
+  /**
+   * 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
+   */
+  setupMessageListener() {
+    this.messageHandler = (event) => {
+      if (event.origin !== this.expectedOrigin) {
+        return;
+      }
+      const data = event.data;
+      if (!isValidTransferVerifyMessage(data)) {
+        return;
+      }
+      if (data.nonce !== this.nonce) {
+        return;
+      }
+      if (data.sessionId !== this.config.sessionId) {
+        return;
+      }
+      const verifiedEvent = {
+        type: data.type,
+        sessionId: data.sessionId,
+        transferId: data.transferId,
+        nonce: data.nonce,
+        timestamp: data.timestamp,
+        error: data.error
+      };
+      this.config.onEvent?.(verifiedEvent);
+      switch (data.type) {
+        case "edge:transfer-verify:success":
+          this.handleSuccess(verifiedEvent);
+          break;
+        case "edge:transfer-verify:error":
+          this.handleError(verifiedEvent);
+          break;
+        case "edge:transfer-verify:cancel":
+          this.handleCancel(verifiedEvent);
+          break;
+        case "edge:transfer-verify:expired":
+          this.handleExpired(verifiedEvent);
+          break;
+        case "edge:transfer-verify:loaded":
+          this.handleLoaded(verifiedEvent);
+          break;
+      }
+    };
+    window.addEventListener("message", this.messageHandler);
+  }
+  /**
+   * Removes the postMessage listener.
+   */
+  removeMessageListener() {
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+  }
+  // ===========================================================================
+  // PRIVATE — EVENT HANDLERS
+  // ===========================================================================
+  /**
+   * Handles a successful verification event.
+   *
+   * Closes the UI and notifies the consumer.
+   */
+  handleSuccess(event) {
+    this.close();
+    this.config.onSuccess?.(event);
+  }
+  /**
+   * 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.
+   */
+  handleError(event) {
+    this.config.onError?.(event);
+  }
+  /**
+   * Handles a cancellation event from the user.
+   *
+   * Closes the UI and notifies the consumer.
+   */
+  handleCancel(event) {
+    this.close();
+    this.config.onCancel?.(event);
+  }
+  /**
+   * Handles a session/OTP expiration event.
+   *
+   * Closes the UI and notifies the consumer.
+   */
+  handleExpired(event) {
+    this.close();
+    this.config.onExpired?.(event);
+  }
+  /**
+   * Handles the loaded event from the verification page.
+   *
+   * The verification UI is ready for user interaction.
+   */
+  handleLoaded(event) {
+    this.config.onLoaded?.(event);
+  }
+  /**
+   * Handles user closing the popup manually (popup mode only).
+   *
+   * Treated as a cancellation — we fire onCancel with a synthetic event.
+   */
+  handleUserClose() {
+    this.isOpened = false;
+    this.popupManager = null;
+    const syntheticEvent = {
+      type: "edge:transfer-verify:cancel",
+      sessionId: this.config.sessionId,
+      transferId: "",
+      nonce: this.nonce,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.config.onEvent?.(syntheticEvent);
+    this.config.onCancel?.(syntheticEvent);
+  }
+};
+
 // src/index.ts
 import {
-  EdgePopupBlockedError as EdgePopupBlockedError2,
+  EdgePopupBlockedError as EdgePopupBlockedError3,
   EdgeStateMismatchError as EdgeStateMismatchError2,
   EdgeError,
   isEdgeError
@@ -578,10 +1170,13 @@ export {
   EDGE_SCOPES,
   EdgeError,
   EdgeLink,
-  EdgePopupBlockedError2 as EdgePopupBlockedError,
+  EdgePopupBlockedError3 as EdgePopupBlockedError,
   EdgeStateMismatchError2 as EdgeStateMismatchError,
+  EdgeTransferVerify,
+  IframeManager,
   assertCryptoAvailable,
   generatePKCE,
   generateState,
-  isEdgeError
+  isEdgeError,
+  useEdgeLink
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-link",
-  "version": "1.0.3",
+  "version": "1.3.0",
   "description": "Browser SDK for EDGE Connect popup authentication",
   "author": "EdgeBoost",
   "license": "MIT",
@@ -20,17 +20,19 @@
       }
     }
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --passWithNoTests",
-    "test:run": "vitest run --passWithNoTests"
-  },
   "dependencies": {
-    "@edge-markets/connect": "^1.0.0"
+    "@edge-markets/connect": "1.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@types/react": "^18.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
@@ -46,7 +48,8 @@
     "oauth",
     "popup",
     "browser",
-    "fintech"
+    "fintech",
+    "react"
   ],
   "repository": {
     "type": "git",
@@ -56,7 +59,12 @@
   "engines": {
     "node": ">=18"
   },
-  "browser": "./dist/index.mjs"
-}
-
-
+  "browser": "./dist/index.mjs",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}