@fanth/payment-router-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,201 +1,49 @@
-# @fanth/payment-router-sdk
+# payment-router-sdk
 
-TypeScript SDK for **payment-router** - the URL shortener for payment gateway webhooks.
+TypeScript SDK for payment-router: create webhook routes and verify the signed callbacks it forwards.
 
-Both ends of the trip, off one object - `PaymentRouterClient`:
-
-- **creating a route** registers your real webhook URL and hands back the UUID you give the gateway
-  as its external payment id.
-- **verifying a callback** proves the request the router forwarded back really came from the router,
-  and that its body was not touched on the way.
-
-Runs anywhere with `fetch` and WebCrypto: Node 18+, Cloudflare Workers, Deno, Bun, Vercel Edge.
-ESM and CJS builds, types included, one dependency (`jose`).
+## Install
 
 ```bash
-npm install @fanth/payment-router-sdk
+npm install payment-router-sdk
 ```
 
-## Creating a route
+## Usage
 
 ```ts
-import { PaymentRouterClient } from "@fanth/payment-router-sdk";
+import { PaymentRouterClient } from "payment-router-sdk";
 
-const router = new PaymentRouterClient(); // https://payment-r.fanth.pl
+const router = new PaymentRouterClient("https://router.example.com");
 
+// Register the real webhook URL, get back the id to send the gateway plus its callback URLs.
 const route = await router.createRoute({
     webhookUrl: "https://shop.example.com/webhooks/payu",
-    externalId: "order-42", // your own id, echoed back on the callback
-    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // optional
+    externalId: "order-123", // optional, echoed back on the callback
+    expiresAt: "2026-07-12T10:00:00Z", // optional, defaults to 12h out
 });
 
-// route.id              -> send as the gateway's external payment id (PayU: extOrderId)
-// route.callbackUrls    -> { payu: "https://payment-r.fanth.pl/webhooks/payu" }
-```
-
-Every call defaults to the hosted router at `https://payment-r.fanth.pl` (exported as
-`DEFAULT_BASE_URL`). Running your own worker? Pass `baseUrl` - the verifier's expected `iss` follows
-it, so one option covers both ends.
-
-Then create the payment at the gateway with `route.id` as its external order id, and point the
-gateway's single webhook URL at `route.callbackUrls.payu`. That URL never changes, so it can just as
-well be read straight off the client without creating a route:
-
-```ts
-router.callbackUrl("payu"); // https://payment-r.fanth.pl/webhooks/payu
+route.id; // send this to the gateway as its external payment id
+route.callbackUrls; // { payu: "https://router.example.com/webhooks/payu" }
 ```
 
-### Options
-
-| Option         | Default            | What it does                                                 |
-| -------------- | ------------------ | ------------------------------------------------------------ |
-| `baseUrl`      | `DEFAULT_BASE_URL` | The router's public origin.                                  |
-| `fetch`        | global `fetch`     | Custom fetch, for proxies, instrumentation or tests.         |
-| `timeoutMs`    | `10000`            | Per-attempt timeout.                                         |
-| `maxRetries`   | `2`                | Retries on network errors and 429/502/503/504, with backoff. |
-| `retryDelayMs` | `200`              | Base backoff, doubled per attempt.                           |
-| `headers`      | -                  | Extra headers on every request.                              |
-| `verifier`     | -                  | Overrides for the built-in verifier (see below).             |
-
-Route creation is not idempotent: if a create succeeded but its response was lost on the way back,
-the retry creates a second route and the first is orphaned. That is harmless - an unused route is a
-row nobody ever calls back on - but set `maxRetries: 0` if you would rather see the failure.
-
-## Verifying a callback
-
-The router signs every forwarded callback with an EdDSA (Ed25519) JWT in the
-`X-Payment-Router-Signature` header, and publishes the public keys as a JWKS. The client checks both
-the signature **and** `body_sha256`, so the signature covers the payload and not just its
-provenance. Key rotation on the router is transparent - the key set is fetched by `kid` and cached.
-
-Verification needs the **raw bytes** as they arrived. Re-serialized JSON changes the hash, and the
-callback will be rejected.
-
-The same client does it - three methods, same checks, different shape of input. The key set is
-cached per client, so keep one around instead of building one per request. A service that only
-receives callbacks and never creates routes builds the client just the same.
-
-### Express, Fastify, Koa, anything else
-
-`verifyWebhook(headers, rawBody)` takes the headers and the raw body and gives the same raw body
-back - or throws. No middleware, no framework types.
+In the receiving webhook handler, verify the forwarded callback's `X-Payment-Router-Signature`
+header before trusting it:
 
 ```ts
-import express from "express";
-import { PaymentRouterClient } from "@fanth/payment-router-sdk";
-
-const router = new PaymentRouterClient(); // or { baseUrl } for your own worker
-
-// express.json() throws the raw bytes away, so parse them yourself after verifying
-app.post("/webhooks/payu", express.raw({ type: "*/*" }), async (req, res) => {
-    let rawBody: string;
-    try {
-        rawBody = await router.verifyWebhook(req.headers, req.body);
-    } catch {
-        return res.sendStatus(401);
-    }
-
-    await markPaid(JSON.parse(rawBody));
-    res.sendStatus(200);
-});
-```
-
-Both header shapes work: Node's plain object and fetch's `Headers`.
+const token = req.headers["x-payment-router-signature"];
+const rawBody = req.rawBody; // must be the exact bytes received
 
