@openreceive/http 0.4.10 → 0.4.12

package/README.md

@@ -38,8 +38,10 @@ write-once settlement with first-attempt-only fulfillment, and the
 machine (`attention` reads as `pending` on the wire; operators see it only in
 `openreceive_payments.status`). `onPaid` is the settlement hook in both modes: with `db` it receives
 `PaymentSettlement` (`reference` plus a `query` that runs inside the
-settlement transaction); with a custom repository it receives the raw
-`SettlementEvent` (`paymentHash`, `paidAt`, `details`). Settlement
+settlement transaction); with a custom repository it receives
+`SettlementEvent<Transaction>` (`reference`, `paymentHash`, `paidAt`, `details`,
+and `transaction`). The repository awaits fulfillment before commit; failure
+rolls back both payment and host writes. Settlement
 piggybacks on mounted routes by default through the durable `openreceive_meta`
 gate (`opportunisticReconcile: false` disables, `{ minIntervalSeconds }`
 tunes); `startNotificationWorker` is the optional

package/dist/{adapter-surface-DHngkTKQ.d.ts → adapter-surface-Cs4g29Ez.d.ts}

@@ -1,5 +1,5 @@
-import { Checkout, SwapData, NodeSettlementActionHook, CreateCheckoutAmount, NodeSettlementActionInput, OpenReceive } from '@openreceive/node';
-import { ErrorBody, ErrorCode, TransactionSettlementStatus, PaymentDetails } from '@openreceive/core';
+import { Checkout, SwapData, NodeSettlementActionHook, CreateCheckoutAmount, OpenReceive } from '@openreceive/node';
+import { ErrorBody, ErrorCode, TransactionSettlementStatus, PaymentDetails, PaymentScanWindow } from '@openreceive/core';
 
 type AuthorizeAction = "checkout.prepare" | "checkout.create" | "payment.check" | "swap.quote" | "swap.create" | "swap.read" | "swap.refund";
 /**
@@ -152,7 +152,9 @@ interface ReconcilableAttempt {
     readonly paymentHash: string;
     /** Exact NIP-47 invoice creation time returned by make_invoice. */
     readonly createdAt: number;
-    /** Unix timestamp after which the attempt can be closed once a scan confirms no settlement. */
+    readonly createdAtSource?: "wallet" | "host";
+    /** Actual wallet invoice deadline from the saved checkout, never the deposit deadline.
+     * Closure also requires a covering scan after this deadline plus the expiry grace. */
     readonly expiresAt: number;
 }
 /** A terminal (non-settled) state transition observed by reconciliation. */
