@edge-markets/connect-link 1.0.0

package/dist/index.js

@@ -0,0 +1,609 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ALL_EDGE_SCOPES: () => import_connect3.ALL_EDGE_SCOPES,
+  EDGE_SCOPES: () => import_connect3.EDGE_SCOPES,
+  EdgeError: () => import_connect2.EdgeError,
+  EdgeLink: () => EdgeLink,
+  EdgePopupBlockedError: () => import_connect2.EdgePopupBlockedError,
+  EdgeStateMismatchError: () => import_connect2.EdgeStateMismatchError,
+  assertCryptoAvailable: () => assertCryptoAvailable,
+  generatePKCE: () => generatePKCE,
+  generateState: () => generateState,
+  isEdgeError: () => import_connect2.isEdgeError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/edge-link.ts
+var import_connect = require("@edge-markets/connect");
+
+// src/pkce.ts
+function generateRandomBytes(byteLength = 64) {
+  const array = new Uint8Array(byteLength);
+  crypto.getRandomValues(array);
+  return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function sha256(plain) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(plain);
+  return crypto.subtle.digest("SHA-256", data);
+}
+function base64UrlEncode(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function generatePKCE() {
+  const verifier = generateRandomBytes(64);
+  const hash = await sha256(verifier);
+  const challenge = base64UrlEncode(hash);
+  return { verifier, challenge };
+}
+function generateState() {
+  return generateRandomBytes(32);
+}
+function assertCryptoAvailable() {
+  if (typeof crypto === "undefined" || !crypto.subtle) {
+    throw new Error(
+      "Web Crypto API not available. EDGE Connect requires a secure context (HTTPS) and a modern browser."
+    );
+  }
+}
+
+// src/popup.ts
+var DEFAULT_CONFIG = {
+  width: 450,
+  height: 700
+};
+var CLOSE_CHECK_INTERVAL_MS = 500;
+var PopupManager = class {
+  constructor() {
+    this.popup = null;
+    this.closeCheckInterval = null;
+    this.callbacks = {};
+  }
+  /**
+   * Opens a popup window immediately.
+   *
+   * **MUST be called synchronously from a user click handler!**
+   * Any async operations before this call will cause popup blockers.
+   *
+   * The popup opens with a loading state and can be navigated later.
+   *
+   * @param callbacks - Optional lifecycle callbacks
+   * @returns The popup window, or null if blocked
+   *
+   * @example
+   * ```typescript
+   * // In a click handler
+   * const popup = manager.open({
+   *   onUserClose: () => handleExit('user_closed'),
+   * })
+   *
+   * if (!popup) {
+   *   throw new EdgePopupBlockedError()
+   * }
+   * ```
+   */
+  open(callbacks = {}) {
+    this.callbacks = callbacks;
+    const left = Math.round((window.screen.width - DEFAULT_CONFIG.width) / 2);
+    const top = Math.round((window.screen.height - DEFAULT_CONFIG.height) / 2);
+    const features = [
+      `width=${DEFAULT_CONFIG.width}`,
+      `height=${DEFAULT_CONFIG.height}`,
+      `left=${left}`,
+      `top=${top}`,
+      "scrollbars=yes",
+      "resizable=yes",
+      "toolbar=no",
+      "menubar=no",
+      "location=no",
+      "status=no"
+    ].join(",");
+    this.popup = window.open("about:blank", "edge-connect", features);
+    if (!this.popup) {
+      return null;
+    }
+    this.renderLoadingState();
+    this.startCloseMonitor();
+    return this.popup;
+  }
+  /**
+   * Navigates the popup to a URL.
+   *
+   * Call this after async initialization is complete.
+   * Safe to call anytime after open().
+   *
+   * @param url - URL to navigate to
+   */
+  navigateTo(url) {
+    if (this.popup && !this.popup.closed) {
+      this.popup.location.href = url;
+    }
+  }
+  /**
+   * Focuses the popup window.
+   *
+   * Useful when user clicks "Connect" again while popup is already open.
+   */
+  focus() {
+    if (this.popup && !this.popup.closed) {
+      this.popup.focus();
+    }
+  }
+  /**
+   * Closes the popup window and cleans up resources.
+   */
+  close() {
+    this.stopCloseMonitor();
+    if (this.popup && !this.popup.closed) {
+      this.popup.close();
+    }
+    this.popup = null;
+    this.callbacks = {};
+  }
+  /**
+   * Checks if the popup is currently open.
+   */
+  isOpen() {
+    return this.popup !== null && !this.popup.closed;
+  }
+  /**
+   * Gets the popup window reference.
+   */
+  getWindow() {
+    return this.popup;
+  }
+  // ===========================================================================
+  // PRIVATE METHODS
+  // ===========================================================================
+  /**
+   * 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.
+   */
+  renderLoadingState() {
+    if (!this.popup) return;
+    this.popup.document.write(`
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>EDGE Connect</title>
+  <style>
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+      color: white;
+    }
+
+    .container {
+      text-align: center;
+      padding: 40px;
+    }
+
+    .logo {
+      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);
+    }
+
+    .spinner {
+      width: 40px;
+      height: 40px;
+      border: 3px solid rgba(255, 255, 255, 0.2);
+      border-top-color: #00d4aa;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+      margin: 0 auto 24px;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    h1 {
+      font-size: 22px;
+      font-weight: 600;
+      margin-bottom: 8px;
+      letter-spacing: -0.5px;
+    }
+
+    p {
+      font-size: 15px;
+      color: rgba(255, 255, 255, 0.7);
+      line-height: 1.5;
+    }
+
+    .secure {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 6px;
+      margin-top: 32px;
+      font-size: 13px;
+      color: rgba(255, 255, 255, 0.5);
+    }
+
+    .secure svg {
+      width: 14px;
+      height: 14px;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="logo">E</div>
+    <div class="spinner"></div>
+    <h1>EDGE Connect</h1>
+    <p>Preparing secure connection...</p>
+    <div class="secure">
+      <svg 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>
+</body>
+</html>
+    `);
+    this.popup.document.close();
+  }
+  /**
+   * Starts monitoring for user closing the popup.
+   */
+  startCloseMonitor() {
+    this.closeCheckInterval = setInterval(() => {
+      if (this.popup?.closed) {
+        this.stopCloseMonitor();
+        this.popup = null;
+        this.callbacks.onUserClose?.();
+      }
+    }, CLOSE_CHECK_INTERVAL_MS);
+  }
+  /**
+   * Stops the close monitor interval.
+   */
+  stopCloseMonitor() {
+    if (this.closeCheckInterval !== null) {
+      clearInterval(this.closeCheckInterval);
+      this.closeCheckInterval = null;
+    }
+  }
+};
+
+// src/edge-link.ts
+var EdgeLink = class {
+  /**
+   * Creates a new EdgeLink instance.
+   *
+   * @param config - Configuration options
+   * @throws Error if required config is missing or crypto is unavailable
+   */
+  constructor(config) {
+    this.pkce = null;
+    this.state = null;
+    this.messageHandler = null;
+    this.isDestroyed = false;
+    if (!config.clientId) {
+      throw new Error("EdgeLink: clientId is required");
+    }
+    if (!config.environment) {
+      throw new Error("EdgeLink: environment is required");
+    }
+    if (!config.onSuccess) {
+      throw new Error("EdgeLink: onSuccess callback is required");
+    }
+    assertCryptoAvailable();
+    this.config = config;
+    this.popup = new PopupManager();
+    const envConfig = (0, import_connect.getEnvironmentConfig)(config.environment);
+    this.expectedOrigin = config.linkUrl ? new URL(config.linkUrl).origin : new URL(envConfig.userClientUrl).origin;
+    this.setupMessageListener();
+  }
+  // ===========================================================================
+  // PUBLIC API
+  // ===========================================================================
+  /**
+   * Opens the EdgeLink popup.
+   *
+   * **MUST be called directly from a user click handler!**
+   * Calling from setTimeout, Promise.then, or other async contexts will fail.
+   *
+   * @param options - Optional overrides for this open call
+   * @throws EdgePopupBlockedError if popup is blocked
+   *
+   * @example
+   * ```typescript
+   * // ✅ Correct - direct click handler
+   * button.onclick = () => link.open()
+   *
+   * // ❌ Wrong - async gap
+   * button.onclick = async () => {
+   *   await someAsyncWork()
+   *   link.open() // Will be blocked!
+   * }
+   * ```
+   */
+  open(options = {}) {
+    if (this.isDestroyed) {
+      throw new Error("EdgeLink: Cannot open - instance has been destroyed");
+    }
+    if (this.popup.isOpen()) {
+      this.popup.focus();
+      return;
+    }
+    this.emitEvent("OPEN");
+    const win = this.popup.open({
+      onUserClose: () => this.handleUserClose()
+    });
+    if (!win) {
+      this.emitEvent("ERROR", { reason: "popup_blocked" });
+      this.config.onExit?.({
+        reason: "popup_blocked",
+        error: {
+          code: "popup_blocked",
+          message: "Please allow popups for this site and try again."
+        }
+      });
+      throw new import_connect.EdgePopupBlockedError();
+    }
+    this.initializeAuth(options.scopes || this.config.scopes || import_connect.ALL_EDGE_SCOPES);
+  }
+  /**
+   * Closes the EdgeLink popup if open.
+   *
+   * Call this to programmatically close the popup without triggering onExit.
+   */
+  close() {
+    this.popup.close();
+    this.cleanup();
+  }
+  /**
+   * Destroys the EdgeLink instance.
+   *
+   * Call this when unmounting your component or when done with EdgeLink.
+   * After destroy(), the instance cannot be reused.
+   *
+   * @example
+   * ```typescript
+   * // React cleanup
+   * useEffect(() => {
+   *   const link = new EdgeLink({ ... })
+   *   return () => link.destroy()
+   * }, [])
+   * ```
+   */
+  destroy() {
+    this.isDestroyed = true;
+    this.close();
+    this.removeMessageListener();
+  }
+  /**
+   * Checks if the popup is currently open.
+   */
+  isOpen() {
+    return this.popup.isOpen();
+  }
+  // ===========================================================================
+  // PRIVATE METHODS
+  // ===========================================================================
+  /**
+   * Initializes PKCE and navigates popup to auth URL.
+   */
+  async initializeAuth(scopes) {
+    try {
+      this.pkce = await generatePKCE();
+      this.state = generateState();
+      const url = this.buildLinkUrl(scopes);
+      this.emitEvent("HANDOFF", { url });
+      this.popup.navigateTo(url);
+    } catch (error) {
+      this.popup.close();
+      this.emitEvent("ERROR", { error });
+      this.config.onExit?.({
+        reason: "error",
+        error: {
+          code: "init_failed",
+          message: error instanceof Error ? error.message : "Failed to initialize"
+        }
+      });
+    }
+  }
+  /**
+   * Builds the URL for the EdgeLink page.
+   *
+   * The Link page handles:
+   * - User authentication (if not logged in)
+   * - Consent UI (showing requested permissions)
+   * - OAuth redirect to Cognito
+   * - Returning code via postMessage
+   */
+  buildLinkUrl(scopes) {
+    const envConfig = (0, import_connect.getEnvironmentConfig)(this.config.environment);
+    const baseUrl = this.config.linkUrl || `${envConfig.userClientUrl}/oauth/link`;
+    const url = new URL(baseUrl);
+    url.searchParams.set("client_id", this.config.clientId);
+    url.searchParams.set("state", this.state);
+    url.searchParams.set("code_challenge", this.pkce.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    const formattedScopes = (0, import_connect.formatScopesForEnvironment)(scopes, this.config.environment);
+    url.searchParams.set("scope", formattedScopes.join(" "));
+    const redirectUri = this.config.redirectUri || `${window.location.origin}/oauth/edge/callback`;
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("origin", window.location.origin);
+    return url.toString();
+  }
+  /**
+   * Sets up the postMessage listener.
+   */
+  setupMessageListener() {
+    this.messageHandler = (event) => {
+      if (event.origin !== this.expectedOrigin) {
+        return;
+      }
+      const data = event.data;
+      if (!data?.type) return;
+      switch (data.type) {
+        case "EDGE_LINK_SUCCESS":
+          this.handleSuccess(data);
+          break;
+        case "EDGE_LINK_EXIT":
+          this.handleExit(data);
+          break;
+        case "EDGE_LINK_EVENT":
+          if (data.eventName) {
+            this.emitEvent(data.eventName);
+          }
+          break;
+      }
+    };
+    window.addEventListener("message", this.messageHandler);
+  }
+  /**
+   * Removes the postMessage listener.
+   */
+  removeMessageListener() {
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+  }
+  /**
+   * Handles successful authentication from popup.
+   */
+  handleSuccess(data) {
+    if (data.state !== this.state) {
+      this.emitEvent("ERROR", { reason: "state_mismatch" });
+      this.config.onExit?.({
+        reason: "error",
+        error: {
+          code: "state_mismatch",
+          message: "Security error: state parameter mismatch. Please try again."
+        }
+      });
+      this.close();
+      throw new import_connect.EdgeStateMismatchError();
+    }
+    if (!this.pkce?.verifier) {
+      this.config.onExit?.({
+        reason: "error",
+        error: {
+          code: "missing_verifier",
+          message: "Security error: code verifier not found. Please try again."
+        }
+      });
+      this.close();
+      return;
+    }
+    const codeVerifier = this.pkce.verifier;
+    this.popup.close();
+    this.cleanup();
+    this.emitEvent("SUCCESS");
+    this.config.onSuccess({
+      code: data.code,
+      codeVerifier,
+      state: data.state
+    });
+  }
+  /**
+   * Handles exit from popup.
+   */
+  handleExit(data) {
+    this.popup.close();
+    this.cleanup();
+    this.emitEvent("CLOSE", { reason: data.error ? "error" : "user_action" });
+    this.config.onExit?.({
+      reason: data.error ? "error" : "user_closed",
+      error: data.error
+    });
+  }
+  /**
+   * Handles user closing the popup manually.
+   */
+  handleUserClose() {
+    this.cleanup();
+    this.emitEvent("CLOSE", { reason: "user_closed" });
+    this.config.onExit?.({
+      reason: "user_closed"
+    });
+  }
+  /**
+   * Emits an event.
+   */
+  emitEvent(eventName, metadata) {
+    this.config.onEvent?.({
+      eventName,
+      timestamp: Date.now(),
+      metadata
+    });
+  }
+  /**
+   * Cleans up stored state.
+   */
+  cleanup() {
+    this.pkce = null;
+    this.state = null;
+  }
+};
+
+// src/index.ts
+var import_connect2 = require("@edge-markets/connect");
+var import_connect3 = require("@edge-markets/connect");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_EDGE_SCOPES,
+  EDGE_SCOPES,
+  EdgeError,
+  EdgeLink,
+  EdgePopupBlockedError,
+  EdgeStateMismatchError,
+  assertCryptoAvailable,
+  generatePKCE,
+  generateState,
+  isEdgeError
+});