@edge-markets/connect 1.5.0 → 1.6.0

package/README.md

@@ -24,6 +24,7 @@ import type {
   Balance,
   Transfer,
   EdgeTokens,
+  EdgeWebhookEvent,
 } from '@edge-markets/connect'
 
 // Types are generated from the OpenAPI spec
@@ -36,6 +37,49 @@ const user: User = {
 }
 ```
 
+### Webhook events
+
+`EdgeWebhookEvent` is a discriminated union over `event.type` covering every
+event the producer emits. Switching narrows `event.data` to the matching
+variant — no casts:
+
+```typescript
+import type { EdgeWebhookEvent } from '@edge-markets/connect'
+
+function handle(event: EdgeWebhookEvent) {
+  switch (event.type) {
+    case 'transfer.completed':
+      // event.data is { transferId, status: 'completed', type, amount }
+      console.log(`completed: ${event.data.transferId} for ${event.data.amount}`)
+      break
+    case 'transfer.failed':
+      // event.data.reason is `string | undefined`
+      console.log(`failed: ${event.data.reason ?? 'unknown'}`)
+      break
+    case 'transfer.expired':
+      console.log(`expired: ${event.data.transferId}`)
+      break
+    case 'transfer.processing':
+      // @experimental — reserved for ledger dual-write hand-off
+      break
+    case 'consent.revoked':
+      console.log(`consent revoked: ${event.data.userId}`)
+      break
+    default: {
+      const _exhaustive: never = event
+      return _exhaustive
+    }
+  }
+}
+```
+
+> `event.data.amount` is intentionally typed as `string` (e.g. `'100.00'`) to
+> preserve decimal precision. Parse with a decimal-aware library on your side.
+
+For HMAC signature verification on the live HTTP delivery channel, use
+`verifyWebhookSignature` from `@edge-markets/connect-node`. For
+reconciliation polling, use `EdgeConnectServer.syncWebhookEvents`.
+
 ### Configuration
 
 Get environment-specific URLs:
@@ -93,6 +137,12 @@ try {
 | `EdgeTokens` | OAuth tokens |
 | `EdgeLinkSuccess` | Successful link result |
 | `EdgeLinkExit` | Link exit metadata |
+| `EdgeWebhookEvent` | Discriminated union over webhook event types |
+| `TransferCompletedEventData` | Payload for `transfer.completed` |
+| `TransferFailedEventData` | Payload for `transfer.failed` (includes optional `reason`) |
+| `TransferExpiredEventData` | Payload for `transfer.expired` |
+| `ConsentRevokedEventData` | Payload for `consent.revoked` |
+| `EDGE_WEBHOOK_EVENT_TYPES` | Runtime tuple of all known event type strings |
 
 ### Configuration
 

package/dist/index.d.mts

@@ -54,8 +54,8 @@ declare const EDGE_SCOPES: {
      */
     readonly BALANCE_READ: "balance.read";
     /**
-     * Initiate and verify fund transfers.
-     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
+     * Initiate fund transfers and create EDGE-hosted verification sessions.
+     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verification-session`, `GET /v1/transfers`
      */
     readonly TRANSFER_WRITE: "transfer.write";
 };
