@keelcodes/settlement 0.1.0

package/dist/rails.js

@@ -0,0 +1,147 @@
+import { SettlementError } from './types.js';
+/** The stable order used as the final, documented kind tie-break. */
+export const RAIL_KIND_ORDER = ['x402', 'mpp', 'chain', 'fiat'];
+function assertDecimals(decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new SettlementError('malformed-payload', `decimals must be a non-negative integer, got ${decimals}`);
+    }
+}
+const DECIMAL = /^\d+(\.\d+)?$/;
+/**
+ * Parses a human decimal amount into atomic units for `decimals` places, e.g.
+ * `parseUnits('0.01', 6) === 10000n`.
+ *
+ * Hand-rolled on purpose rather than delegated to `viem`'s `parseUnits`. viem
+ * rounds when the input carries more fractional digits than the asset supports
+ * (`1.234` at 2dp yields `123n`), and its parsing rules have changed between
+ * releases — inheriting either is a poor foundation for settlement arithmetic.
+ * More fractional digits than the asset supports is an error here, not a silent
+ * truncation: rounding someone's money is a bug, not a convenience.
+ *
+ * `rails.units.viem.test.ts` pins both the agreement on the accepted domain and
+ * this intentional divergence, so neither can drift unnoticed.
+ */
+export function parseUnits(value, decimals) {
+    assertDecimals(decimals);
+    if (typeof value !== 'string' || !DECIMAL.test(value)) {
+        throw new SettlementError('malformed-payload', `${JSON.stringify(value)} is not a decimal amount`);
+    }
+    const [whole = '0', fraction = ''] = value.split('.');
+    if (fraction.length > decimals) {
+        throw new SettlementError('malformed-payload', `${value} has more than ${decimals} decimal places`);
+    }
+    return BigInt(whole + fraction.padEnd(decimals, '0'));
+}
+/**
+ * Renders atomic units as a human decimal amount, trimming trailing zeros so
+ * that `parseUnits(formatUnits(n, d), d) === n` round-trips exactly.
+ */
+export function formatUnits(value, decimals) {
+    assertDecimals(decimals);
+    if (decimals === 0)
+        return value.toString();
+    const negative = value < 0n;
+    const digits = (negative ? -value : value).toString().padStart(decimals + 1, '0');
+    const whole = digits.slice(0, digits.length - decimals);
+    const fraction = digits.slice(digits.length - decimals).replace(/0+$/, '');
+    const rendered = fraction === '' ? whole : `${whole}.${fraction}`;
+    return negative ? `-${rendered}` : rendered;
+}
+function matchesAsset(asset, ref) {
+    return (asset.address.toLowerCase() === ref.toLowerCase() ||
+        asset.symbol.toLowerCase() === ref.toLowerCase());
+}
+function findAsset(rail, network, ref) {
+    return rail.assets.find((candidate) => (candidate.networks ?? rail.networks).includes(network) && matchesAsset(candidate, ref));
+}
+/**
+ * Resolves the asset descriptor for `assetRef` on `network`, proving the rail
+ * accepts it there. Throws a `requirement-mismatch` rather than routing a
+ * payment the rail cannot actually settle.
+ */
+export function resolveRailAsset(rail, network, assetRef) {
+    const asset = findAsset(rail, network, assetRef);
+    if (asset === undefined) {
+        throw new SettlementError('requirement-mismatch', `rail ${rail.id} does not accept ${JSON.stringify(assetRef)} on ${network}`);
+    }
+    return asset;
+}
+function isEligible(rail, intent, constraints) {
+    if (constraints.kinds !== undefined && !constraints.kinds.includes(rail.kind))
+        return false;
+    // The plan settles on the intent's network, so it must be an allowed one.
+    if (constraints.networks !== undefined && !constraints.networks.includes(intent.network))
+        return false;
+    if (!rail.networks.includes(intent.network))
+        return false;
+    const asset = findAsset(rail, intent.network, intent.asset);
+    if (asset === undefined)
+        return false;
+    if (constraints.assets !== undefined &&
+        !constraints.assets.some((ref) => matchesAsset(asset, ref))) {
+        return false;
+    }
+    if (rail.kind === 'fiat' && (rail.checkout === undefined || rail.checkout === ''))
+        return false;
+    if (constraints.maxAmount !== undefined && intent.amount + (rail.cost ?? 0n) > constraints.maxAmount) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Total order used for the deterministic pick: cheapest `cost`, then lowest
+ * `priority`, then {@link RAIL_KIND_ORDER}, then lexicographic `id`.
+ */
+function compareRails(a, b) {
+    const costA = a.cost ?? 0n;
+    const costB = b.cost ?? 0n;
+    if (costA !== costB)
+        return costA < costB ? -1 : 1;
+    const priorityA = a.priority ?? 0;
+    const priorityB = b.priority ?? 0;
+    if (priorityA !== priorityB)
+        return priorityA - priorityB;
+    const kindA = RAIL_KIND_ORDER.indexOf(a.kind);
+    const kindB = RAIL_KIND_ORDER.indexOf(b.kind);
+    if (kindA !== kindB)
+        return kindA - kindB;
+    if (a.id < b.id)
+        return -1;
+    if (a.id > b.id)
+        return 1;
+    return 0;
+}
+function describeConstraints(constraints) {
+    return JSON.stringify(constraints, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+}
+/**
+ * Picks the cheapest eligible rail for an intent and materialises the plan.
+ *
+ * Throws `no-acceptable-requirement` when nothing can satisfy the intent and
+ * constraints — never returns a "best effort" pick, because silently routing a
+ * payment on terms the payer did not accept is how an agent overpays.
+ */
+export function selectRail(rails, intent, constraints = {}) {
+    const eligible = rails.filter((rail) => isEligible(rail, intent, constraints));
+    if (eligible.length === 0) {
+        throw new SettlementError('no-acceptable-requirement', `no rail can settle intent ${intent.id} (${intent.amount.toString()} ${intent.asset} on ${intent.network}) under ${describeConstraints(constraints)}`);
+    }
+    const rail = eligible.reduce((best, candidate) => compareRails(candidate, best) < 0 ? candidate : best);
+    const asset = resolveRailAsset(rail, intent.network, intent.asset);
+    const cost = rail.cost ?? 0n;
+    const plan = {
+        railId: rail.id,
+        kind: rail.kind,
+        network: intent.network,
+        asset,
+        amount: intent.amount,
+        amountDecimal: formatUnits(intent.amount, asset.decimals),
+        cost,
+        total: intent.amount + cost,
+        payTo: rail.payTo,
+    };
+    if (rail.checkout !== undefined)
+        plan.checkoutHandle = rail.checkout;
+    return { rail, plan };
+}
+//# sourceMappingURL=rails.js.map

package/dist/rails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails.js","sourceRoot":"","sources":["../src/rails.ts"],"names":[],"mappings":"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"}

package/dist/receipts.d.ts

@@ -0,0 +1,25 @@
+import { type PaymentIntent, type SettlementReceipt } from './types.js';
+import { type X402Requirements, type X402SettlementResponse } from './x402.js';
+/**
+ * Turns a protocol response into a {@link SettlementReceipt}.
+ *
+ * Both builders are deliberately strict: a receipt is evidence, so it is only
+ * produced once the payment demonstrably succeeded *and* the terms still match
+ * the intent. A "successful" settlement of the wrong amount is still wrong.
+ */
+export interface X402ReceiptArgs {
+    intent: PaymentIntent;
+    requirement: X402Requirements;
+    response: X402SettlementResponse;
+    /** ISO-8601 timestamp of settlement. */
+    settledAt: string;
+}
+export declare function receiptFromX402(args: X402ReceiptArgs): SettlementReceipt;
+export interface MppReceiptArgs {
+    intent: PaymentIntent;
+    /** The `Payment-Receipt` header value, kept verbatim as the proof. */
+    receipt: string;
+    settledAt: string;
+}
+export declare function receiptFromMpp(args: MppReceiptArgs): SettlementReceipt;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAElG;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAwBxE;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAoBtE"}

package/dist/receipts.js

@@ -0,0 +1,44 @@
+import { SettlementError } from './types.js';
+import { verifyRequirement } from './x402.js';
+export function receiptFromX402(args) {
+    const { intent, requirement, response } = args;
+    if (!response.success) {
+        throw new SettlementError('unsuccessful-settlement', `x402 settlement failed: ${response.errorReason ?? 'no reason given'}`);
+    }
+    // Re-check after the fact: this response is what the receipt attests to.
+    verifyRequirement(requirement, intent);
+    return {
+        id: response.transaction ?? `${intent.id}@${args.settledAt}`,
+        protocol: 'x402',
+        network: intent.network,
+        asset: intent.asset,
+        amount: intent.amount,
+        payer: response.payer ?? intent.payer,
+        payee: intent.payee,
+        transaction: response.transaction,
+        settledAt: args.settledAt,
+        intentId: intent.id,
+        proof: { requirement, response },
+    };
+}
+export function receiptFromMpp(args) {
+    const token = args.receipt.trim();
+    if (token === '') {
+        throw new SettlementError('missing-field', 'MPP settlement returned an empty Payment-Receipt');
+    }
+    return {
+        // The receipt value identifies the settlement, so re-delivering the same
+        // receipt surfaces as a duplicate rather than a second, phantom payment.
+        id: token,
+        protocol: 'mpp',
+        network: args.intent.network,
+        asset: args.intent.asset,
+        amount: args.intent.amount,
+        payer: args.intent.payer,
+        payee: args.intent.payee,
+        settledAt: args.settledAt,
+        intentId: args.intent.id,
+        proof: { receipt: token },
+    };
+}
+//# sourceMappingURL=receipts.js.map

package/dist/receipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.js","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA8C,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAsD,MAAM,WAAW,CAAC;AAkBlG,MAAM,UAAU,eAAe,CAAC,IAAqB;IACnD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,IAAI,eAAe,CACvB,yBAAyB,EACzB,2BAA2B,QAAQ,CAAC,WAAW,IAAI,iBAAiB,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,yEAAyE;IACzE,iBAAiB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAEvC,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,WAAW,IAAI,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,SAAS,EAAE;QAC5D,QAAQ,EAAE,MAAM;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,MAAM,CAAC,EAAE;QACnB,KAAK,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;KACjC,CAAC;AACJ,CAAC;AASD,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,kDAAkD,CAAC,CAAC;IACjG,CAAC;IAED,OAAO;QACL,yEAAyE;QACzE,yEAAyE;QACzE,EAAE,EAAE,KAAK;QACT,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;QAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;QACxB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;QAC1B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;QACxB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;QACxB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE;QACxB,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;KAC1B,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Which settlement rail a record belongs to. `x402`, `mpp` and `erc8183` are
+ * wire protocols; `chain` (an on-chain stablecoin transfer) and `fiat` (a
+ * hosted checkout) are rail kinds with no Keel codec of their own.
+ */
+export type Protocol = 'x402' | 'mpp' | 'erc8183' | 'chain' | 'fiat';
+/** CAIP-2 chain identifier, e.g. `eip155:8453`. */
+export type Caip2 = `${string}:${string}`;
+export type SettlementErrorCode = 'malformed-payload' | 'unsupported-version' | 'missing-field' | 'invalid-caip2' | 'no-acceptable-requirement' | 'requirement-mismatch' | 'unsuccessful-settlement' | 'duplicate-receipt' | 'unknown-intent' | 'invalid-transition' | 'unauthorized-actor' | 'precondition-failed';
+export declare class SettlementError extends Error {
+    readonly code: SettlementErrorCode;
+    constructor(code: SettlementErrorCode, message: string);
+}
+/**
+ * What the payer intends to pay, in protocol-neutral terms. This is the thing a
+ * client verifies a server's payment requirements *against* — a server can hand
+ * back any `payTo` it likes, so the intent is the anchor that catches it.
+ */
+export interface PaymentIntent {
+    id: string;
+    protocol: Protocol;
+    network: Caip2;
+    /** `native` or a token contract address. */
+    asset: string;
+    /** Atomic units (e.g. 10000 = 0.01 USDC at 6 decimals). */
+    amount: bigint;
+    payer: string;
+    payee: string;
+    /** Free-form resource/order reference. */
+    reference?: string;
+    /** ISO-8601 expiry, when the protocol carries one. */
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export type IntentStatus = 'pending' | 'settled' | 'failed';
+/**
+ * Proof that a payment settled. `id` is stable and unique per settlement — the
+ * on-chain transaction hash where the protocol provides one, and an
+ * intent-scoped reference otherwise.
+ */
+export interface SettlementReceipt {
+    id: string;
+    protocol: Protocol;
+    network: Caip2;
+    asset: string;
+    amount: bigint;
+    payer: string;
+    payee: string;
+    transaction?: string;
+    settledAt: string;
+    intentId?: string;
+    /** Protocol-specific proof, kept verbatim for audit. */
+    proof?: Record<string, unknown>;
+}
+/** A signed value movement on the ledger: positive credits, negative debits. */
+export interface LedgerEntry {
+    account: string;
+    network: string;
+    asset: string;
+    amount: bigint;
+    reference?: string;
+}
+/**
+ * The reconciliation ledger is an append-only event log; intent status and
+ * balances are *derived* by folding it, never stored mutably.
+ *
+ * Whether a settled payment moves a balance is a billing concern and is
+ * deliberately not modelled here — `entry` events are the only thing that
+ * affects `balanceOf`.
+ */
+export type LedgerEvent = {
+    kind: 'intent';
+    at: string;
+    intent: PaymentIntent;
+} | {
+    kind: 'receipt';
+    at: string;
+    receipt: SettlementReceipt;
+} | {
+    kind: 'failure';
+    at: string;
+    intentId: string;
+    reason: string;
+} | {
+    kind: 'entry';
+    at: string;
+    entry: LedgerEntry;
+};
+export interface Reconciliation {
+    /** Intent ids with no receipt — expected money that never arrived. */
+    unsettled: string[];
+    /** Receipt ids with no matching intent — money from an unknown intent. */
+    orphans: string[];
+    /** Intent ids with more than one receipt — a possible double settlement. */
+    doubleSettled: string[];
+    ok: boolean;
+}
+export declare function isCaip2(value: string): value is Caip2;
+export declare function assertCaip2(value: unknown, field: string): Caip2;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,19 @@
+export class SettlementError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SettlementError';
+        this.code = code;
+    }
+}
+const CAIP2 = /^[a-z0-9-]{3,8}:[a-zA-Z0-9-]{1,64}$/;
+export function isCaip2(value) {
+    return CAIP2.test(value);
+}
+export function assertCaip2(value, field) {
+    if (typeof value !== 'string' || !isCaip2(value)) {
+        throw new SettlementError('invalid-caip2', `${field} is not a CAIP-2 chain id: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwBA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAsB;IAEnC,YAAY,IAAyB,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AA+ED,MAAM,KAAK,GAAG,qCAAqC,CAAC;AAEpD,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,KAAa;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,GAAG,KAAK,8BAA8B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,106 @@
+import { type LedgerEvent, type Protocol } from './types.js';
+/**
+ * Multi-protocol webhook egress.
+ *
+ * Every rail in this package — x402, MPP, A2A's x402 extension, ERC-8183
+ * escrow — folds into the same append-only {@link LedgerEvent} log, so outbound
+ * notifications need only one normalised event shape. A {@link WebhookEvent}
+ * is that shape; {@link WebhookDispatcher} matches it against subscriptions and
+ * delivers it with retries and a per-delivery audit trail.
+ *
+ * Signing is a port, not baked in: the core carries no crypto dependency and
+ * runs anywhere, so the host wires its own HMAC (`WebhookSigner`) — the same
+ * way scheme payloads are left to the caller. A delivery is only signed when a
+ * subscription carries a `secret` and a signer is configured.
+ */
+export type WebhookEventType = 'intent.created' | 'settlement.succeeded' | 'settlement.failed' | 'ledger.entry';
+/** The transport-neutral event a subscription receives. */
+export interface WebhookEvent {
+    /** Stable per source event — safe to use as an idempotency key. */
+    id: string;
+    type: WebhookEventType;
+    /** ISO-8601, taken from the ledger event. */
+    at: string;
+    protocol?: Protocol;
+    data: unknown;
+}
+/**
+ * Normalises a ledger event into a webhook event. Ids are derived from the
+ * source record so replaying the same log yields the same delivery ids.
+ */
+export declare function webhookEventFromLedgerEvent(event: LedgerEvent): WebhookEvent;
+export interface WebhookSubscription {
+    id: string;
+    url: string;
+    /** Event types to receive; all when omitted. */
+    events?: readonly WebhookEventType[];
+    /** Restrict to these rails; events without a protocol are dropped. */
+    protocols?: readonly Protocol[];
+    /** Enables signing for this subscription. */
+    secret?: string;
+    /** Defaults to active. */
+    active?: boolean;
+}
+export declare function matchesWebhook(subscription: WebhookSubscription, event: WebhookEvent): boolean;
+export interface WebhookRequest {
+    subscriptionId: string;
+    eventId: string;
+    url: string;
+    /** JSON body. */
+    body: string;
+    headers: Record<string, string>;
+}
+export interface WebhookResponse {
+    status: number;
+}
+/** How a request actually leaves the process — `fetch`, a queue, a test double. */
+export type WebhookTransport = (request: WebhookRequest) => Promise<WebhookResponse>;
+export type WebhookSigner = (args: {
+    secret: string;
+    /** Unix seconds, also sent in `x-keel-timestamp`. */
+    timestamp: string;
+    body: string;
+}) => string | Promise<string>;
+export interface WebhookAttempt {
+    attempt: number;
+    at: string;
+    status?: number;
+    error?: string;
+    ok: boolean;
+}
+export interface WebhookDelivery {
+    subscriptionId: string;
+    eventId: string;
+    attempts: WebhookAttempt[];
+    ok: boolean;
+}
+export interface WebhookDispatcherOptions {
+    transport: WebhookTransport;
+    signer?: WebhookSigner;
+    clock?: () => Date;
+    /** Total tries per delivery. Defaults to 3. */
+    maxAttempts?: number;
+    /** Delay before the next attempt; defaults to exponential backoff. */
+    backoffMs?: (attempt: number) => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Static extra headers, or a function of the event/subscription. */
+    headers?: Record<string, string> | ((event: WebhookEvent, subscription: WebhookSubscription) => Record<string, string>);
+}
+/**
+ * Fans a webhook event out to matching subscriptions and records what happened.
+ *
+ * A delivery is retried on a network throw or a non-2xx status, up to
+ * `maxAttempts`; the returned {@link WebhookDelivery} keeps every attempt so a
+ * consumer can audit or replay it.
+ */
+export declare class WebhookDispatcher {
+    private readonly options;
+    constructor(options: WebhookDispatcherOptions);
+    dispatch(subscriptions: readonly WebhookSubscription[], event: WebhookEvent): Promise<WebhookDelivery[]>;
+    private now;
+    private backoff;
+    private sleep;
+    private buildHeaders;
+    private deliver;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/webhooks.js

@@ -0,0 +1,162 @@
+import { SettlementError } from './types.js';
+/**
+ * Normalises a ledger event into a webhook event. Ids are derived from the
+ * source record so replaying the same log yields the same delivery ids.
+ */
+export function webhookEventFromLedgerEvent(event) {
+    switch (event.kind) {
+        case 'intent':
+            return {
+                id: `intent.created:${event.intent.id}`,
+                type: 'intent.created',
+                at: event.at,
+                protocol: event.intent.protocol,
+                data: event.intent,
+            };
+        case 'receipt':
+            return {
+                id: `settlement.succeeded:${event.receipt.id}`,
+                type: 'settlement.succeeded',
+                at: event.at,
+                protocol: event.receipt.protocol,
+                data: event.receipt,
+            };
+        case 'failure':
+            return {
+                id: `settlement.failed:${event.intentId}@${event.at}`,
+                type: 'settlement.failed',
+                at: event.at,
+                data: { intentId: event.intentId, reason: event.reason },
+            };
+        case 'entry':
+            return {
+                id: `ledger.entry:${event.entry.account}@${event.at}`,
+                type: 'ledger.entry',
+                at: event.at,
+                data: event.entry,
+            };
+    }
+}
+export function matchesWebhook(subscription, event) {
+    if (subscription.active === false)
+        return false;
+    if (subscription.events !== undefined && !subscription.events.includes(event.type))
+        return false;
+    if (subscription.protocols !== undefined) {
+        if (event.protocol === undefined)
+            return false;
+        if (!subscription.protocols.includes(event.protocol))
+            return false;
+    }
+    return true;
+}
+function isSuccess(status) {
+    return status >= 200 && status < 300;
+}
+/**
+ * JSON encoding with `bigint` rendered as a decimal string. Ledger records carry
+ * atomic-unit amounts as `bigint`, and `JSON.stringify` throws on those.
+ */
+function encodeBody(event) {
+    return JSON.stringify({
+        id: event.id,
+        type: event.type,
+        at: event.at,
+        protocol: event.protocol,
+        data: event.data,
+    }, (_key, value) => (typeof value === 'bigint' ? value.toString() : value));
+}
+/**
+ * Fans a webhook event out to matching subscriptions and records what happened.
+ *
+ * A delivery is retried on a network throw or a non-2xx status, up to
+ * `maxAttempts`; the returned {@link WebhookDelivery} keeps every attempt so a
+ * consumer can audit or replay it.
+ */
+export class WebhookDispatcher {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async dispatch(subscriptions, event) {
+        const deliveries = [];
+        for (const subscription of subscriptions) {
+            if (!matchesWebhook(subscription, event))
+                continue;
+            deliveries.push(await this.deliver(subscription, event));
+        }
+        return deliveries;
+    }
+    now() {
+        return this.options.clock?.() ?? new Date();
+    }
+    backoff(attempt) {
+        if (this.options.backoffMs !== undefined)
+            return this.options.backoffMs(attempt);
+        return 250 * 2 ** (attempt - 1);
+    }
+    sleep(ms) {
+        if (this.options.sleep !== undefined)
+            return this.options.sleep(ms);
+        const schedule = globalThis
+            .setTimeout;
+        if (schedule === undefined) {
+            throw new SettlementError('precondition-failed', 'no timer available; pass options.sleep');
+        }
+        return new Promise((resolve) => {
+            schedule(() => resolve(), ms);
+        });
+    }
+    async buildHeaders(subscription, event, body) {
+        const timestamp = Math.floor(this.now().getTime() / 1000).toString();
+        const extra = typeof this.options.headers === 'function'
+            ? this.options.headers(event, subscription)
+            : this.options.headers ?? {};
+        const headers = {
+            'content-type': 'application/json',
+            'x-keel-event': event.type,
+            'x-keel-event-id': event.id,
+            'x-keel-timestamp': timestamp,
+            ...extra,
+        };
+        if (this.options.signer !== undefined && subscription.secret !== undefined) {
+            const value = await this.options.signer({ secret: subscription.secret, timestamp, body });
+            headers['x-keel-signature'] = `t=${timestamp},v1=${value}`;
+        }
+        return headers;
+    }
+    async deliver(subscription, event) {
+        const maxAttempts = this.options.maxAttempts ?? 3;
+        const body = encodeBody(event);
+        const attempts = [];
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            const at = this.now().toISOString();
+            try {
+                const headers = await this.buildHeaders(subscription, event, body);
+                const response = await this.options.transport({
+                    subscriptionId: subscription.id,
+                    eventId: event.id,
+                    url: subscription.url,
+                    body,
+                    headers,
+                });
+                const ok = isSuccess(response.status);
+                attempts.push({ attempt, at, status: response.status, ok });
+                if (ok)
+                    return { subscriptionId: subscription.id, eventId: event.id, attempts, ok: true };
+            }
+            catch (error) {
+                attempts.push({
+                    attempt,
+                    at,
+                    error: error instanceof Error ? error.message : String(error),
+                    ok: false,
+                });
+            }
+            if (attempt < maxAttempts)
+                await this.sleep(this.backoff(attempt));
+        }
+        return { subscriptionId: subscription.id, eventId: event.id, attempts, ok: false };
+    }
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}