@distyra/sdk 0.5.0 → 0.6.1

package/README.md

@@ -36,8 +36,9 @@ if (error) {
   throw new Error(error.detail ?? error.error);
 }
 
-// `data` is fully typed against the EnrichResponse schema
-console.log(data.merchant.name, data.category.primary);
+// `data` is fully typed against the EnrichResponse schema. `merchant` is null
+// for non-merchant transactions (bank fees, transfers), so guard it.
+console.log(data.merchant?.name ?? '(no merchant)', data.category.primary);
 ```
 
 ## Options
@@ -52,6 +53,67 @@ console.log(data.merchant.name, data.category.primary);
 
 The returned client is a typed [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) client — use `.GET`, `.POST`, etc. against any path in the spec, with full request/response typing.
 
+## Handling unknown merchants (eventual consistency)
+
+The first time anyone enriches a brand-new merchant, the response may be unresolved
+(`resolution.status` other than `resolved`). The system then discovers and confirms that
+merchant in the background, so the same descriptor resolves shortly after, for every
+caller, with no model call.
+
+Read `resolution.retry_after`:
+
+- A number (seconds) means a confirmed answer is likely coming. Retry the same descriptor
+  once after that delay, or just let your next natural re-sync pick it up.
+- `null` means the result is definitive; no retry will help.
+
+```ts
+const { data } = await distyra.POST('/v1/enrich', { body: { descriptor, country_hint } });
+if (data.resolution.status !== 'resolved' && data.resolution.retry_after != null) {
+  // retry once after data.resolution.retry_after seconds, or wait for your next sync
+}
+```
+
+Note: `resolution.retryable` is a different signal. It is `true` only for a transient
+backend error (`timed_out` / `transient_error`), which you retry within seconds. See the
+full resolution-and-retries guide at <https://api.distyra.com/docs>.
+
+## Verifying webhooks
+
+Distyra signs every webhook delivery with a Stripe-shape header:
+
+```
+X-Distyra-Signature: t=<unix>,v1=<hmac_sha256_hex>
+```
+
+`verifyWebhook` checks it (HMAC-SHA256 over `"<t>.<rawBody>"`, keyed by the
+endpoint's signing secret, with replay protection). Always verify against the
+**raw request body**, before JSON parsing — re-serializing changes the bytes and
+breaks the signature.
+
+```ts
+import { verifyWebhook } from '@distyra/sdk';
+
+// Express — capture the raw body, e.g. app.use(express.raw({ type: 'application/json' }))
+app.post('/webhooks/distyra', (req, res) => {
+  const raw = req.body.toString('utf8');
+  const result = verifyWebhook(
+    process.env.DISTYRA_WEBHOOK_SECRET!,
+    raw,
+    req.header('X-Distyra-Signature'),
+  );
+  if (!result.ok) return res.status(400).send(result.reason);
+
+  const event = JSON.parse(raw);
+  // ... handle event ...
+  res.sendStatus(200);
+});
+```
+
+It returns `{ ok: true, timestamp }` or `{ ok: false, reason }` where `reason` is
+`'malformed'`, `'stale'`, or `'no_match'`. The default replay window is 5 minutes
+(`DEFAULT_TOLERANCE_SECONDS`); override it with `{ toleranceSeconds }`. Uses
+`node:crypto`, so it runs server-side (Node 18+).
+
 ## Lower-level access
 
 The generated `paths` and `operations` types are re-exported if you want to build your own `openapi-fetch` client or reference response shapes directly: