@elisym/commerce 0.3.0 → 0.4.0

package/dist/buyer.d.ts

@@ -1,8 +1,9 @@
 import { NostrEvent, EventTemplate, VerifiedEvent, Filter } from 'nostr-tools';
 import { SimplePool } from 'nostr-tools/pool';
 import { Rpc, SolanaRpcApi, KeyPairSigner } from '@solana/kit';
-import { ChainFamily, Network, ChainConfig, Asset, PaymentRequestData } from '@elisym/pay-core';
+import { ChainFamily, Network, ChainConfig, Asset, PaymentRequestData, ParsedPaymentRequestV2 } from '@elisym/pay-core';
 import { t as OfferWarning, F as FetchLike, b as DomainKeys, X as VerifiedOffer, H as PayoutTarget, r as OfferRefusal, x as OrderStatusMessage } from './verify-offer-BZ_a9x3L.js';
+import { Eip1193Client } from '@elisym/pay-core/evm';
 import 'zod';
 
 /**
@@ -376,8 +377,18 @@ interface OrderRecord {
     marker?: PaymentMarker;
     /** The transaction that paid, once found. */
     paidTx?: string;
+    /** Wall-clock seconds when the payment was found (UI only: the "no answer" timer). */
+    paidAt?: number;
     status?: OrderStatus;
+    /**
+     * Tempo only: why the record ended unpaid, written in the same write and never
+     * changed. `over` means a wallet prompt may still be open and could still be approved.
+     */
+    endedBy?: EndedBy;
+    /** Tempo `over` records whose old-prompt warning the buyer confirmed for THIS record. */
+    confirmedOverIds?: string[];
 }
+type EndedBy = 'rejected' | 'over' | 'nothing';
 declare const TERMINAL_STATES: readonly OrderState[];
 declare function isTerminal(record: Pick<OrderRecord, 'state'>): boolean;
 /**
@@ -412,18 +423,22 @@ type StoreWrite = {
      * `missing`: no such record. `conflict`: the record (its version or its
      * marker's attempt) is not the one the caller judged. `exclusion`: another
      * record for this product holds a live payment. `not_ready`: the record's
-     * state does not allow this write.
+     * state does not allow this write. `needs_confirmation`: a Tempo order of
+     * this product ended `over` - its wallet prompt may still be approved - and
+     * the buyer has not confirmed the warning for it on this record.
      */
-    reason: 'missing' | 'conflict' | 'exclusion' | 'not_ready';
+    reason: 'missing' | 'conflict' | 'exclusion' | 'not_ready' | 'needs_confirmation';
     /** For `exclusion`: the order holding it. */
     holder?: string;
+    /** For `needs_confirmation`: the ended orders to confirm. */
+    unconfirmed?: string[];
 };
 /**
  * Fields a plain update may change. What the order and its payment were made of
  * (payout, amount, reference, offer, ...) is fixed when the record is added; the
  * marker and the version have their own paths.
  */
-type RecordPatch = Partial<Pick<OrderRecord, 'state' | 'paymentRequest' | 'orderWrap' | 'receiptWrap' | 'inboxRelays' | 'acknowledgedRelays' | 'paidTx' | 'status'>>;
+type RecordPatch = Partial<Pick<OrderRecord, 'state' | 'paymentRequest' | 'orderWrap' | 'receiptWrap' | 'inboxRelays' | 'acknowledgedRelays' | 'paidTx' | 'paidAt' | 'status' | 'endedBy' | 'confirmedOverIds'>>;
 /**
  * Where order records live. Every money rule is judged by the core (below) on
  * what `transactProduct` hands it; a backend only makes that read-judge-write
@@ -466,21 +481,21 @@ declare function judgeUpdate(records: readonly OrderRecord[], orderId: string, e
  * its composed request and no marker - and no OTHER record for the product
  * holds a live payment (two tabs cannot both pay).
  */
-declare function judgeSetMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, marker: PaymentMarker): Judged;
+declare function judgeSetMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, marker: PaymentMarker, now?: number): Judged;
 /**
  * Change the marker of the attempt `attemptId` - record its signature or hash,
  * or replace it with a retry's marker (same record, order and reference). Both
  * the attempt and the record version must be the ones the caller judged: a
  * signature recorded in between is never overrun.
  */
-declare function judgeUpdateMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker): Judged;
+declare function judgeUpdateMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker, now?: number): Judged;
 /**
  * End the attempt `attemptId`, judged at `expectedVersion`: nothing was
  * requested (`ordered`, the marker is removed), or the attempt provably ended
  * (`ended-unpaid`, the marker is KEPT - it no longer excludes, but its floor,
  * signature or hash is what later reconciliation starts from).
  */
-declare function judgeClearMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>): Judged;
+declare function judgeClearMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>, endedBy?: Exclude<EndedBy, 'nothing'>): Judged;
 /**
  * After a delivery: pin the store's owner, and add every payout of the offer
  * that delivered to the known ones (pinning only the paid one would flag every
@@ -514,11 +529,11 @@ declare class OrderStore {
     /** Change plain fields of the record the caller judged at `expectedVersion`. */
     update(orderId: string, expectedVersion: number, patch: RecordPatch): Promise<StoreWrite>;
     /** See `judgeSetMarker`. */
-    setMarker(orderId: string, expectedVersion: number, marker: PaymentMarker): Promise<StoreWrite>;
+    setMarker(orderId: string, expectedVersion: number, marker: PaymentMarker, now?: number): Promise<StoreWrite>;
     /** See `judgeUpdateMarker`. */
-    updateMarker(orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker): Promise<StoreWrite>;
+    updateMarker(orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker, now?: number): Promise<StoreWrite>;
     /** See `judgeClearMarker`. */
-    clearMarker(orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>): Promise<StoreWrite>;
+    clearMarker(orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>, endedBy?: Exclude<EndedBy, 'nothing'>): Promise<StoreWrite>;
     pins(storePubkey: string): Promise<StorePinsRecord | undefined>;
     /** See `mergePins`. */
     rememberDelivery(storePubkey: string, ownerPubkey: string, payouts: readonly {
@@ -547,7 +562,7 @@ declare class MemoryOrderBackend implements OrderBackend {
     }): Promise<T>;
 }
 
-type ReadyOffer$1 = Extract<LoadedOffer, {
+type ReadyOffer$2 = Extract<LoadedOffer, {
     ok: true;
 }>;
 /** The receipt `medium` of a chain: `solana`, `solana-devnet`, `tempo`, `tempo-moderato`. */
@@ -563,10 +578,10 @@ declare function clockAgrees(chainTime: number, deviceTime: number): boolean;
  * and price and no new warning to confirm (`same`); something the buyer must
  * look at again (`changed`); or the chosen payout is gone (`gone`).
  */
-declare function compareOffers(shown: PricedPayout, confirmed: readonly OfferWarning[], fresh: ReadyOffer$1): 'same' | 'changed' | 'gone';
+declare function compareOffers(shown: PricedPayout, confirmed: readonly OfferWarning[], fresh: ReadyOffer$2): 'same' | 'changed' | 'gone';
 interface PlaceOrderInput {
     /** A FRESH verified offer (at most two minutes old). */
-    offer: ReadyOffer$1;
+    offer: ReadyOffer$2;
     payout: PricedPayout;
     email?: string;
     /** Chain time read just before ordering (seconds). */
@@ -651,7 +666,7 @@ declare function listenForStatus(record: OrderRecord, relays: readonly string[],
     close(): void;
 };
 
-type ReadyOffer = Extract<LoadedOffer, {
+type ReadyOffer$1 = Extract<LoadedOffer, {
     ok: true;
 }>;
 /**
@@ -703,7 +718,7 @@ interface SolanaPayDeps extends OrderDeps {
 }
 interface PayInput {
     /** A FRESH verified offer (at most two minutes old): the payout and price are checked against it. */
-    fresh: ReadyOffer;
+    fresh: ReadyOffer$1;
     /** Chain time read just before (seconds). */
     chainTime: number;
 }
@@ -731,7 +746,12 @@ type SolanaPayRefusal =
 /** A retry before the last attempt provably ended. */
  | 'still_waiting' | 'already_paid'
 /** The caller's spend limit refused the attempt's costs (`reserve` threw). Nothing was recorded. */
- | 'spend_limit';
+ | 'spend_limit'
+/**
+ * A Tempo order of this product ended with its wallet prompt still open:
+ * the buyer confirms the warning (`confirmedOverIds`) before this request.
+ */
+ | 'needs_confirmation';
 type SolanaPayResult = {
     ok: true;
     record: OrderRecord;
@@ -742,6 +762,8 @@ type SolanaPayResult = {
     record?: OrderRecord;
     /** For `exclusion`: the order holding it. */
     holder?: string;
+    /** For `needs_confirmation`: the ended orders to confirm. */
+    unconfirmed?: string[];
     /** For `insufficient_*`: what the payment needs and what the payer has, in subunits / lamports. */
     needed?: bigint;
     available?: bigint;
@@ -901,6 +923,8 @@ declare function onOtherTerms(record: OrderRecord, payout: PricedPayout): boolea
 type EndDeps = Pick<SolanaPayDeps, 'store' | 'readClient' | 'clientFor' | 'now' | 'canProveOver'> & {
     /** The order's own network's RPC, or `undefined` when the caller has none for it. */
     rpc: SolanaPayDeps['rpc'] | undefined;
+    /** For a Tempo order: a read RPC of its own chain, or `undefined` when the caller has none. */
+    tempo?: Eip1193Client;
     store: OrderStore;
 };
 /**
@@ -918,4 +942,166 @@ declare function endOrder(record: OrderRecord, deps: EndDeps): Promise<{
     record: OrderRecord;
 }>;
 
-export { type AuthSigner, CONFIRM_WARNINGS, DEFAULT_RELAYS, type EndDeps, type LoadOfferOptions, type LoadedOffer, MAX_CLOCK_SKEW_SECS, MAX_RELAY_URL_LENGTH, MERCHANT_CATCH_UP_SECS, MemoryOrderBackend, OFFER_SNAPSHOT_MAX_AGE_SECS, ORDER_ACK_TARGET, type OrderBackend, type OrderDeps, type OrderRecord, type OrderState, type OrderStatus, OrderStore, PAYMENT_SCAN_MARGIN_SECS, PAY_CUTOFF_SECS, type PayInput, type PaymentCosts, type PaymentMarker, type PlaceOrderInput, type PlaceOrderResult, type PoolLike, type PricedPayout, type PublishResult, RELAY_CONNECT_MAX_WAIT_MS, RELAY_PUBLISH_DEADLINE_MS, RELAY_QUERY_DEADLINE_MS, RELAY_QUERY_MAX_WAIT_MS, type RecordPatch, type RelayClient, type RelayClientOptions, type RelayLike, SOLANA_COMPUTE_UNIT_LIMIT, STORE_RELAY_CAP, STORE_WRITE_ATTEMPTS, SUBSCRIBE_RETRY_MAX_MS, SUBSCRIBE_RETRY_MS, SUBSCRIBE_STABLE_MS, type SignedRefusal, type SolanaPayDeps, type SolanaPayRefusal, type SolanaPayResult, type SolanaWallet, type SolanaWatch, type StoreInbox, type StorePins, type StorePinsRecord, type StoreRelaySources, type StoreWrite, TERMINAL_STATES, WRAP_BACKDATE_SECS, type WidgetRefusal, applyStatus, cancelledUnpaid, checkBeforePaying, checkSignedTransaction, clockAgrees, compareOffers, composeOrderPayment, createPool, createRelayClient, deliveryLink, endOrder, endSolanaOrder, gone, holdsPayExclusion, isEventShaped, isGenuineEvent, isPageOrigin, isSnapshotStale, isTerminal, judgeAdd, judgeClearMarker, judgeSetMarker, judgeUpdate, judgeUpdateMarker, listenForStatus, loadOffer, loadOfferForAgent, localSolanaWallet, mediumOf, mergePins, newestGenuine, newestStoreInbox, normalizeRelayUrl, nowSecs, onOtherTerms, payWithSolana, placeOrder, readChainTime, readRelays, readStoreInbox, recordToShow, relayHost, resumeOrder, retryWithSolana, sendReceipt, statusFor, storeRelays, storedSolanaRequest, uniqueRelays, watchSolanaPayment };
+/**
+ * Paying an acknowledged order on Tempo, and reconciling it.
+ *
+ * The rules differ from Solana's where the chain does: a Tempo wallet prompt
+ * has no deadline and a relayer can land an approved payment under a new
+ * hash, so there is no retry here - an attempt holding a sent hash stays live
+ * until it is found, and an attempt proven unpaid (`over`) ends the order with
+ * its prompt still open (the store asks for confirmation before any other
+ * payment of the product, see `judgeSetMarker`).
+ */
+
+type ReadyOffer = Extract<LoadedOffer, {
+    ok: true;
+}>;
+interface TempoPayDeps extends OrderDeps {
+    /** A read RPC of the record's own Tempo chain. */
+    client: Eip1193Client;
+    /** The device clock (seconds): the marker's `setAt`, the receipt's date. */
+    now?: () => number;
+    newAttemptId?: () => string;
+}
+/** An EIP-1193 wallet, reduced to what one payment needs. */
+interface TempoWallet {
+    /** The payer, 0x. */
+    address: string;
+    /** `eth_chainId` as the WALLET answers it. */
+    chainId(): Promise<number>;
+    /**
+     * `eth_sendTransaction` of one call; resolves the hash the wallet returned.
+     * A user refusal rejects with an error carrying `code: 4001`.
+     */
+    sendCall(call: {
+        from: string;
+        to: string;
+        data: string;
+        chainId: string;
+    }): Promise<string>;
+}
+type TempoPayRefusal = 
+/** The record cannot take a payment now (state, request, the store closed it). */
+'not_payable'
+/** The offer snapshot is older than two minutes: verify again. */
+ | 'stale_offer'
+/** The store no longer offers this payout at this price: end this order and start a new one. */
+ | 'offer_changed'
+/** Too close to the merchant's catch-up end, or to the request's deadline: a new order. */
+ | 'too_late'
+/** The payee is a Tempo system address or a coin contract: nothing can pay it. */
+ | 'unpayable' | 'self_payment' | 'insufficient_token'
+/** The recipient's receive policy refuses this payer: the money would sit with the guard. */
+ | 'policy_blocked'
+/** The read RPC, or the wallet, is on another chain. */
+ | 'wrong_chain'
+/** A chain read failed; nothing was requested. */
+ | 'rpc_error' | 'exclusion' | 'needs_confirmation' | 'conflict'
+/** The buyer refused in the wallet (4001): nothing was signed, the order ended. */
+ | 'rejected'
+/** The wallet did not answer with a hash: the attempt stays live ("check your wallet"). */
+ | 'wallet_failed';
+type TempoPayResult = {
+    ok: true;
+    record: OrderRecord;
+    hash: string;
+    /** The hash could not be stored yet: keep it in memory and pass it to the watch. */
+    hashUnsaved?: boolean;
+} | {
+    ok: false;
+    reason: TempoPayRefusal;
+    record?: OrderRecord;
+    holder?: string;
+    unconfirmed?: string[];
+    /** For `insufficient_token`: subunits. */
+    needed?: bigint;
+    available?: bigint;
+};
+/** What the buyer keeps beyond the price for the wallet's own fee (MetaMask takes it in the coin). */
+declare function tempoFeeMargin(decimals: number): bigint;
+/** The request stored on the record, as the schema reads it. */
+declare function storedTempoRequest(record: OrderRecord): ParsedPaymentRequestV2 | undefined;
+/** The chain's time, from its finalized head: what a Tempo order rumor is dated with. */
+declare function readTempoChainTime(client: Eip1193Client): Promise<number>;
+/** Store the hash of attempt `attemptId`, re-reading on a lost compare-and-swap. */
+declare function saveTempoHash(record: OrderRecord, attemptId: string, hash: string, deps: Pick<TempoPayDeps, 'store'>): Promise<{
+    saved: boolean;
+    record: OrderRecord;
+    stopped?: boolean;
+}>;
+/**
+ * Pay an acknowledged order: checks, the request, the pay floor, the marker
+ * (test-and-set with the product exclusion and the old-prompt confirmation),
+ * the wallet's chain re-read, ONE `eth_sendTransaction`. A proving rejection
+ * ends the order; any other failure keeps the attempt live.
+ */
+declare function payWithTempo(record: OrderRecord, wallet: TempoWallet, fresh: ReadyOffer, deps: TempoPayDeps): Promise<TempoPayResult>;
+type TempoWatch = 
+/** The payment was found and recorded. */
+{
+    state: 'paid';
+    record: OrderRecord;
+}
+/**
+ * Nothing yet, or a sent hash still unresolved: keep watching. `pastDeadline`:
+ * the request's late deadline passed and a hash is still unresolved (the
+ * "check your wallet, or contact the store" case).
+ */
+ | {
+    state: 'waiting';
+    record: OrderRecord;
+    pastDeadline?: boolean;
+}
+/** No hash, no pending call, and a vouched "not paid" past the late deadline. */
+ | {
+    state: 'over';
+    record: OrderRecord;
+}
+/** The money sits with the recipient's transfer-policy guard. */
+ | {
+    state: 'blocked';
+    record: OrderRecord;
+}
+/** The chain answered something no verdict rests on: keep watching, say so after a while. */
+ | {
+    state: 'unsure';
+    record: OrderRecord;
+}
+/** Delivered or refunded: nothing is left to watch. */
+ | {
+    state: 'closed';
+    record: OrderRecord;
+};
+interface TempoWatchOptions {
+    /** A hash returned in this session that is not stored yet: it counts as a pending call. */
+    pendingHash?: string;
+    /** A wallet call of this session is still unanswered. */
+    callPending?: boolean;
+}
+/**
+ * One reconciliation step for a Tempo attempt, or for a Tempo order that ended
+ * `over` (its prompt can still be approved). Only `none` with no hash, no
+ * pending call and a live attempt - the verifier vouches `none` only past the
+ * late deadline - is `over`.
+ */
+declare function watchTempoPayment(record: OrderRecord, deps: TempoPayDeps, options?: TempoWatchOptions): Promise<TempoWatch>;
+/** The late deadline of a request: after it a vouched "not paid" is final for an attempt with no hash. */
+declare function tempoLateDeadline(request: ParsedPaymentRequestV2): number;
+/**
+ * End a Tempo order that will not be paid: at once when nothing was requested;
+ * with an attempt, only once the watch proves it over - it ends `over`, its
+ * prompt still open.
+ */
+declare function endTempoOrder(record: OrderRecord, deps: TempoPayDeps, options?: TempoWatchOptions): Promise<{
+    ended: boolean;
+    record: OrderRecord;
+}>;
+/**
+ * Whether an ended Tempo order may still be paid: it ended `over` (or with no
+ * reason, fail closed) inside the merchant's catch-up, judged on the device
+ * clock with the skew allowance. The same predicate as the store's
+ * confirmation, for the per-load reconciliation.
+ */
+declare function mayStillBePaid(record: OrderRecord, now: number): boolean;
+
+export { type AuthSigner, CONFIRM_WARNINGS, DEFAULT_RELAYS, type EndDeps, type EndedBy, type LoadOfferOptions, type LoadedOffer, MAX_CLOCK_SKEW_SECS, MAX_RELAY_URL_LENGTH, MERCHANT_CATCH_UP_SECS, MemoryOrderBackend, OFFER_SNAPSHOT_MAX_AGE_SECS, ORDER_ACK_TARGET, type OrderBackend, type OrderDeps, type OrderRecord, type OrderState, type OrderStatus, OrderStore, PAYMENT_SCAN_MARGIN_SECS, PAY_CUTOFF_SECS, type PayInput, type PaymentCosts, type PaymentMarker, type PlaceOrderInput, type PlaceOrderResult, type PoolLike, type PricedPayout, type PublishResult, RELAY_CONNECT_MAX_WAIT_MS, RELAY_PUBLISH_DEADLINE_MS, RELAY_QUERY_DEADLINE_MS, RELAY_QUERY_MAX_WAIT_MS, type RecordPatch, type RelayClient, type RelayClientOptions, type RelayLike, SOLANA_COMPUTE_UNIT_LIMIT, STORE_RELAY_CAP, STORE_WRITE_ATTEMPTS, SUBSCRIBE_RETRY_MAX_MS, SUBSCRIBE_RETRY_MS, SUBSCRIBE_STABLE_MS, type SignedRefusal, type SolanaPayDeps, type SolanaPayRefusal, type SolanaPayResult, type SolanaWallet, type SolanaWatch, type StoreInbox, type StorePins, type StorePinsRecord, type StoreRelaySources, type StoreWrite, TERMINAL_STATES, type TempoPayDeps, type TempoPayRefusal, type TempoPayResult, type TempoWallet, type TempoWatch, type TempoWatchOptions, WRAP_BACKDATE_SECS, type WidgetRefusal, applyStatus, cancelledUnpaid, checkBeforePaying, checkSignedTransaction, clockAgrees, compareOffers, composeOrderPayment, createPool, createRelayClient, deliveryLink, endOrder, endSolanaOrder, endTempoOrder, gone, holdsPayExclusion, isEventShaped, isGenuineEvent, isPageOrigin, isSnapshotStale, isTerminal, judgeAdd, judgeClearMarker, judgeSetMarker, judgeUpdate, judgeUpdateMarker, listenForStatus, loadOffer, loadOfferForAgent, localSolanaWallet, mayStillBePaid, mediumOf, mergePins, newestGenuine, newestStoreInbox, normalizeRelayUrl, nowSecs, onOtherTerms, payWithSolana, payWithTempo, placeOrder, readChainTime, readRelays, readStoreInbox, readTempoChainTime, recordToShow, relayHost, resumeOrder, retryWithSolana, saveTempoHash, sendReceipt, statusFor, storeRelays, storedSolanaRequest, storedTempoRequest, tempoFeeMargin, tempoLateDeadline, uniqueRelays, watchSolanaPayment, watchTempoPayment };