@@ -696,7 +696,7 @@ interface paths {
          *     Use the `idempotencyKey` to safely retry requests. If a transfer with the same key exists, its current status will be returned.
          *
          *     **OTP Verification:**
-         *     After initiating, the transfer will be in `pending_verification` status. Call `POST /transfer/{transferId}/verify` with the OTP to complete.
+         *     After initiating, the transfer will be in `pending_verification` status. Call `POST /transfer/{transferId}/verification-session` to create an EDGE-hosted verification session and embed the returned `verificationUrl` in your frontend.
          */
         post: operations['initiateTransfer'];
         delete?: never;
@@ -745,32 +745,6 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/v1/transfer/{transferId}/verify': {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Verify transfer with OTP
-         * @description Completes a pending transfer by verifying the one-time password.
-         *
-         *     **OTP Methods:**
-         *     - `sms`: User receives OTP via SMS
-         *     - `totp`: User generates OTP from authenticator app
-         *
-         *     The OTP method is indicated in the `otpMethod` field of the transfer response.
-         */
-        post: operations['verifyTransfer'];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     '/v1/consent': {
         parameters: {
             query?: never;
@@ -1154,13 +1128,6 @@ interface components {
              */
             total: number;
         };
-        VerifyTransferRequestDto: {
-            /**
-             * @description One-time password for verification
-             * @example 123456
-             */
-            otp: string;
-        };
         RevokeConsentResponseDto: {
             /**
              * @description Whether consent was successfully revoked
@@ -2035,69 +2002,6 @@ interface operations {
             };
         };
     };
-    verifyTransfer: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                /** @description The unique transfer identifier */
-                transferId: string;
-            };
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                'application/json': components['schemas']['VerifyTransferRequestDto'];
-            };
-        };
-        responses: {
-            /** @description Transfer verified and completed (or failed) */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['TransferResponseDto'];
-                };
-            };
-            /** @description Invalid OTP or transfer expired */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-            /** @description Invalid or expired access token */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-            /** @description User consent required or insufficient scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ConsentRequiredErrorDto'];
-                };
-            };
-            /** @description Transfer not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-        };
-    };
     revokeConsent: {
         parameters: {
             query?: never;
@@ -2432,10 +2336,6 @@ type TransferListItem = components['schemas']['TransferListItemDto'];
  * Paginated list of transfers.
  */
 type TransferList = components['schemas']['ListTransfersResponseDto'];
-/**
- * Request payload for verifying a transfer with OTP.
- */
-type VerifyTransferRequest = components['schemas']['VerifyTransferRequestDto'];
 /**
  * Response from revoking user consent.
  */
@@ -2636,6 +2536,179 @@ declare const OTP_METHODS: readonly ["sms", "totp", "email"];
  */
 declare const TRANSFER_CATEGORIES: readonly ["sportsbook", "casino", "dfs", "sweepstakes"];
 
