@edge-markets/connect-node 1.7.0 → 1.8.0

package/dist/index.mjs

@@ -8,7 +8,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/edge-connect-server.ts
 import {
   EdgeApiError,
-  EdgeAuthenticationError,
+  EdgeAuthenticationError as EdgeAuthenticationError2,
   EdgeConsentRequiredError,
   EdgeError,
   EdgeIdentityVerificationError,
@@ -19,12 +19,137 @@ import {
   getEnvironmentConfig
 } from "@edge-markets/connect";
 
+// src/transfer-helpers.ts
+import {
+  EdgeValidationError
+} from "@edge-markets/connect";
+import crypto from "crypto";
+var DEFAULT_MIN_AMOUNT = "1.00";
+var DEFAULT_MAX_AMOUNT = "10000.00";
+function normalizeMoneyAmount(value) {
+  const cents = parseMoneyToCents(value, "amount");
+  const dollars = cents / 100n;
+  const remainder = cents % 100n;
+  return `${dollars.toString()}.${remainder.toString().padStart(2, "0")}`;
+}
+function validateTransferAmount(value, limits = {}) {
+  const amount = parseMoneyToCents(value, "amount");
+  const min = parseMoneyToCents(limits.min ?? DEFAULT_MIN_AMOUNT, "min");
+  const max = parseMoneyToCents(limits.max ?? DEFAULT_MAX_AMOUNT, "max");
+  const errors = {};
+  if (min <= 0n) errors.min = ["Minimum amount must be greater than 0"];
+  if (max < min) errors.max = ["Maximum amount must be greater than or equal to minimum amount"];
+  if (amount < min) errors.amount = [`Must be at least ${formatCents(min)}`];
+  if (amount > max) errors.amount = [`Must be at most ${formatCents(max)}`];
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError("Invalid transfer amount", errors);
+  }
+  return formatCents(amount);
+}
+function createTransferIdempotencyKey(options) {
+  const namespace = sanitizeKeyPart(options.namespace || "edge");
+  const partnerUserId = requireKeyPart(options.partnerUserId, "partnerUserId");
+  const externalId = options.externalId ? sanitizeKeyPart(options.externalId) : void 0;
+  const nonce = options.nonce ? sanitizeKeyPart(options.nonce) : void 0;
+  const amount = normalizeMoneyAmount(options.amount);
+  const digest = crypto.createHash("sha256").update(
+    JSON.stringify({
+      partnerUserId,
+      type: options.type,
+      amount,
+      category: options.category ?? null,
+      externalId: externalId ?? null,
+      nonce: nonce ?? null
+    })
+  ).digest("hex").slice(0, 32);
+  return [namespace, options.type, digest].join("_");
+}
+function assertSameTransferIntent(existing, requested) {
+  const errors = {};
+  if (existing.type !== requested.type) {
+    errors.type = [`Expected ${existing.type}, received ${requested.type}`];
+  }
+  const existingAmount = normalizeMoneyAmount(existing.amount);
+  const requestedAmount = normalizeMoneyAmount(requested.amount);
+  if (existingAmount !== requestedAmount) {
+    errors.amount = [`Expected ${existingAmount}, received ${requestedAmount}`];
+  }
+  const existingCategory = existing.category ?? void 0;
+  const requestedCategory = requested.category ?? void 0;
+  if (existingCategory !== requestedCategory) {
+    errors.category = [`Expected ${existingCategory || "unset"}, received ${requestedCategory || "unset"}`];
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError("Transfer intent does not match existing idempotent transfer", errors);
+  }
+}
+async function startTransferVerification(client, options) {
+  const origin = typeof options.origin === "string" ? options.origin.trim() : "";
+  if (!origin) {
+    throw new EdgeValidationError("Verification origin is required", {
+      origin: ["Required"]
+    });
+  }
+  const transfer = await client.initiateTransfer({
+    ...options.transfer,
+    amount: normalizeMoneyAmount(options.transfer.amount)
+  });
+  const transferId = transfer.transferId;
+  if (!transferId) {
+    throw new EdgeValidationError("Transfer response missing transferId", {
+      transferId: ["Required to create a verification session"]
+    });
+  }
+  const verificationSession = await client.createVerificationSession(transferId, { origin });
+  return { transfer, verificationSession };
+}
+function parseMoneyToCents(value, field) {
+  let input;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new EdgeValidationError("Money amount must be finite", { [field]: ["Must be a finite number"] });
+    }
+    input = value.toFixed(2);
+  } else if (typeof value === "string") {
+    input = value.trim();
+  } else {
+    throw new EdgeValidationError("Money amount must be a string or number", { [field]: ["Invalid type"] });
+  }
+  if (!/^\d+(\.\d{0,2})?$/.test(input)) {
+    throw new EdgeValidationError("Money amount must be a positive decimal with at most 2 places", {
+      [field]: ['Use a decimal string like "25.00"']
+    });
+  }
+  const [dollars, cents = ""] = input.split(".");
+  const normalizedDollars = dollars.replace(/^0+(?=\d)/, "") || "0";
+  const amount = BigInt(normalizedDollars) * 100n + BigInt(cents.padEnd(2, "0"));
+  if (amount <= 0n) {
+    throw new EdgeValidationError("Money amount must be greater than 0", { [field]: ["Must be greater than 0"] });
+  }
+  return amount;
+}
+function formatCents(cents) {
+  return `${(cents / 100n).toString()}.${(cents % 100n).toString().padStart(2, "0")}`;
+}
+function requireKeyPart(value, field) {
+  const sanitized = sanitizeKeyPart(value);
+  if (!sanitized) {
+    throw new EdgeValidationError("Idempotency key input is incomplete", {
+      [field]: ["Required"]
+    });
+  }
+  return sanitized;
+}
+function sanitizeKeyPart(value) {
+  return value.trim().replace(/[^a-zA-Z0-9_.:-]/g, "_").slice(0, 64);
+}
+
 // src/validators.ts
-import { EdgeValidationError } from "@edge-markets/connect";
+import { EdgeValidationError as EdgeValidationError2 } 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", {
+    throw new EdgeValidationError2("transferId must be a UUID v4", {
       transferId: ["Must be a valid UUID v4"]
     });
   }
@@ -44,7 +169,7 @@ function validateVerifyIdentityOptions(options) {
   }
   if (Object.keys(errors).length > 0) {
     const firstMessage = Object.values(errors)[0][0];
-    throw new EdgeValidationError(firstMessage, errors);
+    throw new EdgeValidationError2(firstMessage, errors);
   }
 }
 function validateTransferOptions(options) {
@@ -73,7 +198,7 @@ function validateTransferOptions(options) {
     errors.category = ["Must be one of: sportsbook, casino, dfs, sweepstakes"];
   }
   if (Object.keys(errors).length > 0) {
-    throw new EdgeValidationError("Invalid transfer options", errors);
+    throw new EdgeValidationError2("Invalid transfer options", errors);
   }
 }
 
@@ -105,6 +230,9 @@ var EdgeUserClient = class {
     }
     return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
   }
