@edge-markets/connect-node 1.6.0 → 1.7.0

package/README.md

@@ -9,6 +9,8 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 📡 **Full API client** - User, balance, transfers via `forUser()` pattern
 - 🛡️ **Typed errors** - Specific error classes for each scenario
 - 📝 **TypeScript first** - Complete type definitions
+- 🪝 **Webhook signature verification** - Constant-time HMAC-SHA256 with replay protection
+- 🔁 **Webhook reconciliation** - Cursor-based sync for catching missed events
 
 ## Installation
 
@@ -51,10 +53,10 @@ Never expose your client secret to browsers or client-side code.
 
 ```typescript
 interface EdgeConnectServerConfig {
-  clientId: string              // Your OAuth client ID
-  clientSecret: string          // Your OAuth client secret (keep secret!)
+  clientId: string              // Your user-facing OAuth client ID
+  clientSecret: string          // Your user-facing OAuth client secret (keep secret!)
   environment: EdgeEnvironment  // 'production' | 'staging' | 'sandbox'
-  
+
   // Optional
   apiBaseUrl?: string           // Custom API URL (dev only)
   oauthBaseUrl?: string         // Custom OAuth URL (dev only)
@@ -63,6 +65,13 @@ interface EdgeConnectServerConfig {
   onRequest?: (info) => void    // Hook called before each request
   onResponse?: (info) => void   // Hook called after each response
 
+  // Optional: Partner-level credentials for non-user-scoped endpoints.
+  // Required ONLY when calling syncWebhookEvents — the rest of the SDK
+  // works without them. These are a DIFFERENT OAuth client than clientId
+  // (machine-to-machine, not user-facing).
+  partnerClientId?: string
+  partnerClientSecret?: string
+
   // Optional: Message Level Encryption (Connect endpoints only)
   mle?: {
     enabled: boolean
@@ -175,7 +184,7 @@ const balance = await client.getBalance()
 ### Transfers
 
 ```typescript