+/**
+ * EDGE Connect Webhook Event Types (SDK-002)
+ *
+ * Discriminated union over `event.type` so partners get full type narrowing
+ * inside `switch` blocks. Field shapes mirror the producer's enqueue calls
+ * 1:1; see `edgeboost-api/src/nest/services/connect/`:
+ *   - `transfer-execution.service.ts:273` (transfer.completed)
+ *   - `verification-session.service.ts:468` (transfer.failed)
+ *   - `connect.service.ts:184` (transfer.expired)
+ *   - `oauth/consent.service.ts:125` (consent.revoked)
+ *
+ * **Decimal precision:** `data.amount` is intentionally a `string`, not a
+ * `number`. The producer sends `String(transfer.amount)` so partner systems
+ * can parse with arbitrary-precision libraries (e.g., decimal.js, big.js)
+ * without losing the trailing cent.
+ *
+ * **Timestamps:** `created_at` is an ISO 8601 string, not a `Date` — webhook
+ * payloads are JSON, parsing into `Date` is the partner's choice.
+ */
+
+/**
+ * All EDGE Connect webhook event type strings.
+ *
+ * Use this with {@link EDGE_WEBHOOK_EVENT_TYPES} for runtime checks
+ * and as the discriminator on {@link EdgeWebhookEvent}.
+ */
+type EdgeWebhookEventType = 'transfer.completed' | 'transfer.failed' | 'transfer.expired' | 'transfer.processing' | 'consent.revoked';
+/**
+ * Runtime tuple of every known event type.
+ *
+ * Use this when you need an array of strings (e.g., to filter incoming
+ * events, validate config, or render a UI dropdown). Kept in sync with
+ * {@link EdgeWebhookEventType} via `satisfies`.
+ */
+declare const EDGE_WEBHOOK_EVENT_TYPES: readonly ["transfer.completed", "transfer.failed", "transfer.expired", "transfer.processing", "consent.revoked"];
+/**
+ * Common envelope shared by every webhook event.
+ *
+ * @template T - The discriminator literal (event type)
+ * @template D - The shape of the `data` payload for this event type
+ */
+interface BaseWebhookEvent<T extends EdgeWebhookEventType, D> {
+    /**
+     * Globally unique event identifier (`evt_<base36-time><random>`).
+     *
+     * Use this for idempotency — webhook delivery is at-least-once.
+     */
+    id: string;
+    /** Event discriminator. */
+    type: T;
+    /**
+     * ISO 8601 timestamp of when EDGE created the event.
+     *
+     * Snake-case key matches the wire format — JSON payloads are not transformed.
+     */
+    created_at: string;
+    /** Event-specific payload. Type narrows when you `switch` on `type`. */
+    data: D;
+}
+/**
+ * Payload for `transfer.completed`.
+ *
+ * Emitted when a transfer is verified and the user balance has been settled.
+ */
+interface TransferCompletedEventData {
+    /** UUID v4 of the transfer. */
+    transferId: string;
+    /** Always `'completed'` for this event. */
+    status: 'completed';
+    /** Direction of the transfer (debit = user → partner, credit = partner → user). */
+    type: TransferType;
+    /** Decimal amount as a string (e.g. `'100.00'`). NOT a number. */
+    amount: string;
+}
+/**
+ * Payload for `transfer.failed`.
+ *
+ * Emitted when OTP attempts are exhausted, the ledger rejects the transfer,
+ * or a hard failure occurs after authorization.
+ */
+interface TransferFailedEventData {
+    transferId: string;
+    status: 'failed';
+    type: TransferType;
+    amount: string;
+    /**
+     * Human-readable failure reason.
+     *
+     * Optional — older failures may not include this field. Always default-safe
+     * with `event.data.reason ?? 'unknown'` rather than asserting.
+     */
+    reason?: string;
+}
+/**
+ * Payload for `transfer.expired`.
+ *
+ * Emitted when the user did not verify their OTP within the 15-minute
+ * verification window.
+ */
+interface TransferExpiredEventData {
+    transferId: string;
+    status: 'expired';
+    type: TransferType;
+    amount: string;
+}
+/**
+ * Payload for `transfer.processing`.
+ *
+ * @experimental Reserved for the EDGE-360 ledger dual-write hand-off and not
+ * currently emitted by the production producer. The shape may change before
+ * GA — do not rely on it in production code paths yet.
+ */
+interface TransferProcessingEventData {
+    transferId: string;
+    status: 'processing';
+    type: TransferType;
+    amount: string;
+}
+/**
+ * Payload for `consent.revoked`.
+ *
+ * Emitted when a user revokes the partner's access to their EDGE account.
+ * The partner should mark the corresponding linked account as inactive and
+ * stop calling user-scoped endpoints with the now-invalid access token.
+ */
+interface ConsentRevokedEventData {
+    /** EDGE user ID whose consent was revoked. */
+    userId: string;
+    /** OAuth client ID that lost consent (your partner client ID). */
+    clientId: string;
+    /** ISO 8601 timestamp of the revocation. */
+    revokedAt: string;
+}
+/**
+ * A fully-typed EDGE Connect webhook event.
+ *
+ * Switching on `event.type` narrows `event.data` to the matching variant —
+ * no casts needed:
+ *
+ * @example
+ * ```typescript
+ * import type { EdgeWebhookEvent } from '@edge-markets/connect'
+ *
+ * function handle(event: EdgeWebhookEvent) {
+ *   switch (event.type) {
+ *     case 'transfer.completed':
+ *       // event.data is TransferCompletedEventData
+ *       creditWallet(event.data.transferId, event.data.amount)
+ *       break
+ *     case 'transfer.failed':
+ *       // event.data.reason is `string | undefined`
+ *       logFailure(event.data.transferId, event.data.reason)
+ *       break
+ *     case 'transfer.expired':
+ *       cancelPending(event.data.transferId)
+ *       break
+ *     case 'transfer.processing':
+ *       // experimental — no-op for now
+ *       break
+ *     case 'consent.revoked':
+ *       deactivateLink(event.data.userId, event.data.clientId)
+ *       break
+ *     default: {
+ *       // Compile error if a new event type is added without a handler
+ *       const _exhaustive: never = event
+ *       return _exhaustive
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type EdgeWebhookEvent = BaseWebhookEvent<'transfer.completed', TransferCompletedEventData> | BaseWebhookEvent<'transfer.failed', TransferFailedEventData> | BaseWebhookEvent<'transfer.expired', TransferExpiredEventData> | BaseWebhookEvent<'transfer.processing', TransferProcessingEventData> | BaseWebhookEvent<'consent.revoked', ConsentRevokedEventData>;
+
 /**
  * EDGE Connect SDK Types
  *
@@ -3139,4 +3212,4 @@ declare const SDK_VERSION = "1.0.0";
  */
 declare const SDK_NAME = "@edge-markets/connect";
 
