@fanth/payment-router-sdk 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,275 +1,41 @@
-import { JWTPayload, JWTVerifyGetKey } from 'jose';
-
-/**
- * The hosted router, used whenever no `baseUrl` is given. Self-hosting the worker? Pass your own
- * origin to the client and the verifier - the verifier's expected `iss` follows it.
- */
-declare const DEFAULT_BASE_URL = "https://payment-r.fanth.pl";
-
-/** Injectable so tests, proxies and edge runtimes can swap in their own implementation. */
-type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
-
-/** Gateways the router ships an adapter for. Any other string is accepted too - adapters are added server-side. */
-type KnownGateway = "payu";
-type GatewayName = KnownGateway | (string & {});
-type CreateRouteInput = {
-    /** The real webhook URL the gateway callback should end up at. Must be https and publicly resolvable. */
+export type CreateRouteOptions = {
     webhookUrl: string;
-    /** Your own id for this payment, echoed back on the forwarded callback (header + `external_id` claim). */
+    /** Caller's own id for this payment, echoed back on the forwarded callback. */
     externalId?: string;
-    /** When callbacks carrying this route id stop being accepted. Anything `Date`-ish is fine. */
-    expiresAt?: Date | string | number;
+    /** Defaults to 12h out on the server if omitted. */
+    expiresAt?: string | Date;
 };
-/** A route as it comes back from `POST /v1/routes`, with timestamps parsed. */
-type PaymentRoute = {
-    /**
-     * The id to hand the gateway as its external payment id (PayU: `extOrderId`). This is the whole
-     * point of the router - the callback carries it back and that is how the real URL is found.
-     */
-    id: string;
-    webhookUrl: string;
-    externalId: string | null;
-    expiresAt: Date | null;
-    createdAt: Date;
-    /**
-     * The fixed URL to paste into each gateway's dashboard, per gateway. The same for every route by
-     * design. `null` when the router has no `PUBLIC_BASE_URL` configured.
-     */
-    callbackUrls: Record<GatewayName, string> | null;
-};
-/** The wire shape of a route, before timestamps are parsed. */
-type RawPaymentRoute = {
+export type PaymentRoute = {
     id: string;
     webhookUrl: string;
     externalId: string | null;
     expiresAt: string | null;
     createdAt: string;
+    /** Gateway name -> the fixed callback URL to paste into that gateway's dashboard. */
     callbackUrls: Record<string, string> | null;
 };
-/** The verified claims of the EdDSA JWT the router puts on every forwarded callback. */
-type CallbackClaims = {
-    /** The route id that matched - the id you handed the gateway. */
+export type CallbackClaims = {
     routeId: string;
-    /** The adapter that handled the callback, e.g. "payu". */
-    gateway: GatewayName;
-    /** Your own id, if you set one when creating the route. */
+    gateway: string;
     externalId: string | null;
-    /** Hex SHA-256 of the callback body, already checked against the body you passed in. */
     bodySha256: string;
-    /** The router's public origin (`iss`). */
-    issuer: string;
-    issuedAt: Date;
-    expiresAt: Date;
-    /** The raw JWT payload, for claims this type does not model. */
-    raw: JWTPayload;
-};
-type VerifiedCallback = {
-    claims: CallbackClaims;
-    /** The callback body, byte for byte as the gateway sent it - parse it with the gateway's own schema. */
-    rawBody: string;
-};
-
-type CallbackVerifierOptions = {
-    /**
-     * The router's public origin: the JWKS URL and, unless overridden, the expected `iss`. Defaults
-     * to {@link DEFAULT_BASE_URL}, the hosted router - set it only when running your own worker.
-     */
-    baseUrl?: string;
-    /** Override the JWKS location, e.g. when it is mirrored somewhere else. */
-    jwksUrl?: string;
-    /** Expected `iss` claim. Defaults to `baseUrl` - must match the router's `PUBLIC_BASE_URL` exactly. */
-    issuer?: string;
-    /** Reject tokens issued longer ago than this, in seconds. Default 300 (the router's own TTL). */
-    maxAgeSeconds?: number;
-    /** Leeway for clock skew between you and the router, in seconds. Default 5. */
-    clockToleranceSeconds?: number;
-    /** Custom fetch for the JWKS request. */
-    fetch?: typeof globalThis.fetch;
-    /** Swap the whole key source, e.g. `createLocalJWKSet` in tests or air-gapped setups. */
-    keyStore?: JWTVerifyGetKey;
-};
-/** The minimum a caller has to hand over: the token and the exact bytes that were delivered. */
-type VerifyInput = {
-    /** The `X-Payment-Router-Signature` header value. */
-    token: string | null | undefined;
-    /** The callback body exactly as received - not re-serialized JSON, or the hash will not match. */
-    rawBody: string | Uint8Array;
-};
-/** Either header shape a runtime hands you: fetch's `Headers` or Node's plain object. */
-type HeaderBag = Record<string, string | string[] | undefined> | Headers;
-declare function jwksUrlFor(baseUrl: string): string;
-/** Pull a header out of either a fetch `Headers` or Node's plain object bag. */
-declare function readHeader(headers: HeaderBag, name: string): string | null;
-/** Hex SHA-256, matching how the router hashes the forwarded body (UTF-8 bytes). */
-declare function sha256Hex(data: string | Uint8Array): Promise<string>;
-
-type PaymentRouterClientOptions = {
-    /**
-     * The router's public origin. Defaults to {@link DEFAULT_BASE_URL}, the hosted one - set it only
-     * when running your own worker. A base path is respected.
-     */
-    baseUrl?: string;
-    /** Custom fetch, for proxies, instrumentation or tests. Defaults to the global one. */
-    fetch?: FetchLike;
-    /** Per-attempt timeout. Default 10s. */
-    timeoutMs?: number;
-    /**
-     * Retries for transient failures (network errors, 429, 502, 503, 504). Default 2.
-     *
-     * 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 one is orphaned. That is harmless - an
-     * unused route is just a row nobody ever calls back on - but set this to 0 if you would rather
-     * see the failure.
-     */
-    maxRetries?: number;
-    /** Base backoff between retries, doubled each attempt. Default 200ms. */
-    retryDelayMs?: number;
-    /** Extra headers on every request, e.g. one your own reverse proxy requires. */
-    headers?: Record<string, string>;
-    /**
-     * Overrides for the callback verifier hanging off this client (issuer, max age, clock tolerance,
-     * ...). `baseUrl` and `fetch` are inherited from the client, so this is usually left alone.
-     */
-    verifier?: Omit<CallbackVerifierOptions, "baseUrl">;
 };
-/**
- * Talks to the payment-router API.
- *
- * The router is a URL shortener for gateway webhooks: you register the real webhook URL, get a UUID
- * back, and hand that UUID to the gateway as its external payment id. The gateway then calls the
- * router's single webhook URL and the router replays the callback at your URL.
- *
- * The other end of the trip - verifying the callback the router forwards back - hangs off the same
- * object, so one `baseUrl` covers both.
- *
- * ```ts
- * const client = new PaymentRouterClient({ baseUrl: "https://router.example.com" });
- * const route = await client.createRoute({ webhookUrl: "https://shop.example.com/webhooks/payu" });
- * // route.id -> PayU's extOrderId, route.callbackUrls.payu -> PayU's notifyUrl
- *
- * const rawBody = await client.verifyWebhook(req.headers, req.body);
- * ```
- */
-declare class PaymentRouterClient {
-    readonly baseUrl: string;
-    private readonly http;
-    private readonly verifierOptions;
-    private cachedVerifier;
-    constructor(options?: PaymentRouterClientOptions);
-    /**
-     * Register a webhook URL and get back the route whose `id` you send to the gateway as its
-     * external payment id.
-     *
-     * @throws {InvalidWebhookUrlError} the router refused the URL (not https, or a private host).
-     * @throws {RateLimitedError} the router's per-IP limit on route creation was hit.
-     */
-    createRoute(input: CreateRouteInput): Promise<PaymentRoute>;
-    /**
-     * The URL to paste into a gateway's dashboard as its single webhook URL. The same for every
-     * route, so it can be read off the client without creating one.
-     */
-    callbackUrl(gateway: GatewayName): string;
-    /** Where the router publishes the public keys that verify forwarded callbacks. */
-    get jwksUrl(): string;
-    /**
-     * Headers and the raw body in, the same raw body back out - or it throws. The short way to guard
-     * a webhook handler: verifies the router's EdDSA JWT against its published keys, and checks that
-     * the body still hashes to what the token claims.
-     *
-     * The body must be the raw bytes as they arrived - parsed-and-re-serialized JSON hashes
-     * differently and will be rejected. Use {@link verifyCallback} when you also want the claims.
-     *
-     * @throws {CallbackVerificationError} when the callback cannot be trusted.
-     */
-    verifyWebhook(headers: HeaderBag, rawBody: string | Uint8Array): Promise<string>;
-    /**
-     * Verify a fetch-API `Request` (Workers, Hono, Next.js, Deno, Bun) and get its claims back.
-     *
-     * The body is read here, so do not read it yourself first - clone the request if you need it.
-     */
-    verifyRequest(request: Request): Promise<VerifiedCallback>;
-    /** Verify a token against the body it covers, and get the claims back. */
-    verifyCallback(input: VerifyInput): Promise<VerifiedCallback>;
-    /**
-     * Built on first use and kept around: the verifier caches the router's key set, so reusing one
-     * client saves a JWKS fetch per callback.
-     */
-    private verifier;
-}
-/** Turn the wire shape into the public one, parsing the ISO timestamps. */
-declare function parseRoute(raw: RawPaymentRoute): PaymentRoute;
-/** Has this route stopped accepting callbacks? Routes without an expiry never do. */
-declare function isRouteExpired(route: PaymentRoute, now?: Date): boolean;
-/** The callback URL for one gateway, or null when the router published none. */
-declare function callbackUrlFor(route: PaymentRoute, gateway: GatewayName): string | null;
-
-/** The slice of Node's `IncomingMessage` needed to drain a body, kept structural to avoid `@types/node` in the public API. */
-type ReadableRequest = AsyncIterable<Uint8Array | string>;
-/**
- * Collect the raw request body from a Node stream, for servers with no body parser of their own.
- *
- * The signature covers the bytes as they arrived, so this deliberately returns the untouched text -
- * parse it afterwards, never before.
- */
-declare function readRawBody(request: ReadableRequest): Promise<string>;
-
-/**
- * Headers the router adds to a forwarded callback. All lowercase - Node lowercases incoming header
- * names, and the fetch `Headers` lookup is case-insensitive anyway.
- *
- * Only the signature header is trustworthy: the others are convenience copies of claims that live
- * inside the signed JWT, and anyone who can reach your webhook can set them. Read them for logs,
- * verify the token for decisions.
- */
-declare const SIGNATURE_HEADER = "x-payment-router-signature";
-declare const ROUTE_ID_HEADER = "x-payment-router-id";
-declare const GATEWAY_HEADER = "x-payment-router-gateway";
-declare const EXTERNAL_ID_HEADER = "x-payment-router-external-id";
-declare const FORWARDED_HOST_HEADER = "x-forwarded-host";
-
-/** Base class for everything this SDK throws, so a single `catch` can tell our failures apart. */
-declare class PaymentRouterError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** The router answered, but with a non-2xx status. `code` is the machine-readable `error` field. */
-declare class PaymentRouterApiError extends PaymentRouterError {
+export declare class PaymentRouterError extends Error {
     readonly status: number;
-    /** The `error` field of the response body, when the router sent one. */
-    readonly code: string | null;
-    /** The parsed (or raw string) response body, for anything the typed fields do not cover. */
     readonly body: unknown;
-    constructor(message: string, status: number, code: string | null, body: unknown);
-}
-/** 429 from `POST /v1/routes` - the router's per-IP rate limit kicked in. Safe to retry later. */
-declare class RateLimitedError extends PaymentRouterApiError {
-}
-/**
- * 422 - the router refused the webhook URL (not https, or pointing at a private/loopback host).
- * Never retry this one, the URL itself has to change.
- */
-declare class InvalidWebhookUrlError extends PaymentRouterApiError {
-    /** The router's human-readable reason, e.g. "webhookUrl must use https". */
-    get reason(): string;
+    constructor(message: string, status: number, body: unknown);
 }
-/** The request never produced a response: DNS, TCP, TLS, timeout or abort. */
-declare class PaymentRouterNetworkError extends PaymentRouterError {
-}
-/** The request did not survive the client-side checks, so nothing was sent. */
-declare class PaymentRouterValidationError extends PaymentRouterError {
-}
-/**
- * A forwarded callback failed verification: missing/expired/forged JWT, wrong issuer, or a body that
- * does not match the `body_sha256` claim. Treat it as an unauthenticated request, never as a payment.
- */
-declare class CallbackVerificationError extends PaymentRouterError {
-    /** Machine-readable failure reason, for logging and metrics. */
-    readonly reason: CallbackVerificationFailure;
-    constructor(reason: CallbackVerificationFailure, message: string, options?: {
-        cause?: unknown;
-    });
+/** Client for a payment-router deployment: create routes, verify signed callbacks. */
+export declare class PaymentRouterClient {
+    #private;
+    constructor(baseUrl?: string);
+    /** Register a webhook URL, get back the route id to hand the gateway plus its callback URLs. */
+    createRoute(options: CreateRouteOptions): Promise<PaymentRoute>;
+    /**
+     * Verify the `X-Payment-Router-Signature` JWT on a forwarded callback. `rawBody` must be the
+     * exact bytes received, since the signature binds `body_sha256`. Throws if the token is
+     * invalid, expired, or the body does not match what was signed.
+     */
+    verifyCallback(token: string, rawBody: string): Promise<CallbackClaims>;
 }
-type CallbackVerificationFailure = "missing_signature" | "invalid_signature" | "body_mismatch" | "malformed_claims" | "body_already_consumed";
-
-export { type CallbackClaims, CallbackVerificationError, type CallbackVerificationFailure, type CallbackVerifierOptions, type CreateRouteInput, DEFAULT_BASE_URL, EXTERNAL_ID_HEADER, FORWARDED_HOST_HEADER, type FetchLike, GATEWAY_HEADER, type GatewayName, type HeaderBag, InvalidWebhookUrlError, type KnownGateway, type PaymentRoute, PaymentRouterApiError, PaymentRouterClient, type PaymentRouterClientOptions, PaymentRouterError, PaymentRouterNetworkError, PaymentRouterValidationError, ROUTE_ID_HEADER, RateLimitedError, type RawPaymentRoute, type ReadableRequest, SIGNATURE_HEADER, type VerifiedCallback, type VerifyInput, callbackUrlFor, isRouteExpired, jwksUrlFor, parseRoute, readHeader, readRawBody, sha256Hex };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,KAAK;aAGrB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,OAAO;IAHjC,YACI,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EAGhC;CACJ;AASD,sFAAsF;AACtF,qBAAa,mBAAmB;;IAI5B,YAAY,OAAO,GAAE,MAAyB,EAG7C;IAED,gGAAgG;IAC1F,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiBpE;IAED;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAc5E;CACJ"}