-// Initiate transfer (requires OTP verification)
+// 1. Initiate the transfer — returns a pending transfer that requires verification.
 const transfer = await client.initiateTransfer({
   type: 'debit',           // 'debit' = pull from user, 'credit' = push to user
   amount: '100.00',
@@ -183,12 +192,25 @@ const transfer = await client.initiateTransfer({
 })
 // Returns: { transferId, status: 'pending_verification', otpMethod }
 
-// Verify with OTP
-const result = await client.verifyTransfer(transfer.transferId, userOtp)
-// Returns: { transferId, status: 'completed' | 'failed' }
+// 2. Create an EDGE-hosted verification session. The returned `verificationUrl`
+//    is a single-use, short-lived URL you embed in an iframe or popup on your
+//    frontend. The user enters their OTP inside the EDGE-hosted UI — OTP secrets
+//    never touch your infrastructure.
+const session = await client.createVerificationSession(transfer.transferId, {
+  origin: 'https://your-site.example.com',
+})
+// Returns: { sessionId, verificationUrl, expiresAt }
+
+// 3. Listen for the postMessage event from the iframe (or poll
+//    getVerificationSessionStatus) to learn when verification completes.
+//    A `transfer.completed` webhook will be delivered to your configured
+//    webhook URL once the transfer settles. For browser-crash recovery,
+//    your backend should also reconcile against
+//    GET /v1/partner/webhooks/events/sync using a dashboard
+//    client_credentials token from POST /connect/oauth/token.
 
 // Get transfer status
-const status = await client.getTransfer(transferId)
+const status = await client.getTransfer(transfer.transferId)
 
 // List transfers
 const { transfers, total } = await client.listTransfers({
@@ -208,6 +230,172 @@ await client.revokeConsent()
 await db.edgeConnections.delete(userId)
 ```
 
+## Webhooks
+
+EDGE Connect delivers webhook events to your server when transfers complete,
+fail, expire, or when a user revokes consent. The SDK provides two helpers:
+**signature verification** for the live HTTP delivery channel, and a
+**reconciliation sync method** for the cron-driven safety net.
+
+### Verify webhook signatures
+
+Every webhook arrives with an `X-Edge-Signature` header in `t=...,v1=...`
+format — HMAC-SHA256 over `${timestamp}.${rawBody}` keyed by your webhook
+secret. Use `verifyWebhookSignature` to check it. The function does
+constant-time comparison and rejects events older than 5 minutes by default
+to prevent replay attacks.
+
+> ⚠️ **The `body` argument MUST be the raw request bytes**, not a parsed
+> object that you re-stringified. `JSON.stringify(req.body)` reorders keys
+> and silently breaks verification with no diagnostic. Always capture the
+> raw body via your framework's raw-body middleware.
+
+```typescript
+import { verifyWebhookSignature, type EdgeWebhookEvent } from '@edge-markets/connect-node'
+import express from 'express'
+
+const app = express()
+
+app.post(
+  '/webhooks/edge',
+  // 👇 Critical: this gives you req.body as a Buffer, not a parsed object
+  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: EdgeWebhookEvent = JSON.parse(req.body.toString('utf8'))
+    // Process asynchronously and return 200 immediately — see "Best Practices"
+    void processEdgeEvent(event)
+    res.status(200).send('ok')
+  },
+)
+```
+
+#### NestJS
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true })
+
+// edge-webhook.controller.ts
+import { Controller, Post, Req, HttpCode, type RawBodyRequest } from '@nestjs/common'
+import type { Request } from 'express'
+import { verifyWebhookSignature } from '@edge-markets/connect-node'
+
+@Controller('webhooks')
+export class EdgeWebhookController {
+  @Post('edge')
+  @HttpCode(200)
+  handle(@Req() req: RawBodyRequest<Request>) {
+    const ok = verifyWebhookSignature(
+      req.headers['x-edge-signature'] as string,
+      req.rawBody?.toString('utf8') ?? '',
+      process.env.EDGE_WEBHOOK_SECRET!,
+    )
+    if (!ok) throw new UnauthorizedException('invalid signature')
+    // ...
+  }
+}
+```
+
+### Type-safe event handling with `EdgeWebhookEvent`
+
+`EdgeWebhookEvent` is a discriminated union over `event.type`. Switching
+narrows `event.data` automatically — no casts required.
+
+```typescript
+import type { EdgeWebhookEvent } from '@edge-markets/connect-node'
+
+function processEdgeEvent(event: EdgeWebhookEvent) {
+  switch (event.type) {
+    case 'transfer.completed':
+      // event.data is { transferId, status: 'completed', type, amount }
+      creditWallet(event.data.transferId, event.data.amount)
+      break
+    case 'transfer.failed':
+      // event.data.reason is `string | undefined`
+      logFailure(event.data.transferId, event.data.reason ?? 'unknown')
+      break
+    case 'transfer.expired':
+      cancelPending(event.data.transferId)
+      break
+    case 'transfer.processing':
+      // @experimental — reserved for ledger dual-write hand-off
+      break
+    case 'consent.revoked':
+      deactivateLink(event.data.userId, event.data.clientId)
+      break
+    default: {
+      const _exhaustive: never = event
+      return _exhaustive
+    }
+  }
+}
+```
+
+`event.data.amount` is intentionally a `string` (e.g. `'100.00'`), not a
+number, to preserve decimal precision — parse it with a decimal-aware
+library on your side.
+
+### Reconcile missed events with `syncWebhookEvents`
+
+Even with retries and a dead-letter queue, network or partner outages can
+drop webhook events. Run `syncWebhookEvents` from a cron (every ~5 minutes
+is typical) to catch anything your primary receiver missed.
+
+This method requires the partner-level credentials (`partnerClientId` /
+`partnerClientSecret`) on `EdgeConnectServer`. It uses the OAuth
+`client_credentials` grant, caches the partner token internally, and
+handles a 401 by refreshing the token once and retrying.
+
+```typescript
+import { EdgeConnectServer } from '@edge-markets/connect-node'
+
+const edge = new EdgeConnectServer({
+  clientId: process.env.EDGE_CLIENT_ID!,
+  clientSecret: process.env.EDGE_CLIENT_SECRET!,
+  environment: 'staging',
+  partnerClientId: process.env.EDGE_PARTNER_CLIENT_ID!,
+  partnerClientSecret: process.env.EDGE_PARTNER_CLIENT_SECRET!,
+})
+
+async function reconcile() {
+  let cursor = await db.cursors.get('edge') // your stored watermark
+  while (true) {
+    const { events, hasMore } = await edge.syncWebhookEvents({ afterEventId: cursor })
+    for (const event of events) {
+      await processEdgeEvent(event) // same idempotent handler as live webhooks
+      cursor = event.id
+    }
+    if (events.length > 0) await db.cursors.set('edge', cursor!)
+    if (!hasMore) break
+  }
+}
+
+setInterval(reconcile, 5 * 60 * 1000)
+```
+
+The server enforces a **30-day lookback**. If your cursor is older than 30
+days, you will receive events from 30 days ago — re-bootstrap from a known
+good state via `getTransfer` if you have been offline for longer.
+
+### Best practices
+
+1. **Verify signatures first** — reject mis-signed events with 401 before
+   doing any work.
+2. **Return 200 immediately** — process events asynchronously. EDGE retries
+   on non-2xx and on responses slower than 10s.
+3. **Be idempotent** — the same event may be delivered more than once
+   (at-least-once delivery). Key your wallet credit / status update on
+   `event.id` or `event.data.transferId`.
+4. **Run reconciliation as a backstop** — webhooks are the fast path,
+   `syncWebhookEvents` is the safety net. They share the same handler.
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -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 };