+  async startTransferVerification(options) {
+    return startTransferVerification(this, options);
+  }
   async getTransfer(transferId) {
     validateTransferId(transferId);
     return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
@@ -225,16 +353,46 @@ function fromBase64Url(value) {
 }
 
 // src/mtls.ts
+import fs from "fs";
 import https from "https";
+import tls from "tls";
+var CERT_PATTERN = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+function normalizeCaBundle(ca) {
+  if (!ca) return [];
+  const values = Array.isArray(ca) ? ca : [ca];
+  return values.flatMap((value) => {
+    const normalized = value.replace(/\\n/g, "\n").trim();
+    if (!normalized) return [];
+    const certificates = normalized.match(CERT_PATTERN);
+    return certificates ? certificates.map((certificate) => certificate.trim()) : [normalized];
+  });
+}
+function getNodeExtraCaCerts() {
+  const extraCaPath = process.env.NODE_EXTRA_CA_CERTS?.trim();
+  if (!extraCaPath) return [];
+  try {
+    return normalizeCaBundle(fs.readFileSync(extraCaPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`EdgeConnectServer: failed to read NODE_EXTRA_CA_CERTS from "${extraCaPath}": ${message}`);
+  }
+}
+function buildServerCaBundle(ca) {
+  const customCa = normalizeCaBundle(ca);
+  if (customCa.length === 0) return void 0;
+  return Array.from(/* @__PURE__ */ new Set([...tls.rootCertificates, ...getNodeExtraCaCerts(), ...customCa]));
+}
 function createHttpsAgent(config) {
+  const ca = buildServerCaBundle(config.ca);
   return new https.Agent({
     cert: config.cert,
     key: config.key,
     rejectUnauthorized: true,
-    ...config.ca ? { ca: config.ca } : {}
+    ...ca ? { ca } : {}
   });
 }
 function createUndiciDispatcher(config) {
+  const ca = buildServerCaBundle(config.ca);
   const moduleName = "undici";
   const { Agent } = __require(moduleName);
   return new Agent({
@@ -242,7 +400,7 @@ function createUndiciDispatcher(config) {
       cert: config.cert,
       key: config.key,
       rejectUnauthorized: true,
-      ...config.ca ? { ca: config.ca } : {}
+      ...ca ? { ca } : {}
     }
   });
 }
@@ -255,6 +413,112 @@ function validateMtlsConfig(config) {
   }
 }
 
+// src/session.ts
+import { EdgeAuthenticationError, EdgeValidationError as EdgeValidationError3 } from "@edge-markets/connect";
+var EdgeUserSession = class {
+  constructor(options) {
+    if (!options.edge?.forUser || !options.edge?.refreshTokens) {
+      throw new EdgeValidationError3("EdgeUserSession requires an EdgeConnectServer instance", {
+        edge: ["Provide edge.forUser and edge.refreshTokens"]
+      });
+    }
+    const subjectId = typeof options.subjectId === "string" ? options.subjectId.trim() : "";
+    if (!subjectId) {
+      throw new EdgeValidationError3("EdgeUserSession subjectId is required", {
+        subjectId: ["Required"]
+      });
+    }
+    if (!options.tokenStore?.load || !options.tokenStore?.save) {
+      throw new EdgeValidationError3("EdgeUserSession tokenStore is required", {
+        tokenStore: ["Provide load(subjectId) and save(subjectId, value, context)"]
+      });
+    }
+    if (options.refreshSkewMs !== void 0 && (!Number.isFinite(options.refreshSkewMs) || options.refreshSkewMs < 0)) {
+      throw new EdgeValidationError3("refreshSkewMs must be a non-negative number", {
+        refreshSkewMs: ["Must be greater than or equal to 0"]
+      });
+    }
+    this.edge = options.edge;
+    this.subjectId = subjectId;
+    this.tokenStore = options.tokenStore;
+    this.tokenVault = options.tokenVault;
+    this.refreshSkewMs = options.refreshSkewMs ?? 6e4;
+    this.now = options.now ?? Date.now;
+    this.onRefresh = options.onRefresh;
+  }
+  async getValidTokens(options = {}) {
+    const tokens = await this.loadTokens();
+    if (!options.forceRefresh && tokens.expiresAt > this.now() + this.refreshSkewMs) {
+      return tokens;
+    }
+    const refreshed = await this.edge.refreshTokens(tokens.refreshToken);
+    await this.saveTokens(refreshed, true);
+    await this.onRefresh?.(refreshed);
+    return refreshed;
+  }
+  async getClient(options = {}) {
+    const tokens = await this.getValidTokens(options);
+    return this.edge.forUser(tokens.accessToken);
+  }
+  async withClient(callback) {
+    const tokens = await this.getValidTokens();
+    return callback(this.edge.forUser(tokens.accessToken), tokens);
+  }
+  async saveTokens(tokens, refreshed = false) {
+    validateTokens(tokens);
+    const value = this.tokenVault ? this.tokenVault.encryptTokens(tokens) : tokens;
+    await this.tokenStore.save(this.subjectId, value, { tokens, refreshed });
+  }
+  async loadTokens() {
+    const value = await this.tokenStore.load(this.subjectId);
+    if (!value) {
+      throw new EdgeAuthenticationError("No EDGE tokens are stored for this subject", {
+        subjectId: this.subjectId
+      });
+    }
+    if (typeof value === "string") {
+      if (!this.tokenVault) {
+        throw new EdgeAuthenticationError("Encrypted EDGE token envelope loaded but no tokenVault was configured", {
+          subjectId: this.subjectId
+        });
+      }
+      const tokens = this.tokenVault.decryptTokens(value);
+      validateTokens(tokens);
+      return tokens;
+    }
+    validateTokens(value);
+    return value;
+  }
+};
+function createEdgeUserSession(options) {
+  return new EdgeUserSession(options);
+}
+function validateTokens(tokens) {
+  const errors = {};
+  if (!tokens || typeof tokens !== "object") {
+    errors.tokens = ["Expected token object"];
+  } else {
+    if (typeof tokens.accessToken !== "string" || !tokens.accessToken.trim()) {
+      errors.accessToken = ["Required"];
+    }
+    if (typeof tokens.refreshToken !== "string" || !tokens.refreshToken.trim()) {
+      errors.refreshToken = ["Required"];
+    }
+    if (typeof tokens.expiresAt !== "number" || !Number.isFinite(tokens.expiresAt) || tokens.expiresAt <= 0) {
+      errors.expiresAt = ["Must be a positive Unix timestamp in milliseconds"];
+    }
+    if (typeof tokens.expiresIn !== "number" || !Number.isFinite(tokens.expiresIn) || tokens.expiresIn <= 0) {
+      errors.expiresIn = ["Must be a positive number"];
+    }
+    if (typeof tokens.scope !== "string") {
+      errors.scope = ["Required"];
+    }
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError3("Invalid EDGE token payload", errors);
+  }
+}
+
 // src/types.ts
 var DEFAULT_TIMEOUT = 3e4;
 var USER_AGENT = "@edge-markets/connect-node/1.0.0";
@@ -265,12 +529,113 @@ var DEFAULT_RETRY_CONFIG = {
   baseDelayMs: 1e3
 };
 
+// src/webhook-reconciler.ts
+var DEFAULT_MAX_PAGES = 10;
+var EdgeWebhookReconciler = class {
+  constructor(options) {
+    this.running = false;
+    if (!options.edge?.syncWebhookEvents) {
+      throw new Error("EdgeWebhookReconciler: edge.syncWebhookEvents is required");
+    }
+    if (!options.cursorStore?.load || !options.cursorStore?.save) {
+      throw new Error("EdgeWebhookReconciler: cursorStore.load and cursorStore.save are required");
+    }
+    if (!options.processEvent) {
+      throw new Error("EdgeWebhookReconciler: processEvent is required");
+    }
+    if (options.maxPages !== void 0 && (!Number.isInteger(options.maxPages) || options.maxPages <= 0)) {
+      throw new Error("EdgeWebhookReconciler: maxPages must be a positive integer");
+    }
+    this.options = options;
+  }
+  async run() {
+    if (this.running) {
+      return {
+        processed: 0,
+        pages: 0,
+        hasMore: false,
+        skipped: true,
+        reason: "already_running"
+      };
+    }
+    this.running = true;
+    try {
+      return await this.runInternal();
+    } finally {
+      this.running = false;
+    }
+  }
+  async runInternal() {
+    let cursor = normalizeCursor(await this.options.cursorStore.load());
+    let processed = 0;
+    let pages = 0;
+    let hasMore = false;
+    const maxPages = this.options.maxPages ?? DEFAULT_MAX_PAGES;
+    while (pages < maxPages) {
+      const result = await this.options.edge.syncWebhookEvents({
+        ...cursor ? { afterEventId: cursor } : {},
+        ...this.options.limit !== void 0 ? { limit: this.options.limit } : {}
+      });
+      pages++;
+      hasMore = result.hasMore;
+      if (result.events.length === 0) {
+        return {
+          processed,
+          pages,
+          ...cursor ? { cursor } : {},
+          hasMore,
+          skipped: false,
+          ...hasMore ? { reason: "empty_page_with_has_more" } : {}
+        };
+      }
+      for (const event of result.events) {
+        await this.options.processEvent(event);
+        cursor = event.id;
+        await this.options.cursorStore.save(cursor);
+        processed++;
+      }
+      if (!result.hasMore) {
+        return {
+          processed,
+          pages,
+          ...cursor ? { cursor } : {},
+          hasMore: false,
+          skipped: false
+        };
+      }
+    }
+    return {
+      processed,
+      pages,
+      ...cursor ? { cursor } : {},
+      hasMore,
+      skipped: false,
+      ...hasMore ? { reason: "max_pages_reached" } : {}
+    };
+  }
+};
+function createWebhookReconciler(options) {
+  return new EdgeWebhookReconciler(options);
+}
+function normalizeCursor(cursor) {
+  if (typeof cursor !== "string") return void 0;
+  const trimmed = cursor.trim();
+  return trimmed || void 0;
+}
+
 // src/edge-connect-server.ts
 var instances = /* @__PURE__ */ new Map();
 function getInstanceKey(config) {
-  return `${config.clientId}:${config.environment}`;
+  return JSON.stringify([
+    config.clientId,
+    config.environment,
+    config.apiBaseUrl || "",
+    config.oauthBaseUrl || "",
+    config.partnerApiBaseUrl || "",
+    config.partnerClientId || ""
+  ]);
 }
-var MTLS_ENFORCED_HOSTS = /* @__PURE__ */ new Set(["connect-staging.edgeboost.io", "api.edgeboost.com"]);
+var MTLS_ENFORCED_HOSTS = /* @__PURE__ */ new Set(["connect-staging.edgeboost.io", "connect.edgeboost.io"]);
 function isMtlsEnforcedHost(host) {
   if (MTLS_ENFORCED_HOSTS.has(host)) {
     return true;
@@ -292,6 +657,29 @@ function environmentRequiresMtls(environment, apiBaseUrl) {
     return false;
   }
 }
+var CONNECT_API_BASE_PATH = "/connect/v1";
+function stripTrailingSlash(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  return value.slice(0, end);
+}
+function derivePartnerApiBaseUrl(apiBaseUrl) {
+  const url = new URL(apiBaseUrl);
+  const normalizedPath = stripTrailingSlash(url.pathname);
+  if (normalizedPath.endsWith(CONNECT_API_BASE_PATH)) {
+    const prefix = normalizedPath.slice(0, -CONNECT_API_BASE_PATH.length);
+    url.pathname = `${prefix}/v1`;
+  } else {
+    url.pathname = normalizedPath || "/";
+  }
+  url.search = "";
+  url.hash = "";
+  return stripTrailingSlash(url.toString());
+}
+var SYNC_WEBHOOK_EVENTS_MIN_LIMIT = 1;
+var SYNC_WEBHOOK_EVENTS_MAX_LIMIT = 100;
 var EdgeConnectServer = class _EdgeConnectServer {
   constructor(config) {
     this.partnerTokenCache = null;
@@ -307,6 +695,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
     this.config = config;
     const envConfig = getEnvironmentConfig(config.environment);
     this.apiBaseUrl = config.apiBaseUrl || envConfig.apiBaseUrl;
+    this.partnerApiBaseUrl = stripTrailingSlash(config.partnerApiBaseUrl || derivePartnerApiBaseUrl(this.apiBaseUrl));
     this.oauthBaseUrl = config.oauthBaseUrl || envConfig.oauthBaseUrl;
     this.timeout = config.timeout || DEFAULT_TIMEOUT;
     this.retryConfig = {
@@ -349,10 +738,13 @@ var EdgeConnectServer = class _EdgeConnectServer {
    */
   forUser(accessToken) {
     if (!accessToken) {
-      throw new EdgeAuthenticationError("accessToken is required when calling forUser()");
+      throw new EdgeAuthenticationError2("accessToken is required when calling forUser()");
     }
     return new EdgeUserClient(this, accessToken);
   }
+  createUserSession(options) {
+    return new EdgeUserSession({ ...options, edge: this });
+  }
   async exchangeCode(code, codeVerifier, redirectUri) {
     const tokenUrl = `${this.oauthBaseUrl}/token`;
     const body = {
@@ -410,7 +802,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
       );
       if (!response.ok) {
         const error = await response.json().catch(() => ({}));
-        throw new EdgeAuthenticationError(
+        throw new EdgeAuthenticationError2(
           error.message || error.error_description || "Token refresh failed. User may need to reconnect.",
           { tokenError: error }
         );
@@ -543,21 +935,41 @@ var EdgeConnectServer = class _EdgeConnectServer {
    */
   async syncWebhookEvents(options = {}) {
     if (!this.config.partnerClientId) {
-      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
+      throw new EdgeAuthenticationError2("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
     }
     if (!this.config.partnerClientSecret) {
-      throw new EdgeAuthenticationError("syncWebhookEvents requires `partnerClientSecret` in EdgeConnectServer config");
+      throw new EdgeAuthenticationError2("syncWebhookEvents requires `partnerClientSecret` in EdgeConnectServer config");
     }
-    const url = this.buildSyncUrl(options);
+    const normalizedOptions = this.normalizeSyncWebhookEventsOptions(options);
+    const url = this.buildSyncUrl(normalizedOptions);
     let token = await this.getPartnerToken();
-    let response = await this.partnerFetch(url, token);
+    let { response, durationMs, attempt } = await this.partnerFetch(url, token);
     if (response.status === 401) {
+      await this.drainResponseBody(response);
+      this.config.onResponse?.({
+        status: response.status,
+        body: { error: "unauthorized" },
+        durationMs,
+        method: "GET",
+        url,
+        endpoint: "partner_webhook_sync",
+        attempt
+      });
       this.partnerTokenCache = null;
       token = await this.getPartnerToken();
-      response = await this.partnerFetch(url, token);
+      ({ response, durationMs, attempt } = await this.partnerFetch(url, token));
       if (response.status === 401) {
         const body = await response.json().catch(() => ({}));
-        throw new EdgeAuthenticationError(
+        this.config.onResponse?.({
+          status: response.status,
+          body: this.redactPartnerSyncResponseBody(body),
+          durationMs,
+          method: "GET",
+          url,
+          endpoint: "partner_webhook_sync",
+          attempt
+        });
+        throw new EdgeAuthenticationError2(
           body.message || "Partner token rejected after refresh \u2014 check partnerClientId/Secret",
           body
         );
@@ -565,6 +977,15 @@ var EdgeConnectServer = class _EdgeConnectServer {
     }
     if (!response.ok) {
       const body = await response.json().catch(() => ({}));
+      this.config.onResponse?.({
+        status: response.status,
+        body: this.redactPartnerSyncResponseBody(body),
+        durationMs,
+        method: "GET",
+        url,
+        endpoint: "partner_webhook_sync",
+        attempt
+      });
       throw new EdgeApiError(
         body.error || "sync_failed",
         body.message || `syncWebhookEvents failed with status ${response.status}`,
@@ -573,17 +994,57 @@ var EdgeConnectServer = class _EdgeConnectServer {
       );
     }
     const wire = await response.json().catch(() => ({}));
+    this.config.onResponse?.({
+      status: response.status,
+      body: {
+        eventCount: wire.events?.length ?? 0,
+        hasMore: !!wire.has_more
+      },
+      durationMs,
+      method: "GET",
+      url,
+      endpoint: "partner_webhook_sync",
+      attempt
+    });
     const events = (wire.events ?? []).map((entry) => entry.payload).filter((p) => !!p);
     return {
       events,
       hasMore: !!wire.has_more
     };
   }
+  /**
+   * Creates a cursor-based webhook reconciler bound to this SDK instance.
+   *
+   * Use this from cron jobs to process events returned by
+   * {@link EdgeConnectServer.syncWebhookEvents} without hand-writing
+   * pagination, cursor advancement, or process-level concurrency guards.
+   */
+  createWebhookReconciler(options) {
+    return new EdgeWebhookReconciler({ ...options, edge: this });
+  }
   /**
    * Builds the sync URL with normalized query parameters.
    */
+  normalizeSyncWebhookEventsOptions(options) {
+    const normalized = {};
+    if (typeof options.afterEventId === "string" && options.afterEventId.trim()) {
+      normalized.afterEventId = options.afterEventId.trim();
+    }
+    if (options.limit !== void 0) {
+      if (!Number.isInteger(options.limit) || options.limit < SYNC_WEBHOOK_EVENTS_MIN_LIMIT || options.limit > SYNC_WEBHOOK_EVENTS_MAX_LIMIT) {
+        throw new EdgeApiError(
+          "invalid_sync_options",
+          `syncWebhookEvents limit must be an integer between ${SYNC_WEBHOOK_EVENTS_MIN_LIMIT} and ${SYNC_WEBHOOK_EVENTS_MAX_LIMIT}`,
+          400,
+          { limit: options.limit }
+        );
+      }
+      normalized.limit = options.limit;
+    }
+    return normalized;
+  }
   buildSyncUrl(options) {
-    const url = new URL(`${this.apiBaseUrl}/partner/webhooks/events/sync`);
+    const url = new URL(`${this.partnerApiBaseUrl}/partner/webhooks/events/sync`);
     if (options.afterEventId) {
       url.searchParams.set("after_event_id", options.afterEventId);
     }
@@ -598,22 +1059,57 @@ var EdgeConnectServer = class _EdgeConnectServer {
    * lifecycle (process-wide, client_credentials) than user tokens.
    */
   async partnerFetch(url, token) {
-    try {
-      return await this.fetchWithTimeout(
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      if (attempt > 0) {
+        await this.sleep(this.getRetryDelay(attempt - 1));
+      }
+      const startTime = Date.now();
+      this.config.onRequest?.({
+        method: "GET",
         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);
+        endpoint: "partner_webhook_sync",
+        attempt
+      });
+      try {
+        const response = await this.fetchWithTimeout(
+          url,
+          {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${token}`,
+              "Content-Type": "application/json",
+              "User-Agent": USER_AGENT
+            }
+          },
+          this.dispatcher
+        );
+        const durationMs = Date.now() - startTime;
+        if (response.status !== 401 && this.retryConfig.retryOn.includes(response.status) && attempt < this.retryConfig.maxRetries) {
+          await this.drainResponseBody(response);
+          this.config.onResponse?.({
+            status: response.status,
+            body: { retrying: true },
+            durationMs,
+            method: "GET",
+            url,
+            endpoint: "partner_webhook_sync",
+            attempt
+          });
+          continue;
+        }
+        return { response, durationMs, attempt };
+      } catch (error) {
+        lastError = error;
+        if (attempt >= this.retryConfig.maxRetries) {
+          throw new EdgeNetworkError("syncWebhookEvents network failure", lastError);
+        }
+      }
     }
+    throw new EdgeNetworkError(
+      `syncWebhookEvents network failure after ${this.retryConfig.maxRetries} retries`,
+      lastError
+    );
   }
   /**
    * Fetches (or returns the cached) partner token via the
@@ -629,6 +1125,17 @@ var EdgeConnectServer = class _EdgeConnectServer {
     }
     const tokenUrl = `${this.oauthBaseUrl}/token`;
     let response;
+    const startTime = Date.now();
+    this.config.onRequest?.({
+      method: "POST",
+      url: tokenUrl,
+      endpoint: "oauth_token",
+      body: {
+        grant_type: "client_credentials",
+        client_id: this.config.partnerClientId,
+        client_secret: "[REDACTED]"
+      }
+    });
     try {
       response = await this.fetchWithTimeout(
         tokenUrl,
@@ -649,16 +1156,24 @@ var EdgeConnectServer = class _EdgeConnectServer {
     } catch (error) {
       throw new EdgeNetworkError("Partner token request network failure", error);
     }
+    const durationMs = Date.now() - startTime;
+    const data = await response.json().catch(() => ({}));
+    this.config.onResponse?.({
+      status: response.status,
+      body: this.redactPartnerTokenResponseBody(data),
+      durationMs,
+      method: "POST",
+      url: tokenUrl,
+      endpoint: "oauth_token"
+    });
     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
+      throw new EdgeAuthenticationError2(
+        data.message || data.error_description || `Partner token request failed with status ${response.status}`,
+        data
       );
     }
-    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");
+      throw new EdgeAuthenticationError2("Partner token response missing access_token or expires_in");
     }
     this.partnerTokenCache = {
       token: data.access_token,
@@ -673,6 +1188,26 @@ var EdgeConnectServer = class _EdgeConnectServer {
   _resetPartnerTokenCache() {
     this.partnerTokenCache = null;
   }
+  redactPartnerTokenResponseBody(body) {
+    return {
+      ...body,
+      ...typeof body.access_token === "string" ? { access_token: "[REDACTED]" } : {},
+      ...typeof body.refresh_token === "string" ? { refresh_token: "[REDACTED]" } : {},
+      ...typeof body.id_token === "string" ? { id_token: "[REDACTED]" } : {}
+    };
+  }
+  redactPartnerSyncResponseBody(body) {
+    if (Array.isArray(body.events)) {
+      return {
+        ...body,
+        events: `[REDACTED ${body.events.length} events]`
+      };
+    }
+    return body;
+  }
+  async drainResponseBody(response) {
+    await response.arrayBuffer().catch(() => void 0);
+  }
   getRetryDelay(attempt) {
     const { backoff, baseDelayMs } = this.retryConfig;
     if (backoff === "exponential") {
@@ -718,7 +1253,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
       });
     }
     if (errorCode === "invalid_client" || errorMessage?.includes("Invalid client")) {
-      return new EdgeAuthenticationError("Invalid client credentials. Check your client ID and secret.", {
+      return new EdgeAuthenticationError2("Invalid client credentials. Check your client ID and secret.", {
         edgeBoostError: error
       });
     }
@@ -732,7 +1267,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
   async handleApiErrorFromBody(error, status, path) {
     if (status === 401) {
-      return new EdgeAuthenticationError(error.message || "Access token is invalid or expired", error);
+      return new EdgeAuthenticationError2(error.message || "Access token is invalid or expired", error);
     }
     if (status === 403) {
       if (error.error === "consent_required") {
@@ -782,8 +1317,519 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
 };
 
+// src/env.ts
+import { EDGE_ENVIRONMENTS, EdgeValidationError as EdgeValidationError4, getEnvironmentConfig as getEnvironmentConfig2 } from "@edge-markets/connect";
+import fs2 from "fs";
+var ENVIRONMENT_NAMES = new Set(Object.keys(EDGE_ENVIRONMENTS));
+function readEnv(env, name) {
+  const value = env[name];
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function readFirstEnv(env, names) {
+  for (const name of names) {
+    const value = readEnv(env, name);
+    if (value) return value;
+  }
+  return void 0;
+}
+function normalizePem(value) {
+  return value.replace(/\\n/g, "\n").trim();
+}
+function readPemValue(env, valueName, pathName, warnings) {
+  const inlineValue = readEnv(env, valueName);
+  const filePath = readEnv(env, pathName);
+  if (inlineValue && filePath) {
+    warnings.push(`${valueName} and ${pathName} are both set; using ${valueName}`);
+  }
+  if (inlineValue) {
+    return normalizePem(inlineValue);
+  }
+  if (!filePath) {
+    return void 0;
+  }
+  try {
+    return normalizePem(fs2.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new EdgeValidationError4(`Failed to read ${pathName}`, {
+      [pathName]: [`Unable to read PEM file "${filePath}": ${message}`]
+    });
+  }
+}
+function readEnvironment(env) {
+  const value = readEnv(env, "EDGE_ENVIRONMENT") || "staging";
+  if (!ENVIRONMENT_NAMES.has(value)) {
+    throw new EdgeValidationError4("Invalid EDGE_ENVIRONMENT", {
+      EDGE_ENVIRONMENT: [`Must be one of: ${Array.from(ENVIRONMENT_NAMES).join(", ")}`]
+    });
+  }
+  return value;
+}
+function readTimeout(env, override) {
+  if (override !== void 0) return override;
+  const value = readFirstEnv(env, ["EDGE_TIMEOUT_MS", "EDGE_REQUEST_TIMEOUT_MS"]);
+  if (!value) return void 0;
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new EdgeValidationError4("Invalid EDGE_TIMEOUT_MS", {
+      EDGE_TIMEOUT_MS: ["Must be a positive integer number of milliseconds"]
+    });
+  }
+  return timeout;
+}
+function buildMtlsConfig(env, requireMtls, warnings) {
+  const cert = readPemValue(env, "EDGE_MTLS_CERT", "EDGE_MTLS_CERT_PATH", warnings);
+  const key = readPemValue(env, "EDGE_MTLS_KEY", "EDGE_MTLS_KEY_PATH", warnings);
+  const ca = readPemValue(env, "EDGE_MTLS_CA", "EDGE_MTLS_CA_PATH", warnings);
+  if (!cert && !key && !ca) {
+    if (requireMtls) {
+      throw new EdgeValidationError4("mTLS is required but no EDGE_MTLS_CERT or EDGE_MTLS_KEY was provided", {
+        EDGE_MTLS_CERT: ["Required when requireMtls is true"],
+        EDGE_MTLS_KEY: ["Required when requireMtls is true"]
+      });
+    }
+    return void 0;
+  }
+  if (!cert || !key) {
+    throw new EdgeValidationError4("Incomplete mTLS configuration", {
+      EDGE_MTLS_CERT: cert ? [] : ["Required when mTLS is configured"],
+      EDGE_MTLS_KEY: key ? [] : ["Required when mTLS is configured"]
+    });
+  }
+  return {
+    enabled: true,
+    cert,
+    key,
+    ...ca ? { ca } : {}
+  };
+}
+function inferMtlsRequirement(environment, apiBaseUrl) {
+  if (environment === "staging" || environment === "production") return true;
+  const resolvedApiBaseUrl = apiBaseUrl || getEnvironmentConfig2(environment).apiBaseUrl;
+  try {
+    const host = new URL(resolvedApiBaseUrl).host;
+    return host === "connect-staging.edgeboost.io" || host === "connect.edgeboost.io";
+  } catch {
+    return false;
+  }
+}
+function createEdgeConnectServerFromEnv(options = {}) {
+  const env = options.env ?? process.env;
+  const warnings = [];
+  const environment = readEnvironment(env);
+  const apiBaseUrl = readEnv(env, "EDGE_API_BASE_URL");
+  const mtlsRequiredByTarget = inferMtlsRequirement(environment, apiBaseUrl);
+  const requireMtls = options.requireMtls ?? false;
+  const mtls = buildMtlsConfig(env, requireMtls, warnings);
+  const timeout = readTimeout(env, options.timeout);
+  const clientId = readFirstEnv(env, ["EDGE_CLIENT_ID", "EDGE_CONNECT_CLIENT_ID"]) || "";
+  const clientSecret = readFirstEnv(env, ["EDGE_CLIENT_SECRET", "EDGE_CONNECT_CLIENT_SECRET"]) || "";
+  const oauthBaseUrl = readEnv(env, "EDGE_OAUTH_BASE_URL");
+  const partnerApiBaseUrl = readEnv(env, "EDGE_PARTNER_API_BASE_URL");
+  const partnerClientId = readFirstEnv(env, ["EDGE_PARTNER_CLIENT_ID", "EDGE_DASHBOARD_CLIENT_ID"]);
+  const partnerClientSecret = readFirstEnv(env, ["EDGE_PARTNER_CLIENT_SECRET", "EDGE_DASHBOARD_CLIENT_SECRET"]);
+  const validationErrors = {};
+  if (!clientId) validationErrors.EDGE_CLIENT_ID = ["Required"];
+  if (!clientSecret) validationErrors.EDGE_CLIENT_SECRET = ["Required"];
+  if (Object.keys(validationErrors).length > 0) {
+    throw new EdgeValidationError4("Missing required EDGE Connect environment variables", validationErrors);
+  }
+  if (mtlsRequiredByTarget && !mtls) {
+    warnings.push(
+      `EDGE_ENVIRONMENT=${environment} uses an mTLS-enforced EDGE Connect target; configure EDGE_MTLS_CERT and EDGE_MTLS_KEY before making API calls.`
+    );
+  }
+  const config = {
+    clientId,
+    clientSecret,
+    environment,
+    ...apiBaseUrl ? { apiBaseUrl } : {},
+    ...oauthBaseUrl ? { oauthBaseUrl } : {},
+    ...partnerApiBaseUrl ? { partnerApiBaseUrl } : {},
+    ...partnerClientId ? { partnerClientId } : {},
+    ...partnerClientSecret ? { partnerClientSecret } : {},
+    ...timeout ? { timeout } : {},
+    ...options.retry ? { retry: options.retry } : {},
+    ...options.onRequest ? { onRequest: options.onRequest } : {},
+    ...options.onResponse ? { onResponse: options.onResponse } : {},
+    ...options.mle ? { mle: options.mle } : {},
+    ...mtls ? { mtls } : {}
+  };
+  const server = new EdgeConnectServer(config);
+  return {
+    server,
+    config,
+    capabilities: {
+      mtlsEnabled: !!config.mtls?.enabled,
+      webhookSyncConfigured: !!config.partnerClientId && !!config.partnerClientSecret,
+      customApiBaseUrl: !!config.apiBaseUrl,
+      customOAuthBaseUrl: !!config.oauthBaseUrl,
+      customPartnerApiBaseUrl: !!config.partnerApiBaseUrl
+    },
+    warnings
+  };
+}
+
+// src/error-adapter.ts
+import {
+  EdgeConsentRequiredError as EdgeConsentRequiredError2,
+  EdgeError as EdgeError2,
+  EdgeIdentityVerificationError as EdgeIdentityVerificationError2,
+  EdgeNetworkError as EdgeNetworkError2,
+  EdgeValidationError as EdgeValidationError5
+} from "@edge-markets/connect";
+function toEdgeHttpError(error) {
+  const body = toEdgeProblemJson(error);
+  return { status: body.status, body };
+}
+function toEdgeProblemJson(error) {
+  if (error instanceof EdgeConsentRequiredError2) {
+    return problem(error, "Consent required", error.statusCode ?? 403, {
+      clientId: error.clientId,
+      consentUrl: error.consentUrl
+    });
+  }
+  if (error instanceof EdgeValidationError5) {
+    return problem(error, "Validation failed", error.statusCode ?? 400, {
+      validationErrors: error.validationErrors
+    });
+  }
+  if (error instanceof EdgeIdentityVerificationError2) {
+    return problem(error, "Identity verification failed", error.statusCode ?? 422, {
+      fieldErrors: error.fieldErrors
+    });
+  }
+  if (error instanceof EdgeNetworkError2) {
+    return problem(error, "EDGE network error", error.statusCode ?? 502);
+  }
+  if (error instanceof EdgeError2) {
+    return problem(error, edgeTitle(error), error.statusCode ?? 500, error.details);
+  }
+  const message = error instanceof Error ? error.message : "Unexpected error";
+  return {
+    type: "https://developer.edgemarkets.io/errors/internal_error",
+    title: "Internal error",
+    status: 500,
+    detail: message,
+    code: "internal_error"
+  };
+}
+function problem(error, title, status, details) {
+  return {
+    type: `https://developer.edgemarkets.io/errors/${error.code}`,
+    title,
+    status,
+    detail: error.message,
+    code: error.code,
+    ...details && Object.keys(details).length > 0 ? { details } : {}
+  };
+}
+function edgeTitle(error) {
+  return error.code.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+// src/identity.ts
+import { EdgeValidationError as EdgeValidationError6 } from "@edge-markets/connect";
+var DEFAULT_IDENTITY_POLICY = {
+  minNameScore: 70,
+  minAddressScore: 65,
+  requireZipMatch: true,
+  requireApiVerified: true
+};
+function buildVerifyIdentityPayload(profile) {
+  const firstName = firstNonEmpty(profile.firstName, profile.givenName);
+  const lastName = firstNonEmpty(profile.lastName, profile.familyName);
+  const address = profile.address ?? {};
+  const payload = {
+    firstName,
+    lastName,
+    address: {
+      street: firstNonEmpty(address.street, address.line1, address.address1),
+      city: firstNonEmpty(address.city),
+      state: firstNonEmpty(address.state),
+      zip: firstNonEmpty(address.zip, address.postalCode)
+    }
+  };
+  const errors = {};
+  if (!payload.firstName) errors.firstName = ["Required"];
+  if (!payload.lastName) errors.lastName = ["Required"];
+  if (!Object.values(payload.address).some((value) => !!value)) {
+    errors.address = ["At least one address field is required"];
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError6("Partner identity profile is incomplete", errors);
+  }
+  return payload;
+}
+function evaluateIdentityResult(result, policy = {}) {
+  const resolved = { ...DEFAULT_IDENTITY_POLICY, ...policy };
+  validatePolicy(resolved);
+  const reasons = [];
+  const verifiedFlag = result.verified;
+  if (resolved.requireApiVerified && verifiedFlag !== true) {
+    reasons.push("api_not_verified");
+  }
+  const scores = result.scores;
+  if (!scores) {
+    reasons.push("scores_missing");
+  } else {
+    if (typeof scores.name === "number" && scores.name < resolved.minNameScore) {
+      reasons.push("name_score_below_threshold");
+    }
+    if (typeof scores.address === "number" && scores.address < resolved.minAddressScore) {
+      reasons.push("address_score_below_threshold");
+    }
+    if (resolved.requireZipMatch && scores.zipMatch !== true) {
+      reasons.push("zip_mismatch");
+    }
+  }
+  return {
+    verified: reasons.length === 0,
+    reasons,
+    ...scores ? { scores } : {}
+  };
+}
+function validatePolicy(policy) {
+  const errors = {};
+  if (!isScore(policy.minNameScore)) errors.minNameScore = ["Must be between 0 and 100"];
+  if (!isScore(policy.minAddressScore)) errors.minAddressScore = ["Must be between 0 and 100"];
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError6("Invalid identity policy", errors);
+  }
+}
+function isScore(value) {
+  return Number.isFinite(value) && value >= 0 && value <= 100;
+}
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return "";
+}
+
+// src/token-vault.ts
+import { EdgeValidationError as EdgeValidationError7 } from "@edge-markets/connect";
+import crypto2 from "crypto";
+var TOKEN_VAULT_VERSION = "edge_vault_v1";
+var IV_BYTES = 12;
+var TAG_BYTES = 16;
+var KEY_BYTES = 32;
+var EdgeTokenVault = class {
+  constructor(options) {
+    this.currentKey = normalizeVaultKey(options.currentKey, "currentKey");
+    this.keysById = /* @__PURE__ */ new Map([[this.currentKey.id, this.currentKey.key]]);
+    for (const [index, key] of (options.previousKeys ?? []).entries()) {
+      const normalized = normalizeVaultKey(key, `previousKeys[${index}]`);
+      if (this.keysById.has(normalized.id)) {
+        throw new EdgeValidationError7("Duplicate token vault key ID", {
+          keyId: [`Duplicate key ID "${normalized.id}"`]
+        });
+      }
+      this.keysById.set(normalized.id, normalized.key);
+    }
+  }
+  encryptTokens(tokens) {
+    validateEdgeTokens(tokens);
+    const iv = crypto2.randomBytes(IV_BYTES);
+    const aad = Buffer.from(`${TOKEN_VAULT_VERSION}.${this.currentKey.id}`, "utf8");
+    const cipher = crypto2.createCipheriv("aes-256-gcm", this.currentKey.key, iv);
+    cipher.setAAD(aad);
+    const plaintext = Buffer.from(JSON.stringify(tokens), "utf8");
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [
+      TOKEN_VAULT_VERSION,
+      toBase64Url2(Buffer.from(this.currentKey.id, "utf8")),
+      toBase64Url2(iv),
+      toBase64Url2(tag),
+      toBase64Url2(ciphertext)
+    ].join(".");
+  }
+  decryptTokens(envelope) {
+    const parsed = parseEnvelope(envelope);
+    const key = this.keysById.get(parsed.keyId);
+    if (!key) {
+      throw new EdgeValidationError7("Unknown token vault key ID", {
+        keyId: [`No key configured for "${parsed.keyId}"`]
+      });
+    }
+    try {
+      const decipher = crypto2.createDecipheriv("aes-256-gcm", key, parsed.iv);
+      decipher.setAAD(Buffer.from(`${TOKEN_VAULT_VERSION}.${parsed.keyId}`, "utf8"));
+      decipher.setAuthTag(parsed.tag);
+      const plaintext = Buffer.concat([decipher.update(parsed.ciphertext), decipher.final()]).toString("utf8");
+      const tokens = JSON.parse(plaintext);
+      validateEdgeTokens(tokens);
+      return tokens;
+    } catch (error) {
+      if (error instanceof EdgeValidationError7) throw error;
+      throw new EdgeValidationError7("Failed to decrypt EDGE tokens", {
+        tokenEnvelope: ["Envelope is malformed, corrupted, or encrypted with a different key"]
+      });
+    }
+  }
+  isEncrypted(value) {
+    return typeof value === "string" && value.startsWith(`${TOKEN_VAULT_VERSION}.`);
+  }
+};
+function createEdgeTokenVault(options) {
+  return new EdgeTokenVault(options);
+}
+function isEdgeTokenVaultEnvelope(value) {
+  return typeof value === "string" && value.startsWith(`${TOKEN_VAULT_VERSION}.`);
+}
+function normalizeVaultKey(input, fieldName) {
+  const id = typeof input.id === "string" ? input.id.trim() : "";
+  if (!id) {
+    throw new EdgeValidationError7("Token vault key ID is required", {
+      [`${fieldName}.id`]: ["Required"]
+    });
+  }
+  return {
+    id,
+    key: normalizeKeyMaterial(input.key, `${fieldName}.key`)
+  };
+}
+function normalizeKeyMaterial(input, fieldName) {
+  const candidates = [];
+  if (Buffer.isBuffer(input)) {
+    candidates.push(input);
+  } else if (input instanceof Uint8Array) {
+    candidates.push(Buffer.from(input));
+  } else if (typeof input === "string") {
+    const value = input.trim();
+    if (value.startsWith("base64:")) {
+      candidates.push(Buffer.from(value.slice("base64:".length), "base64"));
+    } else if (value.startsWith("base64url:")) {
+      candidates.push(fromBase64Url2(value.slice("base64url:".length)));
+    } else if (/^[0-9a-f]{64}$/i.test(value)) {
+      candidates.push(Buffer.from(value, "hex"));
+    } else {
+      candidates.push(Buffer.from(value, "base64"));
+      candidates.push(fromBase64Url2(value));
+      candidates.push(Buffer.from(value, "utf8"));
+    }
+  }
+  const key = candidates.find((candidate) => candidate.length === KEY_BYTES);
+  if (!key) {
+    throw new EdgeValidationError7("Token vault key must decode to 32 bytes", {
+      [fieldName]: ["Provide a 32-byte key as base64, base64url, hex, Buffer, or Uint8Array"]
+    });
+  }
+  return key;
+}
+function validateEdgeTokens(tokens) {
+  const errors = {};
+  if (!tokens || typeof tokens !== "object") {
+    errors.tokens = ["Expected token object"];
+  } else {
+    if (typeof tokens.accessToken !== "string" || !tokens.accessToken) {
+      errors.accessToken = ["Required"];
+    }
+    if (typeof tokens.refreshToken !== "string" || !tokens.refreshToken) {
+      errors.refreshToken = ["Required"];
+    }
+    if (typeof tokens.expiresIn !== "number" || !Number.isFinite(tokens.expiresIn) || tokens.expiresIn <= 0) {
+      errors.expiresIn = ["Must be a positive number"];
+    }
+    if (typeof tokens.expiresAt !== "number" || !Number.isFinite(tokens.expiresAt) || tokens.expiresAt <= 0) {
+      errors.expiresAt = ["Must be a positive Unix timestamp in milliseconds"];
+    }
+    if (typeof tokens.scope !== "string") {
+      errors.scope = ["Required"];
+    }
+    if (tokens.idToken !== void 0 && typeof tokens.idToken !== "string") {
+      errors.idToken = ["Must be a string when provided"];
+    }
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError7("Invalid EDGE token payload", errors);
+  }
+}
+function parseEnvelope(envelope) {
+  if (typeof envelope !== "string") {
+    throw new EdgeValidationError7("Token envelope must be a string", {
+      tokenEnvelope: ["Expected string"]
+    });
+  }
+  const parts = envelope.split(".");
+  if (parts.length !== 5 || parts[0] !== TOKEN_VAULT_VERSION) {
+    throw new EdgeValidationError7("Invalid EDGE token vault envelope", {
+      tokenEnvelope: [`Expected ${TOKEN_VAULT_VERSION}.<keyId>.<iv>.<tag>.<ciphertext>`]
+    });
+  }
+  const [, encodedKeyId, encodedIv, encodedTag, encodedCiphertext] = parts;
+  const keyId = fromBase64Url2(encodedKeyId).toString("utf8");
+  const iv = fromBase64Url2(encodedIv);
+  const tag = fromBase64Url2(encodedTag);
+  const ciphertext = fromBase64Url2(encodedCiphertext);
+  const errors = {};
+  if (!keyId) errors.keyId = ["Required"];
+  if (iv.length !== IV_BYTES) errors.iv = [`Must be ${IV_BYTES} bytes`];
+  if (tag.length !== TAG_BYTES) errors.tag = [`Must be ${TAG_BYTES} bytes`];
+  if (ciphertext.length === 0) errors.ciphertext = ["Required"];
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError7("Invalid EDGE token vault envelope", errors);
+  }
+  return { keyId, iv, tag, ciphertext };
+}
+function toBase64Url2(value) {
+  return value.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function fromBase64Url2(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  return Buffer.from(normalized + padding, "base64");
+}
+
+// src/webhook-guards.ts
+import { EdgeValidationError as EdgeValidationError8 } from "@edge-markets/connect";
+function isTransferWebhookEvent(event) {
+  return event.type.startsWith("transfer.");
+}
+function assertTransferEventMatchesIntent(event, intent) {
+  if (!isTransferWebhookEvent(event)) {
+    throw new EdgeValidationError8("Webhook event is not a transfer event", {
+      type: [`Received ${event.type}`]
+    });
+  }
+  const data = event.data;
+  const errors = {};
+  if (data.transferId !== intent.transferId) {
+    errors.transferId = [`Expected ${intent.transferId}, received ${data.transferId}`];
+  }
+  if (intent.type && data.type !== intent.type) {
+    errors.type = [`Expected ${intent.type}, received ${data.type}`];
+  }
+  if (intent.status && data.status !== intent.status) {
+    errors.status = [`Expected ${intent.status}, received ${data.status}`];
+  }
+  if (intent.amount !== void 0) {
+    const expectedAmount = normalizeMoneyAmount(intent.amount);
+    const receivedAmount = normalizeMoneyAmount(data.amount);
+    if (receivedAmount !== expectedAmount) {
+      errors.amount = [`Expected ${expectedAmount}, received ${receivedAmount}`];
+    }
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError8("Webhook transfer event does not match expected transfer intent", errors);
+  }
+}
+
+// src/webhook-parser.ts
+import {
+  EDGE_WEBHOOK_EVENT_TYPES,
+  EdgeAuthenticationError as EdgeAuthenticationError3,
+  EdgeValidationError as EdgeValidationError9
+} from "@edge-markets/connect";
+
 // src/webhook-signing.ts
-import crypto from "crypto";
+import crypto3 from "crypto";
 function verifyWebhookSignature(header, body, secret, options = {}) {
   if (typeof header !== "string" || typeof body !== "string" || typeof secret !== "string") {
     return false;
@@ -800,28 +1846,180 @@ function verifyWebhookSignature(header, body, secret, options = {}) {
   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");
+  const expectedHmac = crypto3.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);
+    return crypto3.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
+// src/webhook-parser.ts
+var EVENT_TYPES = new Set(EDGE_WEBHOOK_EVENT_TYPES);
+var TRANSFER_TYPES = /* @__PURE__ */ new Set(["debit", "credit"]);
+function parseAndVerifyWebhook(options) {
+  const body = normalizeRawBody(options.rawBody);
+  const header = normalizeSignatureHeader(options.signatureHeader);
+  const signatureTimestamp = extractWebhookSignatureTimestamp(header);
+  if (!header || !signatureTimestamp) {
+    throw new EdgeAuthenticationError3("Missing or malformed EDGE webhook signature");
+  }
+  if (!verifyWebhookSignature(header, body, options.secret, { toleranceSeconds: options.toleranceSeconds })) {
+    throw new EdgeAuthenticationError3("Invalid EDGE webhook signature");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new EdgeValidationError9("EDGE webhook body must be valid JSON", {
+      rawBody: ["Unable to parse JSON after signature verification"]
+    });
+  }
+  const event = validateEdgeWebhookEvent(parsed);
+  return {
+    event,
+    eventId: event.id,
+    eventType: event.type,
+    signatureTimestamp,
+    receivedAt: options.receivedAt ?? /* @__PURE__ */ new Date()
+  };
+}
+function extractWebhookSignatureTimestamp(header) {
+  const normalizedHeader = normalizeSignatureHeader(header);
+  if (!normalizedHeader) return void 0;
+  const part = normalizedHeader.split(",").map((value) => value.trim()).find((value) => value.startsWith("t="));
+  if (!part) return void 0;
+  const timestamp = Number(part.slice(2));
+  if (!Number.isInteger(timestamp) || timestamp <= 0) return void 0;
+  return timestamp;
+}
+function isEdgeWebhookEvent(value) {
+  try {
+    validateEdgeWebhookEvent(value);
+    return true;
   } catch {
     return false;
   }
 }
+function validateEdgeWebhookEvent(value) {
+  const errors = {};
+  if (!isRecord(value)) {
+    throw new EdgeValidationError9("EDGE webhook event must be an object", {
+      event: ["Expected JSON object"]
+    });
+  }
+  const id = value.id;
+  const type = value.type;
+  const createdAt = value.created_at;
+  const data = value.data;
+  if (typeof id !== "string" || !id.trim()) {
+    errors.id = ["Required string"];
+  }
+  if (typeof type !== "string" || !EVENT_TYPES.has(type)) {
+    errors.type = [`Must be one of: ${EDGE_WEBHOOK_EVENT_TYPES.join(", ")}`];
+  }
+  if (typeof createdAt !== "string" || !createdAt.trim() || Number.isNaN(Date.parse(createdAt))) {
+    errors.created_at = ["Required ISO 8601 timestamp string"];
+  }
+  if (!isRecord(data)) {
+    errors.data = ["Required object"];
+  }
+  if (Object.keys(errors).length === 0) {
+    validateKnownEventData(type, data, errors);
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError9("Invalid EDGE webhook event", errors);
+  }
+  return value;
+}
+function validateKnownEventData(type, data, errors) {
+  switch (type) {
+    case "transfer.completed":
+      validateTransferEventData(data, "completed", errors);
+      return;
+    case "transfer.failed":
+      validateTransferEventData(data, "failed", errors);
+      if (data.reason !== void 0 && typeof data.reason !== "string") {
+        errors["data.reason"] = ["Must be a string when provided"];
+      }
+      return;
+    case "transfer.expired":
+      validateTransferEventData(data, "expired", errors);
+      return;
+    case "transfer.processing":
+      validateTransferEventData(data, "processing", errors);
+      return;
+    case "consent.revoked":
+      validateRequiredString(data, "userId", errors);
+      validateRequiredString(data, "clientId", errors);
+      validateRequiredIsoTimestamp(data, "revokedAt", errors);
+      return;
+    default: {
+      const exhaustive = type;
+      throw new EdgeValidationError9("Unsupported EDGE webhook event type", {
+        type: [`Unsupported event type: ${exhaustive}`]
+      });
+    }
+  }
+}
+function validateTransferEventData(data, status, errors) {
+  validateRequiredString(data, "transferId", errors);
+  if (data.status !== status) {
+    errors["data.status"] = [`Must be "${status}" for this event type`];
+  }
+  if (typeof data.type !== "string" || !TRANSFER_TYPES.has(data.type)) {
+    errors["data.type"] = ['Must be "debit" or "credit"'];
+  }
+  validateRequiredString(data, "amount", errors);
+}
+function validateRequiredString(data, field, errors) {
+  if (typeof data[field] !== "string" || !data[field].trim()) {
+    errors[`data.${field}`] = ["Required string"];
+  }
+}
+function validateRequiredIsoTimestamp(data, field, errors) {
+  if (typeof data[field] !== "string" || !data[field].trim() || Number.isNaN(Date.parse(data[field]))) {
+    errors[`data.${field}`] = ["Required ISO 8601 timestamp string"];
+  }
+}
+function normalizeRawBody(rawBody) {
+  if (typeof rawBody === "string") {
+    return rawBody;
+  }
+  if (Buffer.isBuffer(rawBody) || rawBody instanceof Uint8Array) {
+    return Buffer.from(rawBody).toString("utf8");
+  }
+  throw new EdgeValidationError9("EDGE webhook raw body is required", {
+    rawBody: ["Pass the raw UTF-8 request body, not a parsed JSON object"]
+  });
+}
+function normalizeSignatureHeader(header) {
+  if (Array.isArray(header)) {
+    return header.map((value) => value.trim()).filter(Boolean).join(",");
+  }
+  if (typeof header !== "string") return void 0;
+  const trimmed = header.trim();
+  return trimmed || void 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
 
 // src/index.ts
 import {
   EdgeApiError as EdgeApiError2,
-  EdgeAuthenticationError as EdgeAuthenticationError2,
-  EdgeConsentRequiredError as EdgeConsentRequiredError2,
-  EdgeError as EdgeError2,
-  EdgeIdentityVerificationError as EdgeIdentityVerificationError2,
+  EdgeAuthenticationError as EdgeAuthenticationError4,
+  EdgeConsentRequiredError as EdgeConsentRequiredError3,
+  EdgeError as EdgeError3,
+  EdgeIdentityVerificationError as EdgeIdentityVerificationError3,
   EdgeInsufficientScopeError as EdgeInsufficientScopeError2,
-  EdgeNetworkError as EdgeNetworkError2,
+  EdgeNetworkError as EdgeNetworkError3,
   EdgeNotFoundError as EdgeNotFoundError2,
   EdgeTokenExchangeError as EdgeTokenExchangeError2,
+  EdgeValidationError as EdgeValidationError10,
   isApiError,
   isAuthenticationError,
   isConsentRequiredError,
@@ -830,32 +2028,56 @@ import {
   isNetworkError
 } from "@edge-markets/connect";
 import {
-  EDGE_WEBHOOK_EVENT_TYPES,
+  EDGE_WEBHOOK_EVENT_TYPES as EDGE_WEBHOOK_EVENT_TYPES2,
   TRANSFER_CATEGORIES,
-  getEnvironmentConfig as getEnvironmentConfig2,
+  getEnvironmentConfig as getEnvironmentConfig3,
   isProductionEnvironment
 } from "@edge-markets/connect";
 export {
-  EDGE_WEBHOOK_EVENT_TYPES,
+  EDGE_WEBHOOK_EVENT_TYPES2 as EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError2 as EdgeApiError,
-  EdgeAuthenticationError2 as EdgeAuthenticationError,
+  EdgeAuthenticationError4 as EdgeAuthenticationError,
   EdgeConnectServer,
-  EdgeConsentRequiredError2 as EdgeConsentRequiredError,
-  EdgeError2 as EdgeError,
-  EdgeIdentityVerificationError2 as EdgeIdentityVerificationError,
+  EdgeConsentRequiredError3 as EdgeConsentRequiredError,
+  EdgeError3 as EdgeError,
+  EdgeIdentityVerificationError3 as EdgeIdentityVerificationError,
   EdgeInsufficientScopeError2 as EdgeInsufficientScopeError,
-  EdgeNetworkError2 as EdgeNetworkError,
+  EdgeNetworkError3 as EdgeNetworkError,
   EdgeNotFoundError2 as EdgeNotFoundError,
   EdgeTokenExchangeError2 as EdgeTokenExchangeError,
+  EdgeTokenVault,
   EdgeUserClient,
+  EdgeUserSession,
+  EdgeValidationError10 as EdgeValidationError,
+  EdgeWebhookReconciler,
   TRANSFER_CATEGORIES,
-  getEnvironmentConfig2 as getEnvironmentConfig,
+  assertSameTransferIntent,
+  assertTransferEventMatchesIntent,
+  buildVerifyIdentityPayload,
+  createEdgeConnectServerFromEnv,
+  createEdgeTokenVault,
+  createEdgeUserSession,
+  createTransferIdempotencyKey,
+  createWebhookReconciler,
+  evaluateIdentityResult,
+  extractWebhookSignatureTimestamp,
+  getEnvironmentConfig3 as getEnvironmentConfig,
   isApiError,
   isAuthenticationError,
   isConsentRequiredError,
   isEdgeError,
+  isEdgeTokenVaultEnvelope,
+  isEdgeWebhookEvent,
   isIdentityVerificationError,
   isNetworkError,
   isProductionEnvironment,
+  isTransferWebhookEvent,
+  normalizeMoneyAmount,
+  parseAndVerifyWebhook,
+  startTransferVerification,
+  toEdgeHttpError,
+  toEdgeProblemJson,
+  validateEdgeWebhookEvent,
+  validateTransferAmount,
   verifyWebhookSignature
 };