-export { ALL_EDGE_SCOPES, type ApiError, type Balance, type ConsentRequiredError, type CreateVerificationSessionRequest, EDGE_ENVIRONMENTS, EDGE_SCOPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, type EdgeLinkConfigBase, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type PKCEPair, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, type SdkGeolocation, TRANSFER_CATEGORIES, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferCategory, type TransferList, type TransferListItem, type TransferStatus, type TransferType, type User, type UserAddress, type VerificationSession, type VerificationSessionStatus, type VerificationSessionStatusResponse, type VerifyIdentityAddress, type VerifyIdentityOptions, type VerifyIdentityResult, type VerifyIdentityScores, type VerifyTransferRequest, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };
+export { ALL_EDGE_SCOPES, type ApiError, type Balance, type BaseWebhookEvent, type ConsentRequiredError, type ConsentRevokedEventData, type CreateVerificationSessionRequest, EDGE_ENVIRONMENTS, EDGE_SCOPES, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, type EdgeLinkConfigBase, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type EdgeWebhookEvent, type EdgeWebhookEventType, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type PKCEPair, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, type SdkGeolocation, TRANSFER_CATEGORIES, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferCategory, type TransferCompletedEventData, type TransferExpiredEventData, type TransferFailedEventData, type TransferList, type TransferListItem, type TransferProcessingEventData, type TransferStatus, type TransferType, type User, type UserAddress, type VerificationSession, type VerificationSessionStatus, type VerificationSessionStatusResponse, type VerifyIdentityAddress, type VerifyIdentityOptions, type VerifyIdentityResult, type VerifyIdentityScores, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };

package/dist/index.d.ts

@@ -54,8 +54,8 @@ declare const EDGE_SCOPES: {
      */
     readonly BALANCE_READ: "balance.read";
     /**
-     * Initiate and verify fund transfers.
-     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
+     * Initiate fund transfers and create EDGE-hosted verification sessions.
+     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verification-session`, `GET /v1/transfers`
      */
     readonly TRANSFER_WRITE: "transfer.write";
 };
