@edge-markets/connect-node 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as node_https from 'node:https';
-import { EdgeEnvironment, TransferCategory, SdkGeolocation, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens } from '@edge-markets/connect';
-export { Balance, CreateVerificationSessionRequest, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferList, TransferListItem, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
+import { EdgeEnvironment, TransferCategory, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent } from '@edge-markets/connect';
+export { Balance, BaseWebhookEvent, ConsentRevokedEventData, CreateVerificationSessionRequest, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, EdgeWebhookEvent, EdgeWebhookEventType, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferCompletedEventData, TransferExpiredEventData, TransferFailedEventData, TransferList, TransferListItem, TransferProcessingEventData, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 interface RequestInfo {
     method: string;
@@ -42,6 +42,24 @@ interface EdgeConnectServerConfig {
         strictResponseEncryption?: boolean;
     };
     mtls?: MtlsConfig;
+    /**
+     * Partner-level OAuth client ID for the `client_credentials` grant.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     * This is a different OAuth client than {@link clientId} — it authenticates
+     * your backend (not your users) for partner-scoped surfaces like the
+     * webhook reconciliation sync endpoint.
+     *
+     * If omitted, `syncWebhookEvents()` throws on first call but the rest of
+     * the SDK (token exchange, user-scoped API calls) continues to work.
+     */
+    partnerClientId?: string;
+    /**
+     * Partner-level OAuth client secret paired with {@link partnerClientId}.
+     *
+     * Required ONLY when calling {@link EdgeConnectServer.syncWebhookEvents}.
+     */
+    partnerClientSecret?: string;
 }
 interface MtlsConfig {
     enabled: boolean;
@@ -56,13 +74,6 @@ interface TransferOptions {
     /** Optional transaction category for settlement window determination */
     category?: TransferCategory;
 }
-/**
- * Options for verifying a transfer with OTP.
- */
-interface VerifyTransferOptions {
-    /** SDK-reported geolocation for cross-referencing against IP-based geo */
-    sdkGeo?: SdkGeolocation;
-}
 
 /**
  * A lightweight, user-scoped API client created via {@link EdgeConnectServer.forUser}.
@@ -78,7 +89,6 @@ declare class EdgeUserClient {
     verifyIdentity(options: VerifyIdentityOptions): Promise<VerifyIdentityResult>;
     getBalance(): Promise<Balance>;
     initiateTransfer(options: TransferOptions): Promise<Transfer>;
-    verifyTransfer(transferId: string, otp: string, options?: VerifyTransferOptions): Promise<Transfer>;
     getTransfer(transferId: string): Promise<Transfer>;
     listTransfers(params?: ListTransfersParams): Promise<TransferList>;
     revokeConsent(): Promise<{
@@ -97,6 +107,38 @@ declare class EdgeUserClient {
     getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
+/**
+ * Options for {@link EdgeConnectServer.syncWebhookEvents}.
+ */
+interface SyncWebhookEventsOptions {
+    /**
+     * Cursor token. Pass the `id` of the last event you successfully processed
+     * to receive only newer events. Omit on the first call to start from the
+     * beginning of the 30-day server-side lookback window.
+     */
+    afterEventId?: string;
+    /**
+     * Maximum events per page (1–100). Defaults to 20 server-side.
+     */
+    limit?: number;
+}
+/**
+ * Result of {@link EdgeConnectServer.syncWebhookEvents}. Field names are
+ * normalized to camelCase from the wire format (`has_more` → `hasMore`).
+ */
+interface SyncWebhookEventsResult {
+    /**
+     * Events newer than the supplied cursor, in ascending order. Each event
+     * is the unwrapped {@link EdgeWebhookEvent} payload (the SDK strips the
+     * sync API's outer envelope).
+     */
+    events: EdgeWebhookEvent[];
+    /**
+     * `true` if more events are available beyond this page. Loop while this
+     * is truthy, advancing your cursor to the `id` of the last processed event.
+     */
+    hasMore: boolean;
+}
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
@@ -105,6 +147,7 @@ declare class EdgeConnectServer {
     private readonly retryConfig;
     private readonly httpsAgent;
     private readonly dispatcher;
+    private partnerTokenCache;
     static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
     static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
@@ -124,6 +167,67 @@ declare class EdgeConnectServer {
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
     /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
     _apiRequest<T>(method: string, path: string, accessToken: string, body?: unknown): Promise<T>;
+    /**
+     * 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
+     */
+    syncWebhookEvents(options?: SyncWebhookEventsOptions): Promise<SyncWebhookEventsResult>;
+    /**
+     * Builds the sync URL with normalized query parameters.
+     */
+    private buildSyncUrl;
+    /**
+     * 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.
+     */
+    private partnerFetch;
+    /**
+     * 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.
+     */
+    private getPartnerToken;
+    /**
+     * @internal Test-only: clears the cached partner token so the next call
+     * to `syncWebhookEvents` re-fetches it. Not part of the public API.
+     */
+    _resetPartnerTokenCache(): void;
     private getRetryDelay;
     private sleep;
     private fetchWithTimeout;
@@ -132,4 +236,68 @@ declare class EdgeConnectServer {
     private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions, type VerifyTransferOptions };
+/**
+ * Webhook Signature Verification (SDK-001)
+ *
+ * HMAC-SHA256 verification for EDGE Connect webhook payloads.
+ *
+ * Signature header format: `t={timestamp},v1={hex_hmac}`
+ * Signed message: `{timestamp}.{raw_json_body}`
+ *
+ * The timestamp prefix prevents replay attacks — events older than the
+ * tolerance window (default 5 minutes) are rejected. The HMAC is verified
+ * with constant-time comparison to prevent timing attacks.
+ */
+/**
+ * Options for {@link verifyWebhookSignature}.
+ */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * Maximum age of the signature timestamp, in seconds.
+     *
+     * Signatures older than this are rejected as potential replays.
+     * Defaults to 300 seconds (5 minutes), matching the producer.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verifies an EDGE Connect webhook signature.
+ *
+ * **Always pass the raw request body bytes** — never `JSON.stringify(req.body)`.
+ * Re-stringifying after the framework parses JSON will reorder keys, change
+ * whitespace, and silently break verification with no diagnostic. Capture
+ * the raw body via your framework's raw-body middleware:
+ *
+ * - Express: `express.raw({ type: 'application/json' })`
+ * - Fastify: built-in (use `request.rawBody`)
+ * - NestJS: `{ rawBody: true }` on `NestFactory.create` + `RawBodyRequest<Request>`
+ *
+ * @param header - The `X-Edge-Signature` header value (`t=...,v1=...`)
+ * @param body - The raw request body as a UTF-8 string (NOT a parsed object)
+ * @param secret - The partner's webhook signing secret
+ * @param options - Optional overrides
+ * @returns `true` if the signature is valid and within the tolerance window,
+ *          `false` otherwise. Never throws — malformed input returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@edge-markets/connect-node'
+ *
+ * app.post('/webhooks/edge', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const ok = verifyWebhookSignature(
+ *     req.headers['x-edge-signature'] as string,
+ *     req.body.toString('utf8'),
+ *     process.env.EDGE_WEBHOOK_SECRET!,
+ *   )
+ *
+ *   if (!ok) return res.status(401).send('invalid signature')
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'))
+ *   // ... process event
+ *   res.status(200).send('ok')
+ * })
+ * ```
+ */
+declare function verifyWebhookSignature(header: string, body: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;
+
+export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferOptions, type VerifyWebhookSignatureOptions, verifyWebhookSignature };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  EDGE_WEBHOOK_EVENT_TYPES: () => import_connect4.EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError: () => import_connect3.EdgeApiError,
   EdgeAuthenticationError: () => import_connect3.EdgeAuthenticationError,
   EdgeConnectServer: () => EdgeConnectServer,
@@ -49,7 +50,8 @@ __export(index_exports, {
   isEdgeError: () => import_connect3.isEdgeError,
   isIdentityVerificationError: () => import_connect3.isIdentityVerificationError,
   isNetworkError: () => import_connect3.isNetworkError,
-  isProductionEnvironment: () => import_connect4.isProductionEnvironment
+  isProductionEnvironment: () => import_connect4.isProductionEnvironment,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -58,6 +60,14 @@ var import_connect2 = require("@edge-markets/connect");
 
 // src/validators.ts
 var import_connect = require("@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 import_connect.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() : "";
@@ -134,19 +144,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) {
@@ -167,6 +166,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`,
@@ -179,6 +179,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)}`,
@@ -308,19 +309,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");
     }
@@ -343,8 +356,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.
@@ -515,6 +543,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 import_connect2.EdgeAuthenticationError("syncWebhookEvents requires `partnerClientId` in EdgeConnectServer config");
+    }
+    if (!this.config.partnerClientSecret) {
+      throw new import_connect2.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 import_connect2.EdgeAuthenticationError(
+          body.message || "Partner token rejected after refresh \u2014 check partnerClientId/Secret",
+          body
+        );
+      }
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new import_connect2.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 import_connect2.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 import_connect2.EdgeNetworkError("Partner token request network failure", error);
+    }
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new import_connect2.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 import_connect2.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") {
@@ -624,11 +821,41 @@ var EdgeConnectServer = class _EdgeConnectServer {
   }
 };
 
+// src/webhook-signing.ts
+var import_node_crypto = __toESM(require("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 = import_node_crypto.default.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 import_node_crypto.default.timingSafeEqual(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var import_connect3 = require("@edge-markets/connect");
 var import_connect4 = require("@edge-markets/connect");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError,
   EdgeAuthenticationError,
   EdgeConnectServer,
@@ -648,5 +875,6 @@ var import_connect4 = require("@edge-markets/connect");
   isEdgeError,
   isIdentityVerificationError,
   isNetworkError,
-  isProductionEnvironment
+  isProductionEnvironment,
+  verifyWebhookSignature
 });