-### Fetch-API handlers (Workers, Hono, Next.js, Deno, Bun)
-
-`verifyRequest(request)` reads the header and the body off a `Request` for you, and returns the
-claims alongside the body:
-
-```ts
-export async function POST(request: Request) {
-    try {
-        const { claims, rawBody } = await router.verifyRequest(request);
-        const notification = JSON.parse(rawBody);
-        // claims.routeId / claims.externalId say which of your payments this is
-        await markPaid(claims.externalId, notification);
-        return new Response("OK");
-    } catch (error) {
-        return new Response("unauthorized", { status: 401 });
-    }
-}
+const { routeId, gateway, externalId } = await router.verifyCallback(token, rawBody);
 ```
 
-### Anything the other two do not fit
-
-`verifyCallback()` takes the two things that actually matter and returns the claims:
-
-```ts
-const { claims, rawBody } = await router.verifyCallback({
-    token: req.headers["x-payment-router-signature"],
-    rawBody, // string or Uint8Array, exactly as received
-});
-```
-
-`readRawBody(req)` drains a plain `http.IncomingMessage` when there is no body parser at all.
-
-### Options
-
-Verifier settings go under the client's `verifier` option:
-
-```ts
-const router = new PaymentRouterClient({ verifier: { maxAgeSeconds: 60 } });
-```
-
-| Option                  | Default              | What it does                                                  |
-| ----------------------- | -------------------- | ------------------------------------------------------------- |
-| `issuer`                | the client's baseUrl | Override when it differs from the router's `PUBLIC_BASE_URL`. |
-| `jwksUrl`               | baseUrl + JWKS path  | Override the key set location.                                |
-| `maxAgeSeconds`         | `300`                | Reject tokens older than this - the router's own TTL.         |
-| `clockToleranceSeconds` | `5`                  | Leeway for clock skew.                                        |
-| `fetch`                 | the client's fetch   | Custom fetch for the JWKS request.                            |
-| `keyStore`              | remote JWKS          | Swap the key source, e.g. jose's `createLocalJWKSet`.         |
-
-`baseUrl` is inherited from the client, so one origin covers route creation and verification alike.
-
-### Verified claims
-
-```ts
-type CallbackClaims = {
-    routeId: string; // the id you gave the gateway
-    gateway: string; // "payu"
-    externalId: string | null; // your own id, if you set one
-    bodySha256: string; // already checked against the body
-    issuer: string;
-    issuedAt: Date;
-    expiresAt: Date;
-    raw: JWTPayload;
-};
-```
-
-The router also copies `routeId`, `gateway` and `externalId` into `X-Payment-Router-*` headers
-(exported as `ROUTE_ID_HEADER` & co). They are convenience only - anyone who can reach your webhook
-can set them. Log them, decide on the claims.
-
-If the router runs without `WEBHOOK_SIGNING_PRIVATE_KEY` there is no signature to verify and the
-JWKS endpoint 404s: every callback then fails with `missing_signature`, which is the honest answer.
-
-## Errors
-
-Everything thrown extends `PaymentRouterError`.
-
-| Error                          | When                                                          |
-| ------------------------------ | ------------------------------------------------------------- |
-| `PaymentRouterValidationError` | Bad input, caught client-side before anything was sent.       |
-| `InvalidWebhookUrlError`       | `422` - the router refused the URL (not https, private host). |
-| `RateLimitedError`             | `429` - the router's per-IP limit on route creation.          |
-| `PaymentRouterApiError`        | Any other non-2xx; carries `status`, `code`, `body`.          |
-| `PaymentRouterNetworkError`    | No response at all: DNS, TCP, TLS, timeout.                   |
-| `CallbackVerificationError`    | A callback that cannot be trusted; `reason` says why.         |
-
-`CallbackVerificationError.reason` is one of `missing_signature`, `invalid_signature`,
-`body_mismatch`, `malformed_claims`, `body_already_consumed`.
+`verifyCallback` throws if the token is invalid, expired, issued by a different router, or the body
+does not match what was signed.
 
 ## Development
 
 ```bash
 pnpm install
-pnpm test          # vitest, signs real Ed25519 tokens against a fake JWKS
-pnpm run type-check
-pnpm run build     # tsup -> dist/ (esm + cjs + d.ts)
+pnpm test        # node:test, run via tsx
+pnpm type-check
+pnpm build        # tsup -> dist/ (esm + cjs + d.ts)
 ```