@@ -696,7 +696,7 @@ interface paths {
          *     Use the `idempotencyKey` to safely retry requests. If a transfer with the same key exists, its current status will be returned.
          *
          *     **OTP Verification:**
-         *     After initiating, the transfer will be in `pending_verification` status. Call `POST /transfer/{transferId}/verify` with the OTP to complete.
+         *     After initiating, the transfer will be in `pending_verification` status. Call `POST /transfer/{transferId}/verification-session` to create an EDGE-hosted verification session and embed the returned `verificationUrl` in your frontend.
          */
         post: operations['initiateTransfer'];
         delete?: never;
@@ -745,32 +745,6 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/v1/transfer/{transferId}/verify': {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Verify transfer with OTP
-         * @description Completes a pending transfer by verifying the one-time password.
-         *
-         *     **OTP Methods:**
-         *     - `sms`: User receives OTP via SMS
-         *     - `totp`: User generates OTP from authenticator app
-         *
-         *     The OTP method is indicated in the `otpMethod` field of the transfer response.
-         */
-        post: operations['verifyTransfer'];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     '/v1/consent': {
         parameters: {
             query?: never;
@@ -1154,13 +1128,6 @@ interface components {
              */
             total: number;
         };
-        VerifyTransferRequestDto: {
-            /**
-             * @description One-time password for verification
-             * @example 123456
-             */
-            otp: string;
-        };
         RevokeConsentResponseDto: {
             /**
              * @description Whether consent was successfully revoked
@@ -2035,69 +2002,6 @@ interface operations {
             };
         };
     };
-    verifyTransfer: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                /** @description The unique transfer identifier */
-                transferId: string;
-            };
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                'application/json': components['schemas']['VerifyTransferRequestDto'];
-            };
-        };
-        responses: {
-            /** @description Transfer verified and completed (or failed) */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['TransferResponseDto'];
-                };
-            };
-            /** @description Invalid OTP or transfer expired */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-            /** @description Invalid or expired access token */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-            /** @description User consent required or insufficient scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ConsentRequiredErrorDto'];
-                };
-            };
-            /** @description Transfer not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['ErrorResponseDto'];
-                };
-            };
-        };
-    };
     revokeConsent: {
         parameters: {
             query?: never;
@@ -2432,10 +2336,6 @@ type TransferListItem = components['schemas']['TransferListItemDto'];
  * Paginated list of transfers.
  */
 type TransferList = components['schemas']['ListTransfersResponseDto'];
-/**
- * Request payload for verifying a transfer with OTP.
- */
-type VerifyTransferRequest = components['schemas']['VerifyTransferRequestDto'];
 /**
  * Response from revoking user consent.
  */
@@ -2636,6 +2536,179 @@ declare const OTP_METHODS: readonly ["sms", "totp", "email"];
  */
 declare const TRANSFER_CATEGORIES: readonly ["sportsbook", "casino", "dfs", "sweepstakes"];
 