@@ -185,19 +187,38 @@ interface SettlementRecord {
  * `recordReconciliation` must apply the transition only while the row is still
  * `pending` — it must never overwrite a settled attempt.
  *
- * `recordSettlement` is the write-once settlement claim: the library calls it
- * for every observed settlement and runs the host's own handler only when the
- * call reports the claim won, so a redelivered settlement fulfills once.
+ * `recordSettlementWithFulfillment` locks the reference, records settlement,
+ * and awaits host fulfillment in one transaction. Failure rolls back both writes.
  */
-interface PaymentRepository {
+interface SettlementContext<Transaction = unknown> extends SettlementRecord {
+    readonly reference: string;
+    /** Handle owned by the settlement transaction; never a root connection. */
+    readonly transaction: Transaction;
+}
+interface ReconcileCursor {
+    readonly created_at: number;
+    readonly payment_hash: string;
+}
+interface ReconcileScheduler {
+    cursor: ReconcileCursor | null;
+    windows: PaymentScanWindow[];
+}
+interface ReconcileGateClaim {
+    readonly token: string;
+    readonly scheduler: ReconcileScheduler;
+}
+interface PaymentRepository<Transaction = unknown> {
     listForReference(reference: string): Promise<readonly PaymentRecord[]>;
+    /** Durable acknowledgment for settlement outcomes, including concurrent writes. */
+    findByPaymentHash(paymentHash: string): Promise<PaymentRecord | undefined>;
     /**
-     * The oldest `pending` attempts, terminal rows excluded. A repository with a
-     * large backlog should return an oldest-first batch (the built-in SQL one
-     * caps each pass at OPENRECEIVE_RECONCILE_BATCH_SIZE); the remainder is
-     * covered by later passes.
+     * A bounded keyset page of `pending` attempts ordered by createdAt and hash,
+     * strictly after the supplied cursor; terminal rows are excluded. Return at
+     * OPENRECEIVE_RECONCILE_BATCH_SIZE (200) when that many remain, otherwise
+     * all remaining rows. A short page signals exhaustion; the durable scheduler
+     * wraps immediately so new arrivals cannot postpone old fulfillment retries.
      */
-    listReconcilableAttempts(): Promise<readonly ReconcilableAttempt[]>;
+    listReconcilableAttempts(after?: ReconcileCursor | null): Promise<readonly ReconcilableAttempt[]>;
     /**
      * The `pending` attempt for one payment hash, or undefined when the hash is
      * unknown or already terminal. Direct settlement from an NWC notification
@@ -210,14 +231,15 @@ interface PaymentRepository {
     commitAttempt(input: CheckoutCreatedInput): void | Promise<void>;
     recordReconciliation(transition: ReconciliationTransition): void | Promise<void>;
     /**
-     * Claim the order's first settlement for this attempt and persist it.
+     * Record this pending attempt's settlement under the reference lock, await
+     * fulfillment for the first settled sibling, then commit both writes.
      * Returns true only for the call that won the claim — the attempt was still
      * unsettled AND no sibling attempt on the order had settled. Later calls for
      * the same or a sibling attempt must record the settlement (a genuine second
      * payment is not discarded) and return false. A settled attempt is never
      * overwritten, and an unknown payment hash is a no-op returning false.
      */
-    recordSettlement(settlement: SettlementRecord): boolean | Promise<boolean>;
+    recordSettlementWithFulfillment(settlement: SettlementRecord, fulfill: (context: SettlementContext<Transaction>) => void | Promise<void>): boolean | Promise<boolean>;
     /**
      * Count attempt rows recorded for this client IP at or after `sinceUnixSeconds`.
      * Backs the handler's opt-in `rateLimiting` option; when a custom repository
@@ -226,9 +248,9 @@ interface PaymentRepository {
      */
     countAttemptsFromIp?(clientIp: string, sinceUnixSeconds: number): number | Promise<number>;
     /**
-     * Claim the durable global reconcile gate: return true when this caller may
-     * run a wallet scan now, false when another worker scanned within
-     * `intervalSeconds` (`gate_busy`). The claim MUST be a durable compare-and-set
+     * Claim the durable global reconcile gate: return a token and scheduler when
+     * this caller owns the lease, or null while another lease/interval is active
+     * (`gate_busy`). Persist progress only through the matching unexpired token. The claim MUST be a durable compare-and-set
      * shared by every process on the host database (the built-in SQL repository
      * uses the `openreceive_meta` key/value/rev table) — process-local memory
      * cannot coordinate multiple workers and must never back this. Backs the
@@ -239,6 +261,14 @@ interface PaymentRepository {
     claimReconcileGate?(input: {
         readonly now: number;
         readonly intervalSeconds: number;
+        readonly leaseSeconds?: number;
+    }): ReconcileGateClaim | null | Promise<ReconcileGateClaim | null>;
+    checkpointReconcileGate?(input: {
+        readonly claim: ReconcileGateClaim;
+        readonly scheduler: ReconcileScheduler;
+        readonly now: number;
+        readonly release?: boolean;
+        readonly intervalSeconds?: number;
     }): boolean | Promise<boolean>;
 }
 
@@ -328,7 +358,33 @@ interface PaymentSettlement {
     readonly query: SqlQuery;
 }
 type PaymentSettlementHook = (settlement: PaymentSettlement) => void | Promise<void>;
-interface SqlPaymentRepository extends PaymentRepository {
+/** Nonsecret dry-run report for explicit host/operator review. */
+interface PaymentRepairCandidate {
+    readonly paymentHash: string;
+    readonly reference: string;
+    readonly status: "expired" | "attention";
+    readonly statusReason: string | null;
+    readonly updatedAt: number;
+    readonly instructionExpiresAt: number;
+    readonly settlementExpiresAt: number;
+    readonly category: "early_swap_closure" | "attention";
+}
+interface SqlPaymentRepository extends PaymentRepository<SqlClient> {
+    /** Read-only, hash-keyset candidate report; normal routes never call this. */
+    listRepairCandidates(input?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        candidates: readonly PaymentRepairCandidate[];
+        nextCursor: string | null;
+    }>;
+    /** Requeue one reviewed row only if its reported status and version still match. */
+    requeueAttempt(input: {
+        paymentHash: string;
+        expectedStatus: "expired" | "attention";
+        expectedUpdatedAt: number;
+        reason: string;
+    }): Promise<boolean>;
     /**
      * Replay-safe settlement transaction: set the attempt's `paid_at`/`settled`
      * status once, and run `fulfill` inside the same transaction only for the
@@ -378,35 +434,18 @@ interface CreateHostDbOptions extends CreateOpenReceiveHostBaseOptions {
     readonly onPaid: PaymentSettlementHook;
     readonly payments?: never;
 }
-/**
- * Settlement context passed to repository-mode `onPaid`: the raw core
- * settlement event (`paymentHash`, `paidAt`, `details`). Unlike db-mode's
- * {@link PaymentSettlement} it carries no `reference` and no
- * transactional `query` — the custom repository owns that mapping.
- */
-type SettlementEvent = NodeSettlementActionInput;
-type SettlementEventHook = (settlement: SettlementEvent) => void | Promise<void>;
-/**
- * Advanced escape hatch: the host implements the full
- * `PaymentRepository` contract, including commit locking, write-once
- * settlement, and reconciliation transitions.
- *
- * The settlement hook is `onPaid` in this mode too, but its context type
- * differs from db mode: it receives the raw {@link SettlementEvent}
- * (`paymentHash`, `paidAt`, `details`), with no `reference` and no transactional
- * `query` — unlike db-mode `onPaid`, which runs inside the library's settlement
- * transaction. Write-once is still the library's: repository-mode `onPaid`
- * runs only for the settlement whose `payments.recordSettlement` claim was
- * won, so a redelivered settlement never fulfills twice.
- */
-interface CreateHostRepositoryOptions extends CreateOpenReceiveHostBaseOptions {
-    readonly payments: PaymentRepository;
-    /** Host settlement handler; runs once, for the winning first-settlement claim. */
-    readonly onPaid: SettlementEventHook;
+/** Custom fulfillment receives the resolved reference and its transaction handle. */
+type SettlementEvent<Transaction = unknown> = SettlementContext<Transaction>;
+type SettlementEventHook<Transaction = unknown> = (settlement: SettlementEvent<Transaction>) => void | Promise<void>;
+/** The custom repository awaits onPaid before committing; any failure rolls back both writes. */
+interface CreateHostRepositoryOptions<Transaction = unknown> extends CreateOpenReceiveHostBaseOptions {
+    readonly payments: PaymentRepository<Transaction>;
+    /** Awaited before the winning first-reference settlement transaction commits. */
+    readonly onPaid: SettlementEventHook<Transaction>;
     readonly db?: never;
     readonly tableName?: never;
 }
-type CreateHostOptions = CreateHostDbOptions | CreateHostRepositoryOptions;
+type CreateHostOptions<Transaction = unknown> = CreateHostDbOptions | CreateHostRepositoryOptions<Transaction>;
 interface Host {
     readonly resolveCheckout: ResolveCheckoutHook;
     readonly onCheckoutCreated: CheckoutCreatedHook;
@@ -420,7 +459,7 @@ interface Host {
  * settlement write-once, and reconciliation transitions are library-owned in
  * `db` mode.
  */
-declare function createHost(options: CreateHostOptions): Host;
+declare function createHost<Transaction = unknown>(options: CreateHostOptions<Transaction>): Host;
 /**
  * What the payer is buying, in the host's own words — one optional display
  * string returned beside the price by `amountFor`. It is peeled off here so the
@@ -528,8 +567,10 @@ interface ResolvedHostCheckout {
      * What the payer is buying, in the host's own words — one display string,
      * echoed on the prepare and create responses so the shipped checkout can show
      * something other than a QR and a number. OpenReceive owns no line items and
-     * never will; this is the whole of what it carries. Response only: it is
-     * never read from a request body.
+     * never will; this is the whole of what it carries. Never read from a request
+     * body: the payer does not write the copy next to the amount. On create it is
+     * also the default invoice memo, so the payer's wallet shows the same words
+     * the checkout did.
      */
     readonly description?: string;
     /** Return the selected host payment attempt's hash to reuse or inspect its checkout. */
@@ -697,14 +738,14 @@ type StackWallet = {
  * Where attempts live, which decides what `onPaid` receives. With the host
  * database handle (`db`, the default mode) it is the per-reference
  * `PaymentSettlement`, with `reference` and the transactional `query`;
- * with a custom repository (`payments`, advanced) it is the raw
- * `SettlementEvent`. The branch carries the hook's type, so the
+ * with a custom repository (`payments`, advanced) it includes the resolved
+ * reference and the repository transaction handle. The branch carries the hook's type, so the
  * wrong signature is a type error rather than a runtime surprise.
  */
-type StackStorage = Pick<CreateHostDbOptions, "db" | "tableName" | "onPaid" | "payments"> | Pick<CreateHostRepositoryOptions, "payments" | "onPaid" | "db" | "tableName">;
-interface CreateStackOptions extends Omit<CreateHttpHandlerOptions, "service" | "host">, Omit<CreateHostDbOptions, "db" | "tableName" | "onPaid" | "payments"> {
+type StackStorage<Transaction = unknown> = Pick<CreateHostDbOptions, "db" | "tableName" | "onPaid" | "payments"> | Pick<CreateHostRepositoryOptions<Transaction>, "payments" | "onPaid" | "db" | "tableName">;
+interface CreateStackOptions<Transaction = unknown> extends Omit<CreateHttpHandlerOptions, "service" | "host">, Omit<CreateHostDbOptions, "db" | "tableName" | "onPaid" | "payments"> {
     readonly wallet: StackWallet;
-    readonly storage: StackStorage;
+    readonly storage: StackStorage<Transaction>;
     /**
      * Where the one boot-failure line goes. Boot happens before any service
      * exists, so this is the only sink @openreceive/http can offer; it defaults
@@ -725,7 +766,7 @@ interface Stack {
     /** Closes the service if the stack created it. */
     close(): Promise<void>;
 }
-declare function createStack(options: CreateStackOptions): Stack;
+declare function createStack<Transaction = unknown>(options: CreateStackOptions<Transaction>): Stack;
 /**
  * True when adapter options are the flat all-in-one form (no prebuilt `host`).
  * The composed form always carries `host`; the flat form carries the host
@@ -735,4 +776,4 @@ declare function createStack(options: CreateStackOptions): Stack;
  */
 declare function isStackOptions(options: CreateHttpHandlerOptions | CreateStackOptions): options is CreateStackOptions;
 
-export { hostError as $, type AttemptStatus as A, type SettlementEventHook as B, type CheckoutCreatedHook as C, type SettlementRecord as D, type SqlClient as E, type SqlDatabase as F, type SqlPaymentRepository as G, type Host as H, type IpRateLimitConfig as I, type SqlPaymentsOptions as J, type SqlQuery as K, type Stack as L, type StackStorage as M, type NotificationListener as N, OPENRECEIVE_RECONCILE_BATCH_SIZE as O, type PaymentInsert as P, type StackWallet as Q, type ReconcilableAttempt as R, type SqlAdapter as S, createHost as T, createHttpHandler as U, createIpRateLimit as V, createProxyRateLimitingConfig as W, createRequestId as X, createSqlPayments as Y, createStack as Z, errorResponse as _, type Authorize as a, isServiceErrorShape as a0, isStackOptions as a1, jsonResponse as a2, mapHostRouteError as a3, paymentsSchemaSql as a4, resolveClientIp as a5, startNotificationListener as a6, startNotificationWorker as a7, type AuthorizeAction as b, type AuthorizeContext as c, type AuthorizeResource as d, type CheckoutCreatedInput as e, type CreateHostDbOptions as f, type CreateHostOptions as g, type CreateHostRepositoryOptions as h, type CreateHttpHandlerOptions as i, type CreateStackOptions as j, type HostCheckoutPrice as k, HostError as l, HttpError as m, type HttpHandler as n, type NotificationWorker as o, type PaymentRecord as p, type PaymentRepository as q, type PaymentSettlement as r, type PaymentSettlementHook as s, type RateLimit as t, type ReconciliationTransition as u, type ResolveCheckoutContext as v, type ResolveCheckoutHook as w, type ResolvedHostCheckout as x, type ServiceErrorShape as y, type SettlementEvent as z };
+export { createProxyRateLimitingConfig as $, type AttemptStatus as A, type ResolveCheckoutHook as B, type CheckoutCreatedHook as C, type ResolvedHostCheckout as D, type ServiceErrorShape as E, type SettlementContext as F, type SettlementEvent as G, type Host as H, type IpRateLimitConfig as I, type SettlementEventHook as J, type SettlementRecord as K, type SqlClient as L, type SqlDatabase as M, type NotificationListener as N, OPENRECEIVE_RECONCILE_BATCH_SIZE as O, type PaymentInsert as P, type SqlPaymentRepository as Q, type ReconcilableAttempt as R, type SqlAdapter as S, type SqlPaymentsOptions as T, type SqlQuery as U, type Stack as V, type StackStorage as W, type StackWallet as X, createHost as Y, createHttpHandler as Z, createIpRateLimit as _, type Authorize as a, createRequestId as a0, createSqlPayments as a1, createStack as a2, errorResponse as a3, hostError as a4, isServiceErrorShape as a5, isStackOptions as a6, jsonResponse as a7, mapHostRouteError as a8, paymentsSchemaSql as a9, resolveClientIp as aa, startNotificationListener as ab, startNotificationWorker as ac, type AuthorizeAction as b, type AuthorizeContext as c, type AuthorizeResource as d, type CheckoutCreatedInput as e, type CreateHostDbOptions as f, type CreateHostOptions as g, type CreateHostRepositoryOptions as h, type CreateHttpHandlerOptions as i, type CreateStackOptions as j, type HostCheckoutPrice as k, HostError as l, HttpError as m, type HttpHandler as n, type NotificationWorker as o, type PaymentRecord as p, type PaymentRepairCandidate as q, type PaymentRepository as r, type PaymentSettlement as s, type PaymentSettlementHook as t, type RateLimit as u, type ReconcileCursor as v, type ReconcileGateClaim as w, type ReconcileScheduler as x, type ReconciliationTransition as y, type ResolveCheckoutContext as z };

package/dist/adapter-surface.d.ts

@@ -1,3 +1,3 @@
 export { Checkout, CreateCheckoutAmount, OpenReceive, PaymentCheck, SwapCheckout } from '@openreceive/node';
-export { a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, i as CreateHttpHandlerOptions, j as CreateStackOptions, H as Host, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, o as NotificationWorker, q as PaymentRepository, r as PaymentSettlement, s as PaymentSettlementHook, t as RateLimit, v as ResolveCheckoutContext, w as ResolveCheckoutHook, x as ResolvedHostCheckout, y as ServiceErrorShape, z as SettlementEvent, B as SettlementEventHook, L as Stack, M as StackStorage, Q as StackWallet, U as createHttpHandler, Z as createStack, $ as hostError, a0 as isServiceErrorShape, a3 as mapHostRouteError, a7 as startNotificationWorker } from './adapter-surface-DHngkTKQ.js';
+export { a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, i as CreateHttpHandlerOptions, j as CreateStackOptions, H as Host, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, o as NotificationWorker, r as PaymentRepository, s as PaymentSettlement, t as PaymentSettlementHook, u as RateLimit, z as ResolveCheckoutContext, B as ResolveCheckoutHook, D as ResolvedHostCheckout, E as ServiceErrorShape, G as SettlementEvent, J as SettlementEventHook, V as Stack, W as StackStorage, X as StackWallet, Z as createHttpHandler, a2 as createStack, a4 as hostError, a5 as isServiceErrorShape, a8 as mapHostRouteError, ac as startNotificationWorker } from './adapter-surface-Cs4g29Ez.js';
 import '@openreceive/core';

package/dist/adapter-surface.js

@@ -7,7 +7,7 @@ import {
   isServiceErrorShape,
   mapHostRouteError,
   startNotificationWorker
-} from "./chunk-TJY2HBVU.js";
+} from "./chunk-PGZAFYN6.js";
 export {
   HostError,
   HttpError,