@edge-markets/connect-node 1.6.0 → 1.7.0

package/dist/index.mjs

@@ -21,6 +21,14 @@ import {
 
 // src/validators.ts
 import { EdgeValidationError } from "@edge-markets/connect";
+var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validateTransferId(transferId) {
+  if (typeof transferId !== "string" || !UUID_V4_REGEX.test(transferId)) {
+    throw new EdgeValidationError("transferId must be a UUID v4", {
+      transferId: ["Must be a valid UUID v4"]
+    });
+  }
+}
 function validateVerifyIdentityOptions(options) {
   const errors = {};
   const firstName = typeof options.firstName === "string" ? options.firstName.trim() : "";
@@ -97,19 +105,8 @@ var EdgeUserClient = class {
     }
     return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
   }
-  async verifyTransfer(transferId, otp, options) {
-    const body = { otp };
-    if (options?.sdkGeo) {
-      body.sdkGeo = options.sdkGeo;
-    }
-    return this.server._apiRequest(
-      "POST",
-      `/transfer/${encodeURIComponent(transferId)}/verify`,
-      this.accessToken,
-      body
-    );
-  }
   async getTransfer(transferId) {
+    validateTransferId(transferId);
     return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
   }
   async listTransfers(params) {
@@ -130,6 +127,7 @@ var EdgeUserClient = class {
    * The handoff token is single-use and expires in 120 seconds.
    */
   async createVerificationSession(transferId, options) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "POST",
       `/transfer/${encodeURIComponent(transferId)}/verification-session`,
@@ -142,6 +140,7 @@ var EdgeUserClient = class {
    * Use as an alternative to postMessage events.
    */
   async getVerificationSessionStatus(transferId, sessionId) {
+    validateTransferId(transferId);
     return this.server._apiRequest(
       "GET",
       `/transfer/${encodeURIComponent(transferId)}/verification-session/${encodeURIComponent(sessionId)}`,
@@ -271,19 +270,31 @@ var instances = /* @__PURE__ */ new Map();
 function getInstanceKey(config) {
   return `${config.clientId}:${config.environment}`;
 }
-var EdgeConnectServer = class _EdgeConnectServer {
-  static getInstance(config) {
-    const key = getInstanceKey(config);
-    const existing = instances.get(key);
-    if (existing) return existing;
-    const instance = new _EdgeConnectServer(config);
-    instances.set(key, instance);
-    return instance;
+var MTLS_ENFORCED_HOSTS = /* @__PURE__ */ new Set(["connect-staging.edgeboost.io", "api.edgeboost.com"]);
+function isMtlsEnforcedHost(host) {
+  if (MTLS_ENFORCED_HOSTS.has(host)) {
+    return true;
+  }
+  for (const enforced of MTLS_ENFORCED_HOSTS) {
+    if (host.endsWith("." + enforced)) {
+      return true;
+    }
   }
-  static clearInstances() {
-    instances.clear();
+  return false;
+}
+function environmentRequiresMtls(environment, apiBaseUrl) {
+  if (environment === "staging" || environment === "production") {
+    return true;
   }
+  try {
+    return isMtlsEnforcedHost(new URL(apiBaseUrl).host);
+  } catch {
+    return false;
+  }
+}
+var EdgeConnectServer = class _EdgeConnectServer {
   constructor(config) {
+    this.partnerTokenCache = null;
     if (!config.clientId) {
       throw new Error("EdgeConnectServer: clientId is required");
     }
@@ -306,8 +317,23 @@ var EdgeConnectServer = class _EdgeConnectServer {
       validateMtlsConfig(config.mtls);
       this.httpsAgent = createHttpsAgent(config.mtls);
       this.dispatcher = createUndiciDispatcher(config.mtls);
+    } else if (environmentRequiresMtls(config.environment, this.apiBaseUrl)) {
+      console.warn(
+        `[EdgeConnectServer] environment='${config.environment}' is served from an mTLS-enforced host (${this.apiBaseUrl}) but no mtls config was provided. Requests will fail at the TLS handshake with a connection reset. Pass mtls: { enabled: true, cert, key, ca? } to EdgeConnectServer or coordinate with EDGE DevRel to issue a partner client certificate.`
+      );
     }
   }
+  static getInstance(config) {
+    const key = getInstanceKey(config);
+    const existing = instances.get(key);
+    if (existing) return existing;
+    const instance = new _EdgeConnectServer(config);
+    instances.set(key, instance);
+    return instance;
+  }
+  static clearInstances() {
+    instances.clear();
+  }
   /**
    * Returns the `node:https.Agent` configured with mTLS client certificates.
    * Use this with axios, got, or other HTTP clients. Returns `undefined` if mTLS is not configured.
@@ -478,6 +504,175 @@ var EdgeConnectServer = class _EdgeConnectServer {
       lastError
     );
   }
+  /**
+   * Reconcile webhook events from the partner sync endpoint.
+   *
+   * Use this from a scheduled cron (every ~5 minutes is typical) to catch
+   * events your primary webhook receiver missed — partner downtime, retry
+   * exhaustion, dead-letter queue. This is the third reliability layer
+   * ("Leg 3") on top of HTTP delivery + DLQ.
+   *
+   * **Authentication.** This method uses the OAuth `client_credentials`
+   * grant against {@link EdgeConnectServerConfig.partnerClientId} and
+   * {@link EdgeConnectServerConfig.partnerClientSecret}. The token is
+   * cached internally and refreshed automatically.
+   *
+   * **Pagination.** Pass `afterEventId` with the last `id` you processed.
+   * Loop while `hasMore` is true. The server enforces a 30-day lookback;
+   * cursors older than 30 days return events from 30 days ago, not an error.
+   *
+   * @example
+   * ```typescript
+   * let cursor: string | undefined = await loadCursorFromDb()
+   *
+   * while (true) {
+   *   const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+   *   for (const event of events) {
+   *     await processEvent(event)
+   *     cursor = event.id
+   *   }
+   *   if (events.length > 0) await saveCursorToDb(cursor!)
+   *   if (!hasMore) break
+   * }
+   * ```
+   *
+   * @throws {EdgeAuthenticationError} If partner credentials are missing
+   *         or the partner token cannot be obtained / refreshed
+   * @throws {EdgeNetworkError} On network failure
+   * @throws {EdgeApiError} For other non-2xx responses after retries
+   */
+  async syncWebhookEvents(options = {}) {
+    if (!this.config.partnerClientId) {
+      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
+    }
+    if (!this.config.partnerClientSecret) {
+      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientSecret` in EdgeConnectServer config");
+    }
+    const url = this.buildSyncUrl(options);
+    let token = await this.getPartnerToken();
+    let response = await this.partnerFetch(url, token);
+    if (response.status === 401) {
+      this.partnerTokenCache = null;
+      token = await this.getPartnerToken();
+      response = await this.partnerFetch(url, token);
+      if (response.status === 401) {
+        const body = await response.json().catch(() => ({}));
+        throw new EdgeAuthenticationError(
+          body.message || "Partner token rejected after refresh \u2014 check partnerClientId/Secret",
+          body
+        );
+      }
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new EdgeApiError(
+        body.error || "sync_failed",
+        body.message || `syncWebhookEvents failed with status ${response.status}`,
+        response.status,
+        body
+      );
+    }
+    const wire = await response.json().catch(() => ({}));
+    const events = (wire.events ?? []).map((entry) => entry.payload).filter((p) => !!p);
+    return {
+      events,
+      hasMore: !!wire.has_more
+    };
+  }
+  /**
+   * Builds the sync URL with normalized query parameters.
+   */
+  buildSyncUrl(options) {
+    const url = new URL(`${this.apiBaseUrl}/partner/webhooks/events/sync`);
+    if (options.afterEventId) {
+      url.searchParams.set("after_event_id", options.afterEventId);
+    }
+    if (options.limit !== void 0) {
+      url.searchParams.set("limit", String(options.limit));
+    }
+    return url.toString();
+  }
+  /**
+   * Issues a GET to the sync endpoint with the partner Bearer token. Kept
+   * separate from `_apiRequest` because partner tokens have a different
+   * lifecycle (process-wide, client_credentials) than user tokens.
+   */
+  async partnerFetch(url, token) {
+    try {
+      return await this.fetchWithTimeout(
+        url,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT
+          }
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new EdgeNetworkError("syncWebhookEvents network failure", error);
+    }
+  }
+  /**
+   * Fetches (or returns the cached) partner token via the
+   * `client_credentials` grant. Caches with a 60s safety margin so the
+   * token is renewed *before* the server-side expiry, never racing it.
+   *
+   * Side-effects: writes `this.partnerTokenCache` on success.
+   */
+  async getPartnerToken() {
+    const cached = this.partnerTokenCache;
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.token;
+    }
+    const tokenUrl = `${this.oauthBaseUrl}/token`;
+    let response;
+    try {
+      response = await this.fetchWithTimeout(
+        tokenUrl,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": USER_AGENT
+          },
+          body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.partnerClientId,
+            client_secret: this.config.partnerClientSecret
+          }).toString()
+        },
+        this.dispatcher
+      );
+    } catch (error) {
+      throw new EdgeNetworkError("Partner token request network failure", error);
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new EdgeAuthenticationError(
+        body.message || body.error_description || `Partner token request failed with status ${response.status}`,
+        body
+      );
+    }
+    const data = await response.json().catch(() => ({}));
+    if (!data.access_token || typeof data.expires_in !== "number") {
+      throw new EdgeAuthenticationError("Partner token response missing access_token or expires_in");
+    }
+    this.partnerTokenCache = {
+      token: data.access_token,
+      expiresAt: Date.now() + (data.expires_in - 60) * 1e3
+    };
+    return data.access_token;
+  }
+  /**
+   * @internal Test-only: clears the cached partner token so the next call
+   * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+   */
+  _resetPartnerTokenCache() {
+    this.partnerTokenCache = null;
+  }
   getRetryDelay(attempt) {
     const { backoff, baseDelayMs } = this.retryConfig;
     if (backoff === "exponential") {
@@ -587,6 +782,35 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
 };
 
+// src/webhook-signing.ts
+import crypto from "crypto";
+function verifyWebhookSignature(header, body, secret, options = {}) {
+  if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
+    return false;
+  }
+  const requestedTolerance = options.toleranceSeconds;
+  const toleranceSeconds = typeof requestedTolerance === "number" && Number.isFinite(requestedTolerance) && requestedTolerance >= 0 ? requestedTolerance : 300;
+  const parts = header.split(",").map((p) => p.trim());
+  const tPart = parts.find((p) => p.startsWith("t="));
+  const v1Part = parts.find((p) => p.startsWith("v1="));
+  if (!tPart || !v1Part) return false;
+  const timestamp = parseInt(tPart.slice(2), 10);
+  const signature = v1Part.slice(3);
+  if (isNaN(timestamp) || !signature) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+  const signedContent = `${timestamp}.${body}`;
+  const expectedHmac = crypto.createHmac("sha256", secret).update(signedContent).digest("hex");
+  try {
+    const sigBuf = Buffer.from(signature, "hex");
+    const expBuf = Buffer.from(expectedHmac, "hex");
+    if (sigBuf.length !== expBuf.length) return false;
+    return crypto.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 import {
   EdgeApiError as EdgeApiError2,
@@ -605,8 +829,14 @@ import {
   isIdentityVerificationError,
   isNetworkError
 } from "@edge-markets/connect";
-import { TRANSFER_CATEGORIES, getEnvironmentConfig as getEnvironmentConfig2, isProductionEnvironment } from "@edge-markets/connect";
+import {
+  EDGE_WEBHOOK_EVENT_TYPES,
+  TRANSFER_CATEGORIES,
+  getEnvironmentConfig as getEnvironmentConfig2,
+  isProductionEnvironment
+} from "@edge-markets/connect";
 export {
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError2 as EdgeApiError,
   EdgeAuthenticationError2 as EdgeAuthenticationError,
   EdgeConnectServer,
@@ -626,5 +856,6 @@ export {
   isEdgeError,
   isIdentityVerificationError,
   isNetworkError,
-  isProductionEnvironment
+  isProductionEnvironment,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-node",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Server SDK for EDGE Connect token exchange and API calls",
   "author": "Edge Markets",
   "license": "MIT",
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@edge-markets/connect": "^1.5.0"
+    "@edge-markets/connect": "^1.6.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",