+/**
+ * EDGE Connect Webhook Event Types (SDK-002)
+ *
+ * Discriminated union over `event.type` so partners get full type narrowing
+ * inside `switch` blocks. Field shapes mirror the producer's enqueue calls
+ * 1:1; see `edgeboost-api/src/nest/services/connect/`:
+ *   - `transfer-execution.service.ts:273` (transfer.completed)
+ *   - `verification-session.service.ts:468` (transfer.failed)
+ *   - `connect.service.ts:184` (transfer.expired)
+ *   - `oauth/consent.service.ts:125` (consent.revoked)
+ *
+ * **Decimal precision:** `data.amount` is intentionally a `string`, not a
+ * `number`. The producer sends `String(transfer.amount)` so partner systems
+ * can parse with arbitrary-precision libraries (e.g., decimal.js, big.js)
+ * without losing the trailing cent.
+ *
+ * **Timestamps:** `created_at` is an ISO 8601 string, not a `Date` — webhook
+ * payloads are JSON, parsing into `Date` is the partner's choice.
+ */
+
+/**
+ * All EDGE Connect webhook event type strings.
+ *
+ * Use this with {@link EDGE_WEBHOOK_EVENT_TYPES} for runtime checks
+ * and as the discriminator on {@link EdgeWebhookEvent}.
+ */
+type EdgeWebhookEventType = 'transfer.completed' | 'transfer.failed' | 'transfer.expired' | 'transfer.processing' | 'consent.revoked';
+/**
+ * Runtime tuple of every known event type.
+ *
+ * Use this when you need an array of strings (e.g., to filter incoming
+ * events, validate config, or render a UI dropdown). Kept in sync with
+ * {@link EdgeWebhookEventType} via `satisfies`.
+ */
+declare const EDGE_WEBHOOK_EVENT_TYPES: readonly ["transfer.completed", "transfer.failed", "transfer.expired", "transfer.processing", "consent.revoked"];
+/**
+ * Common envelope shared by every webhook event.
+ *
+ * @template T - The discriminator literal (event type)
+ * @template D - The shape of the `data` payload for this event type
+ */
+interface BaseWebhookEvent<T extends EdgeWebhookEventType, D> {
+    /**
+     * Globally unique event identifier (`evt_<base36-time><random>`).
+     *
+     * Use this for idempotency — webhook delivery is at-least-once.
+     */
+    id: string;
+    /** Event discriminator. */
+    type: T;
+    /**
+     * ISO 8601 timestamp of when EDGE created the event.
+     *
+     * Snake-case key matches the wire format — JSON payloads are not transformed.
+     */
+    created_at: string;
+    /** Event-specific payload. Type narrows when you `switch` on `type`. */
+    data: D;
+}
+/**
+ * Payload for `transfer.completed`.
+ *
+ * Emitted when a transfer is verified and the user balance has been settled.
+ */
+interface TransferCompletedEventData {
+    /** UUID v4 of the transfer. */
+    transferId: string;
+    /** Always `'completed'` for this event. */
+    status: 'completed';
+    /** Direction of the transfer (debit = user → partner, credit = partner → user). */
+    type: TransferType;
+    /** Decimal amount as a string (e.g. `'100.00'`). NOT a number. */
+    amount: string;
+}
+/**
+ * Payload for `transfer.failed`.
+ *
+ * Emitted when OTP attempts are exhausted, the ledger rejects the transfer,
+ * or a hard failure occurs after authorization.
+ */
+interface TransferFailedEventData {
+    transferId: string;
+    status: 'failed';
+    type: TransferType;
+    amount: string;
+    /**
+     * Human-readable failure reason.
+     *
+     * Optional — older failures may not include this field. Always default-safe
+     * with `event.data.reason ?? 'unknown'` rather than asserting.
+     */
+    reason?: string;
+}
+/**
+ * Payload for `transfer.expired`.
+ *
+ * Emitted when the user did not verify their OTP within the 15-minute
+ * verification window.
+ */
+interface TransferExpiredEventData {
+    transferId: string;
+    status: 'expired';
+    type: TransferType;
+    amount: string;
+}
+/**
+ * Payload for `transfer.processing`.
+ *
+ * @experimental Reserved for the EDGE-360 ledger dual-write hand-off and not
+ * currently emitted by the production producer. The shape may change before
+ * GA — do not rely on it in production code paths yet.
+ */
+interface TransferProcessingEventData {
+    transferId: string;
+    status: 'processing';
+    type: TransferType;
+    amount: string;
+}
+/**
+ * Payload for `consent.revoked`.
+ *
+ * Emitted when a user revokes the partner's access to their EDGE account.
+ * The partner should mark the corresponding linked account as inactive and
+ * stop calling user-scoped endpoints with the now-invalid access token.
+ */
+interface ConsentRevokedEventData {
+    /** EDGE user ID whose consent was revoked. */
+    userId: string;
+    /** OAuth client ID that lost consent (your partner client ID). */
+    clientId: string;
+    /** ISO 8601 timestamp of the revocation. */
+    revokedAt: string;
+}
+/**
+ * A fully-typed EDGE Connect webhook event.
+ *
+ * Switching on `event.type` narrows `event.data` to the matching variant —
+ * no casts needed:
+ *
+ * @example
+ * ```typescript
+ * import type { EdgeWebhookEvent } from '@edge-markets/connect'
+ *
+ * function handle(event: EdgeWebhookEvent) {
+ *   switch (event.type) {
+ *     case 'transfer.completed':
+ *       // event.data is TransferCompletedEventData
+ *       creditWallet(event.data.transferId, event.data.amount)
+ *       break
+ *     case 'transfer.failed':
+ *       // event.data.reason is `string | undefined`
+ *       logFailure(event.data.transferId, event.data.reason)
+ *       break
+ *     case 'transfer.expired':
+ *       cancelPending(event.data.transferId)
+ *       break
+ *     case 'transfer.processing':
+ *       // experimental — no-op for now
+ *       break
+ *     case 'consent.revoked':
+ *       deactivateLink(event.data.userId, event.data.clientId)
+ *       break
+ *     default: {
+ *       // Compile error if a new event type is added without a handler
+ *       const _exhaustive: never = event
+ *       return _exhaustive
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type EdgeWebhookEvent = BaseWebhookEvent<'transfer.completed', TransferCompletedEventData> | BaseWebhookEvent<'transfer.failed', TransferFailedEventData> | BaseWebhookEvent<'transfer.expired', TransferExpiredEventData> | BaseWebhookEvent<'transfer.processing', TransferProcessingEventData> | BaseWebhookEvent<'consent.revoked', ConsentRevokedEventData>;
+
 /**
  * EDGE Connect SDK Types
  *
@@ -3139,4 +3212,4 @@ declare const SDK_VERSION = "1.0.0";
  */
 declare const SDK_NAME = "@edge-markets/connect";
 
