@edge-markets/connect-node 1.8.0 → 1.10.0

package/README.md

@@ -12,9 +12,16 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 🪝 **Webhook signature verification** - Constant-time HMAC-SHA256 with replay protection
 - ✅ **Webhook parsing + validation** - Verify raw bodies and fail closed on malformed event payloads
 - 🔁 **Webhook reconciliation** - Cursor-based sync for catching missed events
+- 📥 **Webhook inbox orchestration** - Durable accept/process/replay control flow with partner-owned storage
 - 🔐 **Token vault** - Versioned AES-256-GCM token encryption with key rotation
+- 🔄 **User sessions** - Token-store callbacks with refresh, encryption, and single-flight refresh protection
 - ⚙️ **Env config helper** - Build SDK config from standard EDGE env vars
 
+These helpers are framework-neutral: the SDK owns repeatable Connect mechanics
+such as token refresh, webhook validation, replay control flow, and transfer
+intent checks, while partner applications keep ownership of persistence, wallet
+mutation, admin authorization, and business rules.
+
 ## Installation
 
 ```bash
@@ -85,7 +92,9 @@ Supported environment variables:
 | `EDGE_PARTNER_CLIENT_SECRET` | Partner machine-to-machine client secret for webhook sync |
 | `EDGE_MTLS_CERT` / `EDGE_MTLS_CERT_PATH` | Client certificate PEM or file path |
 | `EDGE_MTLS_KEY` / `EDGE_MTLS_KEY_PATH` | Client private key PEM or file path |
-| `EDGE_MTLS_CA` / `EDGE_MTLS_CA_PATH` | Optional extra server trust root PEM or file path |
+| `EDGE_SERVER_CA_PEM` / `EDGE_SERVER_CA_PEM_PATH` | Optional extra server trust root PEM or file path |
+| `EDGE_MTLS_CA` / `EDGE_MTLS_CA_PATH` | Legacy alias for optional extra server trust root PEM or file path |
+| `EDGE_REQUIRE_MTLS` | Set to `true` to fail startup unless client cert and key are configured |
 | `EDGE_TIMEOUT_MS` | Optional request timeout in milliseconds |
 
 Use inline PEMs with escaped newlines (`\n`) or file paths. If both are set,
@@ -248,35 +257,46 @@ const decrypted = tokenVault.decryptTokens(connection.encryptedTokens)
 const client = edge.forUser(decrypted.accessToken)
 ```
 
-## Token Refresh
+## Token Refresh And User Sessions
 
-Refresh tokens before they expire:
+Use `EdgeUserSession` when you store encrypted tokens and want the SDK to
+handle decrypt-refresh-save-client lifecycle. You still own the database table
+and user mapping.
 
 ```typescript
-async function getValidAccessToken(userId: string): Promise<string> {
-  const connection = await db.edgeConnections.get(userId)
-  
-  // Refresh 5 minutes before expiry
-  const BUFFER = 5 * 60 * 1000
-  
-  if (Date.now() > connection.expiresAt.getTime() - BUFFER) {
-    const newTokens = await edge.refreshTokens(
-      decrypt(connection.refreshToken)
-    )
-    
-    await db.edgeConnections.update(userId, {
-      accessToken: encrypt(newTokens.accessToken),
-      refreshToken: encrypt(newTokens.refreshToken),
-      expiresAt: new Date(newTokens.expiresAt),
-    })
-    
-    return newTokens.accessToken
-  }
-  
-  return decrypt(connection.accessToken)
-}
+const session = edge.createUserSession({
+  subjectId: userId,
+  tokenVault,
+  tokenStore: {
+    load: async (subjectId) => {
+      const row = await db.edgeConnections.get(subjectId)
+      return row?.encryptedTokens
+    },
+    save: async (subjectId, encryptedTokens, { tokens }) => {
+      await db.edgeConnections.update(subjectId, {
+        encryptedTokens,
+        expiresAt: new Date(tokens.expiresAt),
+      })
+    },
+  },
+  refreshSkewMs: 60_000,
+})
+
+const balance = await session.withClient((client) => client.getBalance())
 ```
 
