@edge-markets/connect-node 1.7.0 → 1.9.0

package/dist/index.d.ts

@@ -1,16 +1,23 @@
 import * as node_https from 'node:https';
-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';
+import { EdgeEnvironment, TransferCategory, Transfer, VerificationSession, TransferType, TransferStatus, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent, EdgeWebhookEventType } from '@edge-markets/connect';
+export { Balance, BaseWebhookEvent, ConsentRevokedEventData, CreateVerificationSessionRequest, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, EdgeValidationError, 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';
 
+type RequestEndpoint = 'connect_api' | 'oauth_token' | 'partner_webhook_sync';
 interface RequestInfo {
     method: string;
     url: string;
     body?: unknown;
+    endpoint?: RequestEndpoint;
+    attempt?: number;
 }
 interface ResponseInfo {
     status: number;
     body: unknown;
     durationMs: number;
+    method?: string;
+    url?: string;
+    endpoint?: RequestEndpoint;
+    attempt?: number;
 }
 interface RetryConfig {
     maxRetries?: number;
@@ -23,6 +30,17 @@ interface EdgeConnectServerConfig {
     clientSecret: string;
     environment: EdgeEnvironment;
     apiBaseUrl?: string;
+    /**
+     * Override the partner dashboard API base URL.
+     *
+     * Most integrations should omit this. The SDK derives the dashboard base
+     * from `apiBaseUrl` by replacing `/connect/v1` with `/v1`, matching the
+     * EDGE Connect gateway layout:
+     *
+     * - user-scoped API: `https://connect-staging.edgeboost.io/connect/v1`
+     * - partner dashboard API: `https://connect-staging.edgeboost.io/v1`
+     */
+    partnerApiBaseUrl?: string;
     oauthBaseUrl?: string;
     /**
      * @deprecated cognitoDomain is no longer used. Token exchange now goes through EdgeBoost API.
@@ -63,9 +81,19 @@ interface EdgeConnectServerConfig {
 }
 interface MtlsConfig {
     enabled: boolean;
+    /** Client certificate PEM used to authenticate this partner to EDGE Connect. */
     cert: string;
+    /** Client private key PEM paired with `cert`. */
     key: string;
-    ca?: string;
+    /**
+     * Optional additional server trust root(s), as PEM text.
+     *
+     * The SDK appends these certificates to Node's default public trust store
+     * instead of replacing it. Public EDGE Connect gateways use public ACM
+     * certificates, so most partners should omit this unless EDGE provides a
+     * private server CA for a non-public endpoint.
+     */
+    ca?: string | string[];
 }
 interface TransferOptions {
     type: 'debit' | 'credit';
@@ -75,6 +103,57 @@ interface TransferOptions {
     category?: TransferCategory;
 }
 
+interface TransferAmountLimits {
+    min?: string | number;
+    max?: string | number;
+}
+interface MoneyAmountOptions {
+    allowNumber?: boolean;
+}
+interface CreateTransferIdempotencyKeyOptions {
+    partnerUserId: string;
+    type: TransferType;
+    amount: string | number;
+    category?: TransferCategory;
+    externalId?: string;
+    nonce?: string;
+    namespace?: string;
+}
+interface TransferIntent {
+    type: TransferType;
+    amount: string | number;
+    category?: TransferCategory | null;
+}
+type ConnectTransferDirection = 'user_to_partner' | 'partner_to_user';
+interface TransferStatusMapping<TPartnerState extends string = string> {
+    pending_verification: TPartnerState;
+    processing: TPartnerState;
+    completed: TPartnerState;
+    failed: TPartnerState;
+    expired: TPartnerState;
+}
+interface StartTransferVerificationOptions {
+    transfer: TransferOptions;
+    origin: string;
+}
+interface StartTransferVerificationResult {
+    transfer: Transfer;
+    verificationSession: VerificationSession;
+}
+declare const CONNECT_TRANSFER_DIRECTIONS: {
+    readonly debit: "user_to_partner";
+    readonly credit: "partner_to_user";
+};
+declare function getConnectTransferDirection(type: TransferType): ConnectTransferDirection;
+declare function normalizeMoneyAmount(value: string | number, options?: MoneyAmountOptions): string;
+declare function validateTransferAmount(value: string | number, limits?: TransferAmountLimits, options?: MoneyAmountOptions): string;
+declare function createTransferIdempotencyKey(options: CreateTransferIdempotencyKeyOptions): string;
+declare function assertSameTransferIntent(existing: TransferIntent, requested: TransferIntent): void;
+declare function fingerprintTransferIntent(intent: TransferIntent): string;
+declare function moneyAmountsEqual(left: string | number, right: string | number, options?: MoneyAmountOptions): boolean;
+declare function mapTransferStatusToPartnerState<TPartnerState extends string>(status: TransferStatus, mapping: TransferStatusMapping<TPartnerState>): TPartnerState;
+declare function startTransferVerification(client: Pick<EdgeUserClient, 'initiateTransfer' | 'createVerificationSession'>, options: StartTransferVerificationOptions): Promise<StartTransferVerificationResult>;
+
 /**
  * A lightweight, user-scoped API client created via {@link EdgeConnectServer.forUser}.
  *
@@ -89,6 +168,7 @@ declare class EdgeUserClient {
     verifyIdentity(options: VerifyIdentityOptions): Promise<VerifyIdentityResult>;
     getBalance(): Promise<Balance>;
     initiateTransfer(options: TransferOptions): Promise<Transfer>;
+    startTransferVerification(options: StartTransferVerificationOptions): Promise<StartTransferVerificationResult>;
     getTransfer(transferId: string): Promise<Transfer>;
     listTransfers(params?: ListTransfersParams): Promise<TransferList>;
     revokeConsent(): Promise<{
@@ -107,6 +187,317 @@ declare class EdgeUserClient {
     getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
+type EdgeTokenVaultKeyMaterial = string | Buffer | Uint8Array;
+interface EdgeTokenVaultKey {
+    id: string;
+    key: EdgeTokenVaultKeyMaterial;
+}
+interface EdgeTokenVaultOptions {
+    currentKey: EdgeTokenVaultKey;
+    previousKeys?: EdgeTokenVaultKey[];
+}
+declare class EdgeTokenVault {
+    private readonly currentKey;
+    private readonly keysById;
+    constructor(options: EdgeTokenVaultOptions);
+    encryptTokens(tokens: EdgeTokens): string;
+    decryptTokens(envelope: string): EdgeTokens;
+    isEncrypted(value: unknown): value is string;
+}
+declare function createEdgeTokenVault(options: EdgeTokenVaultOptions): EdgeTokenVault;
+declare function isEdgeTokenVaultEnvelope(value: unknown): value is string;
+
+type EdgeTokenStoreValue = EdgeTokens | string;
+interface EdgeTokenStoreSaveContext {
+    tokens: EdgeTokens;
+    refreshed: boolean;
+}
+interface EdgeTokenStore {
+    load: (subjectId: string) => Promise<EdgeTokenStoreValue | null | undefined> | EdgeTokenStoreValue | null | undefined;
+    save: (subjectId: string, value: EdgeTokenStoreValue, context: EdgeTokenStoreSaveContext) => Promise<void> | void;
+}
+interface EdgeUserSessionOptions {
+    edge: Pick<EdgeConnectServer, 'forUser' | 'refreshTokens'>;
+    subjectId: string;
+    tokenStore: EdgeTokenStore;
+    tokenVault?: Pick<EdgeTokenVault, 'encryptTokens' | 'decryptTokens' | 'isEncrypted'>;
+    refreshSkewMs?: number;
+    now?: () => number;
+    onRefresh?: (tokens: EdgeTokens) => Promise<void> | void;
+    onEvent?: (event: EdgeUserSessionEvent) => Promise<void> | void;
+    singleFlightRefresh?: boolean;
+}
+interface GetValidTokensOptions {
+    forceRefresh?: boolean;
+}
+type EdgeUserSessionEventType = 'session.loaded' | 'session.refresh_started' | 'session.refresh_succeeded' | 'session.refresh_failed' | 'session.saved';
+interface EdgeUserSessionEvent {
+    type: EdgeUserSessionEventType;
+    subjectId: string;
+    refreshed?: boolean;
+    encrypted?: boolean;
+    expiresAt?: number;
+    scope?: string;
+    error?: string;
+}
+declare class EdgeUserSession {
+    private readonly edge;
+    private readonly subjectId;
+    private readonly tokenStore;
+    private readonly tokenVault?;
+    private readonly refreshSkewMs;
+    private readonly now;
+    private readonly onRefresh?;
+    private readonly onEvent?;
+    private readonly singleFlightRefresh;
+    private refreshPromise;
+    constructor(options: EdgeUserSessionOptions);
+    getValidTokens(options?: GetValidTokensOptions): Promise<EdgeTokens>;
+    getClient(options?: GetValidTokensOptions): Promise<EdgeUserClient>;
+    withClient<T>(callback: (client: EdgeUserClient, tokens: EdgeTokens) => Promise<T> | T, options?: GetValidTokensOptions): Promise<T>;
+    saveTokens(tokens: EdgeTokens, refreshed?: boolean): Promise<void>;
+    private loadTokens;
+    private refreshTokens;
+    private emitLoaded;
+    private emit;
+}
+declare function createEdgeUserSession(options: EdgeUserSessionOptions): EdgeUserSession;
+
+/**
+ * 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;
+
+type EdgeWebhookRawBody = string | Buffer | Uint8Array;
+type EdgeWebhookSignatureHeader = string | string[] | undefined | null;
+interface ParseAndVerifyWebhookOptions extends VerifyWebhookSignatureOptions {
+    rawBody: EdgeWebhookRawBody;
+    signatureHeader: EdgeWebhookSignatureHeader;
+    secret: string;
+    receivedAt?: Date;
+}
+interface ParsedEdgeWebhook {
+    event: EdgeWebhookEvent;
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    signatureTimestamp: number;
+    receivedAt: Date;
+}
+declare function parseAndVerifyWebhook(options: ParseAndVerifyWebhookOptions): ParsedEdgeWebhook;
+declare function extractWebhookSignatureTimestamp(header: EdgeWebhookSignatureHeader): number | undefined;
+declare function isEdgeWebhookEvent(value: unknown): value is EdgeWebhookEvent;
+declare function validateEdgeWebhookEvent(value: unknown): EdgeWebhookEvent;
+
+type WebhookInboxStatus = 'pending' | 'processing' | 'processed' | 'failed';
+type WebhookInboxSource = 'live_webhook' | 'sync';
+interface WebhookInboxRecord {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    event: EdgeWebhookEvent;
+    payloadFingerprint: string;
+    status: WebhookInboxStatus;
+    source: WebhookInboxSource;
+    attempts: number;
+    receivedAt: Date;
+    updatedAt?: Date;
+    processedAt?: Date | null;
+    lastError?: string | null;
+    signatureTimestamp?: number | null;
+    signatureHeader?: string | null;
+    rawBody?: string | null;
+}
+interface WebhookInboxInsertRecord {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    event: EdgeWebhookEvent;
+    payloadFingerprint: string;
+    source: WebhookInboxSource;
+    receivedAt: Date;
+    signatureTimestamp?: number | null;
+    signatureHeader?: string | null;
+    rawBody?: string | null;
+}
+type WebhookInboxInsertResult = {
+    inserted: true;
+    record: WebhookInboxRecord;
+} | {
+    inserted: false;
+    record: WebhookInboxRecord;
+};
+interface WebhookInboxListOptions {
+    status?: WebhookInboxStatus;
+    updatedBefore?: Date;
+    limit?: number;
+}
+interface WebhookInboxStore {
+    insert: (record: WebhookInboxInsertRecord) => Promise<WebhookInboxInsertResult> | WebhookInboxInsertResult;
+    find: (eventId: string) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markProcessing: (eventId: string, context: {
+        now: Date;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markProcessed: (eventId: string, context: {
+        now: Date;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markFailed: (eventId: string, context: {
+        now: Date;
+        error: string;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markPending?: (eventId: string, context: {
+        now: Date;
+        reason: string;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    list?: (options: WebhookInboxListOptions) => Promise<WebhookInboxRecord[]> | WebhookInboxRecord[];
+}
+interface WebhookInboxOptions {
+    store: WebhookInboxStore;
+    processEvent: (event: EdgeWebhookEvent, record: WebhookInboxRecord) => Promise<void> | void;
+    now?: () => Date;
+    storeRawBody?: boolean;
+    processingTimeoutMs?: number;
+    onEvent?: (event: WebhookInboxLifecycleEvent) => Promise<void> | void;
+}
+interface WebhookInboxLifecycleEvent {
+    type: 'webhook.accepted' | 'webhook.duplicate' | 'webhook.payload_mismatch' | 'webhook.processing_started' | 'webhook.processing_succeeded' | 'webhook.processing_failed' | 'webhook.recovered_stale';
+    eventId: string;
+    eventType?: EdgeWebhookEventType;
+    status?: WebhookInboxStatus;
+    source?: WebhookInboxSource;
+    attempts?: number;
+    error?: string;
+}
+interface WebhookInboxAcceptResult {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    inserted: boolean;
+    duplicate: boolean;
+    status: WebhookInboxStatus;
+    record: WebhookInboxRecord;
+}
+interface WebhookInboxProcessResult {
+    eventId: string;
+    status: WebhookInboxStatus;
+    processed: boolean;
+    skipped: boolean;
+    reason?: 'already_processed' | 'not_found' | 'locked';
+    record?: WebhookInboxRecord;
+}
+interface WebhookInboxRecoverResult {
+    recovered: number;
+    skipped: boolean;
+    reason?: 'list_not_configured' | 'mark_pending_not_configured';
+}
+declare class EdgeWebhookInbox {
+    private readonly store;
+    private readonly processEvent;
+    private readonly now;
+    private readonly storeRawBody;
+    private readonly processingTimeoutMs;
+    private readonly onEvent?;
+    constructor(options: WebhookInboxOptions);
+    accept(parsed: ParsedEdgeWebhook): Promise<WebhookInboxAcceptResult>;
+    acceptRaw(parsed: ParsedEdgeWebhook, rawBody: string, signatureHeader: string): Promise<WebhookInboxAcceptResult>;
+    acceptSyncedEvent(event: EdgeWebhookEvent, receivedAt?: Date): Promise<WebhookInboxAcceptResult>;
+    process(eventId: string, options?: {
+        force?: boolean;
+    }): Promise<WebhookInboxProcessResult>;
+    replay(eventId: string): Promise<WebhookInboxProcessResult>;
+    recoverStaleProcessing(): Promise<WebhookInboxRecoverResult>;
+    private acceptEvent;
+    private emit;
+}
+declare function createWebhookInbox(options: WebhookInboxOptions): EdgeWebhookInbox;
+declare function fingerprintWebhookEvent(event: EdgeWebhookEvent): string;
+
+interface WebhookReconcilerCursorStore {
+    load: () => Promise<string | null | undefined> | string | null | undefined;
+    save: (cursor: string) => Promise<void> | void;
+}
+interface WebhookReconcilerOptions {
+    edge: Pick<EdgeConnectServer, 'syncWebhookEvents'>;
+    cursorStore: WebhookReconcilerCursorStore;
+    processEvent?: (event: EdgeWebhookEvent) => Promise<void> | void;
+    inbox?: Pick<EdgeWebhookInbox, 'acceptSyncedEvent' | 'process'>;
+    limit?: SyncWebhookEventsOptions['limit'];
+    maxPages?: number;
+}
+interface WebhookReconcilerRunResult {
+    processed: number;
+    accepted?: number;
+    duplicates?: number;
+    pages: number;
+    cursor?: string;
+    hasMore: boolean;
+    skipped: boolean;
+    reason?: 'already_running' | 'empty_page_with_has_more' | 'max_pages_reached';
+}
+declare class EdgeWebhookReconciler {
+    private readonly options;
+    private running;
+    constructor(options: WebhookReconcilerOptions);
+    run(): Promise<WebhookReconcilerRunResult>;
+    private runInternal;
+}
+declare function createWebhookReconciler(options: WebhookReconcilerOptions): EdgeWebhookReconciler;
+
 /**
  * Options for {@link EdgeConnectServer.syncWebhookEvents}.
  */
@@ -142,6 +533,7 @@ interface SyncWebhookEventsResult {
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
+    private readonly partnerApiBaseUrl;
     private readonly oauthBaseUrl;
     private readonly timeout;
     private readonly retryConfig;
@@ -163,6 +555,7 @@ declare class EdgeConnectServer {
      * or per user session and discard it when the token changes.
      */
     forUser(accessToken: string): EdgeUserClient;
+    createUserSession(options: Omit<EdgeUserSessionOptions, 'edge'>): EdgeUserSession;
     exchangeCode(code: string, codeVerifier: string, redirectUri?: string): Promise<EdgeTokens>;
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
     /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
@@ -205,9 +598,18 @@ declare class EdgeConnectServer {
      * @throws {EdgeApiError} For other non-2xx responses after retries
      */
     syncWebhookEvents(options?: SyncWebhookEventsOptions): Promise<SyncWebhookEventsResult>;
+    /**
+     * 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: Omit<WebhookReconcilerOptions, 'edge'>): EdgeWebhookReconciler;
     /**
      * Builds the sync URL with normalized query parameters.
      */
+    private normalizeSyncWebhookEventsOptions;
     private buildSyncUrl;
     /**
      * Issues a GET to the sync endpoint with the partner Bearer token. Kept
@@ -228,6 +630,9 @@ declare class EdgeConnectServer {
      * to `syncWebhookEvents` re-fetches it. Not part of the public API.
      */
     _resetPartnerTokenCache(): void;
+    private redactPartnerTokenResponseBody;
+    private redactPartnerSyncResponseBody;
+    private drainResponseBody;
     private getRetryDelay;
     private sleep;
     private fetchWithTimeout;
@@ -236,68 +641,136 @@ declare class EdgeConnectServer {
     private handleApiErrorFromBody;
 }
 
-/**
- * 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;
+type EdgeConnectEnv = Record<string, string | undefined>;
+interface CreateEdgeConnectServerFromEnvOptions {
+    env?: EdgeConnectEnv;
+    requireMtls?: boolean;
+    timeout?: number;
+    retry?: RetryConfig;
+    onRequest?: (info: RequestInfo) => void;
+    onResponse?: (info: ResponseInfo) => void;
+    mle?: EdgeConnectServerConfig['mle'];
 }
-/**
- * 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;
+interface EdgeConnectServerFromEnvCapabilities {
+    mtlsEnabled: boolean;
+    webhookSyncConfigured: boolean;
+    customApiBaseUrl: boolean;
+    customOAuthBaseUrl: boolean;
+    customPartnerApiBaseUrl: boolean;
+}
+interface EdgeConnectServerFromEnvResult {
+    server: EdgeConnectServer;
+    config: EdgeConnectServerConfig;
+    capabilities: EdgeConnectServerFromEnvCapabilities;
+    warnings: string[];
+}
+declare function createEdgeConnectServerFromEnv(options?: CreateEdgeConnectServerFromEnvOptions): EdgeConnectServerFromEnvResult;
+
+interface EdgeProblemJson {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    code: string;
+    details?: Record<string, unknown>;
+}
+interface EdgeHttpError {
+    status: number;
+    body: EdgeProblemJson;
+}
+declare function toEdgeHttpError(error: unknown): EdgeHttpError;
+declare function toEdgeProblemJson(error: unknown): EdgeProblemJson;
+
+interface EdgeWebhookHttpRequestLike {
+    headers?: Record<string, unknown>;
+    rawBody?: Buffer | Uint8Array | string;
+    body?: unknown;
+}
+interface ParseWebhookHttpRequestOptions extends Omit<ParseAndVerifyWebhookOptions, 'rawBody' | 'signatureHeader'> {
+    request: EdgeWebhookHttpRequestLike;
+    signatureHeaderName?: string;
+}
+declare function getEdgeWebhookRawBody(request: EdgeWebhookHttpRequestLike): EdgeWebhookRawBody;
+declare function getEdgeWebhookSignatureHeader(request: EdgeWebhookHttpRequestLike, headerName?: string): EdgeWebhookSignatureHeader;
+declare function parseWebhookHttpRequest(options: ParseWebhookHttpRequestOptions): ParsedEdgeWebhook;
+
+interface PartnerIdentityAddress {
+    street?: string | null;
+    line1?: string | null;
+    address1?: string | null;
+    city?: string | null;
+    state?: string | null;
+    zip?: string | null;
+    postalCode?: string | null;
+}
+interface PartnerIdentityProfile {
+    firstName?: string | null;
+    givenName?: string | null;
+    lastName?: string | null;
+    familyName?: string | null;
+    address?: PartnerIdentityAddress | null;
+}
+interface IdentityPolicy {
+    minNameScore?: number;
+    minAddressScore?: number;
+    requireZipMatch?: boolean;
+    requireApiVerified?: boolean;
+}
+interface IdentityPolicyEvaluation {
+    verified: boolean;
+    reasons: string[];
+    scores?: VerifyIdentityResult['scores'];
+}
+declare function buildVerifyIdentityPayload(profile: PartnerIdentityProfile): VerifyIdentityOptions;
+declare function evaluateIdentityResult(result: VerifyIdentityResult, policy?: IdentityPolicy): IdentityPolicyEvaluation;
+
+interface EdgeSessionTokenRecord {
+    subjectId: string;
+    encryptedTokens: string;
+    expiresAt: number;
+    scopes?: string[];
+    edgeUserId?: string;
+    keyId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateSessionTokenRecordOptions {
+    scopes?: string[];
+    edgeUserId?: string;
+    keyId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface LegacySessionTokenRecord {
+    subjectId?: string;
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    idToken?: string | null;
+    expiresAt?: unknown;
+    expiresIn?: unknown;
+    scope?: unknown;
+    scopes?: unknown;
+    edgeUserId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface EncryptLegacySessionTokensOptions {
+    subjectId: string;
+    keyId?: string;
+    allowPlaintext?: boolean;
+}
+declare function createSessionTokenRecord(subjectId: string, tokens: EdgeTokens, tokenVault: Pick<EdgeTokenVault, 'encryptTokens'>, options?: CreateSessionTokenRecordOptions): EdgeSessionTokenRecord;
+declare function parseSessionTokenRecord(record: unknown): EdgeSessionTokenRecord;
+declare function encryptLegacySessionTokens(legacyRecord: LegacySessionTokenRecord, tokenVault: Pick<EdgeTokenVault, 'encryptTokens' | 'isEncrypted'>, options: EncryptLegacySessionTokensOptions): EdgeSessionTokenRecord;
+declare function normalizeSessionExpiresAt(value: unknown): number;
+
+interface TransferWebhookIntent {
+    transferId: string;
+    type?: TransferType;
+    amount?: string | number;
+    status?: TransferStatus;
+}
+declare function isTransferWebhookEvent(event: EdgeWebhookEvent): event is Extract<EdgeWebhookEvent, {
+    type: `transfer.${string}`;
+}>;
+declare function assertTransferEventMatchesIntent(event: EdgeWebhookEvent, intent: TransferWebhookIntent): void;
+declare const assertWebhookMatchesTransfer: typeof assertTransferEventMatchesIntent;
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type MtlsConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferOptions, type VerifyWebhookSignatureOptions, verifyWebhookSignature };
+export { CONNECT_TRANSFER_DIRECTIONS, type ConnectTransferDirection, type CreateEdgeConnectServerFromEnvOptions, type CreateSessionTokenRecordOptions, type CreateTransferIdempotencyKeyOptions, type EdgeConnectEnv, EdgeConnectServer, type EdgeConnectServerConfig, type EdgeConnectServerFromEnvCapabilities, type EdgeConnectServerFromEnvResult, type EdgeHttpError, type EdgeProblemJson, type EdgeSessionTokenRecord, type EdgeTokenStore, type EdgeTokenStoreSaveContext, type EdgeTokenStoreValue, EdgeTokenVault, type EdgeTokenVaultKey, type EdgeTokenVaultKeyMaterial, type EdgeTokenVaultOptions, EdgeUserClient, EdgeUserSession, type EdgeUserSessionEvent, type EdgeUserSessionEventType, type EdgeUserSessionOptions, type EdgeWebhookHttpRequestLike, EdgeWebhookInbox, type EdgeWebhookRawBody, EdgeWebhookReconciler, type EdgeWebhookSignatureHeader, type EncryptLegacySessionTokensOptions, type GetValidTokensOptions, type IdentityPolicy, type IdentityPolicyEvaluation, type LegacySessionTokenRecord, type MoneyAmountOptions, type MtlsConfig, type ParseAndVerifyWebhookOptions, type ParseWebhookHttpRequestOptions, type ParsedEdgeWebhook, type PartnerIdentityAddress, type PartnerIdentityProfile, type RequestInfo, type ResponseInfo, type RetryConfig, type StartTransferVerificationOptions, type StartTransferVerificationResult, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferAmountLimits, type TransferIntent, type TransferOptions, type TransferStatusMapping, type TransferWebhookIntent, type VerifyWebhookSignatureOptions, type WebhookInboxAcceptResult, type WebhookInboxInsertRecord, type WebhookInboxInsertResult, type WebhookInboxLifecycleEvent, type WebhookInboxListOptions, type WebhookInboxOptions, type WebhookInboxProcessResult, type WebhookInboxRecord, type WebhookInboxRecoverResult, type WebhookInboxSource, type WebhookInboxStatus, type WebhookInboxStore, type WebhookReconcilerCursorStore, type WebhookReconcilerOptions, type WebhookReconcilerRunResult, assertSameTransferIntent, assertTransferEventMatchesIntent, assertWebhookMatchesTransfer, buildVerifyIdentityPayload, createEdgeConnectServerFromEnv, createEdgeTokenVault, createEdgeUserSession, createSessionTokenRecord, createTransferIdempotencyKey, createWebhookInbox, createWebhookReconciler, encryptLegacySessionTokens, evaluateIdentityResult, extractWebhookSignatureTimestamp, fingerprintTransferIntent, fingerprintWebhookEvent, getConnectTransferDirection, getEdgeWebhookRawBody, getEdgeWebhookSignatureHeader, isEdgeTokenVaultEnvelope, isEdgeWebhookEvent, isTransferWebhookEvent, mapTransferStatusToPartnerState, moneyAmountsEqual, normalizeMoneyAmount, normalizeSessionExpiresAt, parseAndVerifyWebhook, parseSessionTokenRecord, parseWebhookHttpRequest, startTransferVerification, toEdgeHttpError, toEdgeProblemJson, validateEdgeWebhookEvent, validateTransferAmount, verifyWebhookSignature };