-export { ALL_EDGE_SCOPES, type ApiError, type Balance, type ConsentRequiredError, type CreateVerificationSessionRequest, EDGE_ENVIRONMENTS, EDGE_SCOPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, type EdgeLinkConfigBase, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type PKCEPair, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, type SdkGeolocation, TRANSFER_CATEGORIES, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferCategory, type TransferList, type TransferListItem, type TransferStatus, type TransferType, type User, type UserAddress, type VerificationSession, type VerificationSessionStatus, type VerificationSessionStatusResponse, type VerifyIdentityAddress, type VerifyIdentityOptions, type VerifyIdentityResult, type VerifyIdentityScores, type VerifyTransferRequest, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };
+export { ALL_EDGE_SCOPES, type ApiError, type Balance, type BaseWebhookEvent, type ConsentRequiredError, type ConsentRevokedEventData, type CreateVerificationSessionRequest, EDGE_ENVIRONMENTS, EDGE_SCOPES, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, type EdgeLinkConfigBase, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type EdgeWebhookEvent, type EdgeWebhookEventType, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type PKCEPair, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, type SdkGeolocation, TRANSFER_CATEGORIES, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferCategory, type TransferCompletedEventData, type TransferExpiredEventData, type TransferFailedEventData, type TransferList, type TransferListItem, type TransferProcessingEventData, type TransferStatus, type TransferType, type User, type UserAddress, type VerificationSession, type VerificationSessionStatus, type VerificationSessionStatusResponse, type VerifyIdentityAddress, type VerifyIdentityOptions, type VerifyIdentityResult, type VerifyIdentityScores, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   ALL_EDGE_SCOPES: () => ALL_EDGE_SCOPES,
   EDGE_ENVIRONMENTS: () => EDGE_ENVIRONMENTS,
   EDGE_SCOPES: () => EDGE_SCOPES,
+  EDGE_WEBHOOK_EVENT_TYPES: () => EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError: () => EdgeApiError,
   EdgeAuthenticationError: () => EdgeAuthenticationError,
   EdgeConsentRequiredError: () => EdgeConsentRequiredError,
@@ -77,6 +78,15 @@ var TRANSFER_CATEGORIES = [
   "sweepstakes"
 ];
 
+// src/types/webhooks.ts
+var EDGE_WEBHOOK_EVENT_TYPES = [
+  "transfer.completed",
+  "transfer.failed",
+  "transfer.expired",
+  "transfer.processing",
+  "consent.revoked"
+];
+
 // src/config/environments.ts
 var EDGE_ENVIRONMENTS = {
   production: {
@@ -89,9 +99,17 @@ var EDGE_ENVIRONMENTS = {
   },
   staging: {
     cognitoDomain: "https://edge-connect-staging.auth.us-east-1.amazoncognito.com",
-    apiBaseUrl: "https://staging-api.edgeboost.io/connect/v1",
-    oauthBaseUrl: "https://staging-api.edgeboost.io/api/v3/oauth",
-    userClientUrl: "https://connect-staging.edgeboost.io",
+    // Staging partner API — mTLS-enforced. Requires a partner client
+    // certificate on every request. Routed through API Gateway → VPC Link →
+    // internal ALB → ECS. Direct routes to the backend (e.g.
+    // backend.connect-staging.edgeboost.io) no longer exist.
+    apiBaseUrl: "https://connect-staging.edgeboost.io/connect/v1",
+    // OAuth token exchange — partner-facing, also mTLS-enforced.
+    oauthBaseUrl: "https://connect-staging.edgeboost.io/connect/oauth",
+    // User-facing captive frame for the Link SDK enrollment and transfer
+    // verification flows. Served from the edge-connect-oauth Vite app
+    // deployed on Amplify. No mTLS — browser traffic.
+    userClientUrl: "https://oauth.staging-app.edgeboost.bet",
     displayName: "Staging",
     isProduction: false
   },
@@ -145,8 +163,8 @@ var EDGE_SCOPES = {
    */
   BALANCE_READ: "balance.read",
   /**
-   * Initiate and verify fund transfers.
-   * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
+   * Initiate fund transfers and create EDGE-hosted verification sessions.
+   * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verification-session`, `GET /v1/transfers`
    */
   TRANSFER_WRITE: "transfer.write"
 };
@@ -325,6 +343,7 @@ var SDK_NAME = "@edge-markets/connect";
   ALL_EDGE_SCOPES,
   EDGE_ENVIRONMENTS,
   EDGE_SCOPES,
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError,
   EdgeAuthenticationError,
   EdgeConsentRequiredError,

package/dist/index.mjs

@@ -15,6 +15,15 @@ var TRANSFER_CATEGORIES = [
   "sweepstakes"
 ];
 
+// src/types/webhooks.ts
+var EDGE_WEBHOOK_EVENT_TYPES = [
+  "transfer.completed",
+  "transfer.failed",
+  "transfer.expired",
+  "transfer.processing",
+  "consent.revoked"
+];
+
 // src/config/environments.ts
 var EDGE_ENVIRONMENTS = {
   production: {
@@ -27,9 +36,17 @@ var EDGE_ENVIRONMENTS = {
   },
   staging: {
     cognitoDomain: "https://edge-connect-staging.auth.us-east-1.amazoncognito.com",
-    apiBaseUrl: "https://staging-api.edgeboost.io/connect/v1",
-    oauthBaseUrl: "https://staging-api.edgeboost.io/api/v3/oauth",
-    userClientUrl: "https://connect-staging.edgeboost.io",
+    // Staging partner API — mTLS-enforced. Requires a partner client
+    // certificate on every request. Routed through API Gateway → VPC Link →
+    // internal ALB → ECS. Direct routes to the backend (e.g.
+    // backend.connect-staging.edgeboost.io) no longer exist.
+    apiBaseUrl: "https://connect-staging.edgeboost.io/connect/v1",
+    // OAuth token exchange — partner-facing, also mTLS-enforced.
+    oauthBaseUrl: "https://connect-staging.edgeboost.io/connect/oauth",
+    // User-facing captive frame for the Link SDK enrollment and transfer
+    // verification flows. Served from the edge-connect-oauth Vite app
+    // deployed on Amplify. No mTLS — browser traffic.
+    userClientUrl: "https://oauth.staging-app.edgeboost.bet",
     displayName: "Staging",
     isProduction: false
   },
@@ -83,8 +100,8 @@ var EDGE_SCOPES = {
    */
   BALANCE_READ: "balance.read",
   /**
-   * Initiate and verify fund transfers.
-   * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
+   * Initiate fund transfers and create EDGE-hosted verification sessions.
+   * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verification-session`, `GET /v1/transfers`
    */
   TRANSFER_WRITE: "transfer.write"
 };
@@ -262,6 +279,7 @@ export {
   ALL_EDGE_SCOPES,
   EDGE_ENVIRONMENTS,
   EDGE_SCOPES,
+  EDGE_WEBHOOK_EVENT_TYPES,
   EdgeApiError,
   EdgeAuthenticationError,
   EdgeConsentRequiredError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Core types, configuration, and utilities for EDGE Connect SDK",
   "author": "EdgeBoost",
   "license": "MIT",