+`EdgeUserSession` refreshes near-expiry tokens, preserves refresh tokens when
+the token endpoint does not rotate them, saves the refreshed token envelope
+before returning a client, and single-flights concurrent refreshes on the same
+process. In horizontally scaled services, keep your storage callbacks
+idempotent or add DB-level optimistic locking.
+
+For migrations from split token columns, use `createSessionTokenRecord`,
+`parseSessionTokenRecord`, `normalizeSessionExpiresAt`, and
+`encryptLegacySessionTokens`. Plaintext migration requires an explicit
+`allowPlaintext: true` option so production request paths do not silently accept
+raw tokens.
+
 ## API Methods
 
 All user-scoped API methods live on `EdgeUserClient`, created via `edge.forUser(accessToken)`:
@@ -526,6 +546,110 @@ calls, fetches and caches the partner `client_credentials` token internally,
 retries transient sync failures with the SDK retry policy, and redacts token
 material from observability hooks.
 
+### Durable webhook inbox with `createWebhookInbox`
+
+For production integrations, accept a verified webhook into durable storage
+before returning `200`, then process it asynchronously. The SDK can own the
+state machine while your app owns the database callbacks and wallet mutation.
+
+```typescript
+import {
+  createWebhookInbox,
+  parseWebhookHttpRequest,
+} from '@edge-markets/connect-node'
+
+const inbox = createWebhookInbox({
+  store: {
+    insert: db.webhookInbox.insertIdempotently,
+    find: db.webhookInbox.find,
+    markProcessing: db.webhookInbox.markProcessing,
+    markProcessed: db.webhookInbox.markProcessed,
+    markFailed: db.webhookInbox.markFailed,
+    markPending: db.webhookInbox.markPending,
+    list: db.webhookInbox.list,
+  },
+  processEvent: async (event) => {
+    // Partner-owned business logic. Keep wallet mutation idempotent.
+    await processEdgeEvent(event)
+  },
+})
+
+app.post('/webhooks/edge', express.raw({ type: 'application/json' }), async (req, res) => {
+  const parsed = parseWebhookHttpRequest({
+    request: { headers: req.headers, rawBody: req.body },
+    secret: process.env.EDGE_WEBHOOK_SECRET!,
+  })
+
+  const accepted = await inbox.acceptRaw(
+    parsed,
+    Buffer.from(req.body).toString('utf8'),
+    String(req.headers['x-edge-signature'] ?? ''),
+  )
+
+  res.status(200).json({
+    received: true,
+    duplicate: accepted.duplicate,
+    status: accepted.status,
+  })
+
+  void inbox.process(accepted.eventId).catch((error) => {
+    logger.error('EDGE webhook processing failed', { eventId: accepted.eventId, error })
+  })
+})
+```
+
+The inbox statuses are `pending`, `processing`, `processed`, and `failed`.
+Duplicate `event.id` deliveries are idempotent if the payload fingerprint
+matches. A duplicate event ID with different payload fails closed.
+
+Sync reconciliation can use the same inbox path:
+
+```typescript
+const reconciler = edge.createWebhookReconciler({
+  cursorStore,
+  inbox,
+  limit: 100,
+})
+```
+
+The reconciler accepts each synced event into the inbox, processes it, and saves
+the cursor only after processing succeeds or the event is already processed.
+Use `inbox.replay(eventId)` for explicit admin replays and
+`inbox.recoverStaleProcessing()` to make crashed `processing` rows replayable.
+
+### Transfer safety helpers
+
+Use transfer helpers to avoid decimal and direction mistakes:
+
+```typescript
+import {
+  assertWebhookMatchesTransfer,
+  createTransferIdempotencyKey,
+  getConnectTransferDirection,
+  mapTransferStatusToPartnerState,
+  normalizeMoneyAmount,
+  validateTransferAmount,
+} from '@edge-markets/connect-node'
+
+const amount = validateTransferAmount(input.amount, { min: '1.00', max: '10000.00' }, { allowNumber: false })
+const idempotencyKey = createTransferIdempotencyKey({
+  partnerUserId: user.id,
+  type: 'debit',
+  amount,
+  category: 'sportsbook',
+  externalId: bet.id,
+})
+
+// debit = EDGE user to partner; credit = partner to EDGE user
+const direction = getConnectTransferDirection('debit')
+
+assertWebhookMatchesTransfer(event, {
+  transferId: localTransfer.edgeTransferId,
+  type: 'debit',
+  amount: localTransfer.amount,
+})
+```
+
 ## Error Handling
 
 ```typescript