@me.jango/signa 0.3.8 → 0.4.0

package/index.d.ts

@@ -1,5 +1,50 @@
 import { Address, Hex } from 'viem';
 
+/** Why a payment reverted, as a stable code apps and agents branch on. */
+type PayFailureReason = "TERMINAL_UNDER_MIN" | "BUYBACK_SLIPPAGE_EXCEEDED" | "BUYBACK_DERIVED_FLOOR_NOT_MET" | "BUYBACK_SWAP_AMOUNT_TOO_HIGH" | "ROUTER_SLIPPAGE_EXCEEDED" | "ROUTER_NO_ROUTE" | "TOKEN_NOT_ACCEPTED" | "PAYMENTS_PAUSED" | "NO_RULESET" | "ALLOWANCE_TOO_LOW" | "ALLOWANCE_EXPIRED" | "BALANCE_TOO_LOW" | "UNEXPECTED_ETH" | "NFT_SOLD_OUT" | "NFT_UNAVAILABLE" | "NFT_PRICE_ABOVE_PAYMENT" | "NFT_OVERSPENDING";
+/**
+ * The setting a payer can relax so a retry clears the failing check.
+ * `minimum` is the payer's token minimum: the terminal's `minReturnedTokens`
+ * (`TERMINAL_UNDER_MIN`) or the buyback hook's explicit minimum in the pay
+ * metadata (`BUYBACK_SLIPPAGE_EXCEEDED`). `prepareUserPay` floors both by its
+ * `slippageBps`, so the fix is preparing again with the larger tolerance
+ * {@link payRetrySlippageBps} gives; lowering only `minReturnedTokens` leaves
+ * the hook's minimum where it was. Buyback hooks before 1.4 raise the same
+ * error for a floor they derive from their own price oracle, which no
+ * tolerance moves: the fresh preparation's simulation shows that. The
+ * router's conversion minimum is never adjustable: the router can derive it
+ * itself.
+ */
+type PayFailureAdjustable = "minimum";
+/**
+ * A decoded payment revert. `received` and `minimum` are set when the
+ * payment fell short of a minimum, in that check's units (for the router,
+ * the token it converts into), and `adjustable` names the setting a retry
+ * can relax, if any.
+ */
+interface PayFailure$1 {
+    reason: PayFailureReason;
+    /** What the payment would have settled, in the minimum's units. */
+    received?: bigint;
+    /** The minimum it fell short of. */
+    minimum?: bigint;
+    /**
+     * Set with `received`: true when the failing check settled nothing, so a
+     * lower minimum is no fix and `message` does not suggest one. For the
+     * buyback hook that is the part it checked, not always the whole payment.
+     * Absent means unknown, not a fill.
+     */
+    zeroFill?: boolean;
+    /**
+     * Set only with a nonzero `received` below `minimum`: the setting the payer
+     * can relax so a retry clears the failing check. Absent when no setting
+     * the payer controls would help; never relax anything without it.
+     */
+    adjustable?: PayFailureAdjustable;
+    /** One plain sentence to show the payer. */
+    message: string;
+}
+
 /** Browser-safe primitives shared by the existing signed-request client and server. */
 type BotScope = "read" | "plan" | "relay";
 
@@ -129,6 +174,145 @@ declare function buildBotProofTypedData(audience: string, proof: BotProof): {
     };
 };
 
+/** Identifies one immutable effect, including the exact serialized transaction signature. */
+type TransactionApprovalBinding = {
+    accountId: string;
+    principalId: string;
+    planId: string;
+    commitment: Hex;
+    stepIndex: number;
+    transactionHash: Hex;
+};
+type TransactionApprovalClaims = TransactionApprovalBinding & {
+    issuedAt: number;
+    expiresAt: number;
+    nonce: Hex;
+};
+type TransactionApproval = TransactionApprovalClaims & {
+    signature: Hex;
+};
+type SponsorshipApprovalBinding = {
+    accountId: string;
+    principalId: string;
+    sponsorshipId: string;
+    commitment: Hex;
+    submissionHash: Hex;
+};
+type SponsorshipApprovalClaims = SponsorshipApprovalBinding & {
+    issuedAt: number;
+    expiresAt: number;
+    nonce: Hex;
+};
+type SponsorshipApproval = SponsorshipApprovalClaims & {
+    signature: Hex;
+};
+/** Browser-safe owner-wallet signing document; use a fresh cryptographically random nonce. */
+declare function buildTransactionApprovalTypedData(audience: string, input: TransactionApprovalClaims): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        salt: `0x${string}`;
+    };
+    types: {
+        readonly CenterTransactionApproval: readonly [{
+            readonly name: "audience";
+            readonly type: "string";
+        }, {
+            readonly name: "accountId";
+            readonly type: "string";
+        }, {
+            readonly name: "principalId";
+            readonly type: "string";
+        }, {
+            readonly name: "planId";
+            readonly type: "string";
+        }, {
+            readonly name: "commitment";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "stepIndex";
+            readonly type: "uint32";
+        }, {
+            readonly name: "transactionHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "issuedAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "expiresAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "CenterTransactionApproval";
+    message: {
+        audience: string;
+        issuedAt: bigint;
+        expiresAt: bigint;
+        accountId: string;
+        principalId: string;
+        planId: string;
+        commitment: Hex;
+        stepIndex: number;
+        transactionHash: Hex;
+        nonce: Hex;
+    };
+};
+/** Approves publishing exact signed forward requests, independently of direct transaction relay. */
+declare function buildSponsorshipApprovalTypedData(audience: string, input: SponsorshipApprovalClaims): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        salt: `0x${string}`;
+    };
+    types: {
+        readonly CenterSponsorshipApproval: readonly [{
+            readonly name: "audience";
+            readonly type: "string";
+        }, {
+            readonly name: "accountId";
+            readonly type: "string";
+        }, {
+            readonly name: "principalId";
+            readonly type: "string";
+        }, {
+            readonly name: "sponsorshipId";
+            readonly type: "string";
+        }, {
+            readonly name: "commitment";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "submissionHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "issuedAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "expiresAt";
+            readonly type: "uint64";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "CenterSponsorshipApproval";
+    message: {
+        audience: string;
+        issuedAt: bigint;
+        expiresAt: bigint;
+        nonce: `0x${string}`;
+        accountId: string;
+        principalId: string;
+        sponsorshipId: string;
+        commitment: Hex;
+        submissionHash: Hex;
+    };
+};
+
 interface RestBlockEvidence {
     chainId: number;
     blockNumber: string;
@@ -286,145 +470,6 @@ interface UserOperationObservation {
     payFailure?: PayFailure;
 }
 
-/** Identifies one immutable effect, including the exact serialized transaction signature. */
-type TransactionApprovalBinding = {
-    accountId: string;
-    principalId: string;
-    planId: string;
-    commitment: Hex;
-    stepIndex: number;
-    transactionHash: Hex;
-};
-type TransactionApprovalClaims = TransactionApprovalBinding & {
-    issuedAt: number;
-    expiresAt: number;
-    nonce: Hex;
-};
-type TransactionApproval = TransactionApprovalClaims & {
-    signature: Hex;
-};
-type SponsorshipApprovalBinding = {
-    accountId: string;
-    principalId: string;
-    sponsorshipId: string;
-    commitment: Hex;
-    submissionHash: Hex;
-};
-type SponsorshipApprovalClaims = SponsorshipApprovalBinding & {
-    issuedAt: number;
-    expiresAt: number;
-    nonce: Hex;
-};
-type SponsorshipApproval = SponsorshipApprovalClaims & {
-    signature: Hex;
-};
-/** Browser-safe owner-wallet signing document; use a fresh cryptographically random nonce. */
-declare function buildTransactionApprovalTypedData(audience: string, input: TransactionApprovalClaims): {
-    domain: {
-        name: string;
-        version: string;
-        chainId: number;
-        salt: `0x${string}`;
-    };
-    types: {
-        readonly CenterTransactionApproval: readonly [{
-            readonly name: "audience";
-            readonly type: "string";
-        }, {
-            readonly name: "accountId";
-            readonly type: "string";
-        }, {
-            readonly name: "principalId";
-            readonly type: "string";
-        }, {
-            readonly name: "planId";
-            readonly type: "string";
-        }, {
-            readonly name: "commitment";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "stepIndex";
-            readonly type: "uint32";
-        }, {
-            readonly name: "transactionHash";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "issuedAt";
-            readonly type: "uint64";
-        }, {
-            readonly name: "expiresAt";
-            readonly type: "uint64";
-        }, {
-            readonly name: "nonce";
-            readonly type: "bytes32";
-        }];
-    };
-    primaryType: "CenterTransactionApproval";
-    message: {
-        audience: string;
-        issuedAt: bigint;
-        expiresAt: bigint;
-        accountId: string;
-        principalId: string;
-        planId: string;
-        commitment: Hex;
-        stepIndex: number;
-        transactionHash: Hex;
-        nonce: Hex;
-    };
-};
-/** Approves publishing exact signed forward requests, independently of direct transaction relay. */
-declare function buildSponsorshipApprovalTypedData(audience: string, input: SponsorshipApprovalClaims): {
-    domain: {
-        name: string;
-        version: string;
-        chainId: number;
-        salt: `0x${string}`;
-    };
-    types: {
-        readonly CenterSponsorshipApproval: readonly [{
-            readonly name: "audience";
-            readonly type: "string";
-        }, {
-            readonly name: "accountId";
-            readonly type: "string";
-        }, {
-            readonly name: "principalId";
-            readonly type: "string";
-        }, {
-            readonly name: "sponsorshipId";
-            readonly type: "string";
-        }, {
-            readonly name: "commitment";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "submissionHash";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "issuedAt";
-            readonly type: "uint64";
-        }, {
-            readonly name: "expiresAt";
-            readonly type: "uint64";
-        }, {
-            readonly name: "nonce";
-            readonly type: "bytes32";
-        }];
-    };
-    primaryType: "CenterSponsorshipApproval";
-    message: {
-        audience: string;
-        issuedAt: bigint;
-        expiresAt: bigint;
-        nonce: `0x${string}`;
-        accountId: string;
-        principalId: string;
-        sponsorshipId: string;
-        commitment: Hex;
-        submissionHash: Hex;
-    };
-};
-
 interface Safe7579OwnerSigningInput {
     operation: UserOperationV07;
     chainId: number;
@@ -1038,7 +1083,8 @@ interface UserOperationRecord {
     createdAt: number;
     expiresAt: number;
     revision: number;
-    state: 'prepared' | 'submitting' | 'submission_unknown' | UserOperationObservation['state'];
+    /** `retired`: approved, never sent, and refused for good; nothing claims or resends it. */
+    state: 'prepared' | 'submitting' | 'submission_unknown' | 'retired' | UserOperationObservation['state'];
     submission?: {
         key: string;
         commitment: Hex;
@@ -1047,6 +1093,8 @@ interface UserOperationRecord {
         sessionObservationHash?: Hex;
     };
     observation?: UserOperationObservation;
+    /** When the chain settled a retired operation: it never ran and never can, or Signa's own operation took its nonce. */
+    retiredSettledAt?: number;
 }
 
 interface WalletTypedData {
@@ -1165,6 +1213,8 @@ declare class SmartAccountClient {
     }>;
     submitUserOperation(operationId: string, signature: Hex, key?: string): Promise<PreparedUserOperation>;
     /** With `wait`, the answer is held (up to 20 s) until the operation moves past the revision seen. */
+    /** Retires an operation nothing has sent, so it is never claimed or sent again; one already claimed comes back with its submission. */
+    retireUserOperation(operationId: string): Promise<PreparedUserOperation>;
     userOperation(operationId: string, wait?: {
         seconds: number;
         since: number;
@@ -1223,14 +1273,14 @@ type ClientOptions = {
     maxResponseBytes?: number;
     /** Reads a refused request's served payment reason; without it, errors carry none. `CenterClient`
      * and the wallet client use `payFailureOf`; the served pages, which never show one, leave it out. */
-    payFailure?: (served: unknown) => PayFailure | undefined;
+    payFailure?: (served: unknown) => PayFailure$1 | undefined;
 };
 declare class RestClientError extends Error {
     readonly code: string;
     readonly status?: number | undefined;
     /** Why this refused payment attempt would revert, when its calls say. Advisory and for this attempt only; a changed minimum needs a fresh preparation and review. */
-    readonly payFailure?: PayFailure;
-    constructor(code: string, message: string, status?: number | undefined, payFailure?: PayFailure);
+    readonly payFailure?: PayFailure$1;
+    constructor(code: string, message: string, status?: number | undefined, payFailure?: PayFailure$1);
 }
 type PreparedRequest = {
     url: string;
@@ -1454,8 +1504,9 @@ interface CenterWalletPaymentInput {
     operation: PreparedUserOperation;
     expectedPayment: CenterWalletExpectedPayment;
 }
-/** `expired`: published but never included before its signed validity ended; it cannot execute. */
-type CenterWalletPaymentState = 'reviewing' | 'approved' | 'submitting' | 'pending' | 'confirming' | 'paid' | 'reverted' | 'cancelled' | 'unknown' | 'expired';
+/** `expired`: published but never included before its signed validity ended; it cannot execute.
+ * `refused`: Signa refused to send it and retired the approval; Signa never sends it, and a fresh payment takes its nonce. */
+type CenterWalletPaymentState = 'reviewing' | 'approved' | 'submitting' | 'pending' | 'confirming' | 'paid' | 'reverted' | 'cancelled' | 'unknown' | 'expired' | 'refused';
 interface CenterWalletPaymentStatus {
     status: CenterWalletPaymentState;
     accountId: string;
@@ -1469,8 +1520,10 @@ interface CenterWalletPaymentStatus {
     /** An observed outer transaction identifier, never an alias for operationHash. */
     transactionHash?: Hex;
     observation?: UserOperationObservation;
-    /** Why this payment reverted, when its trace says; shown only while it stands reverted. Advisory: a changed minimum needs a fresh preparation and review. */
-    payFailure?: PayFailure;
+    /** Why this payment reverted, when its trace says; shown only while it stands reverted. The SDK's own
+     * `PayFailure` (bigint amounts, with `zeroFill` and `adjustable` for a shortfall); `observation.payFailure`
+     * keeps the served form. Advisory: a changed minimum needs a fresh preparation and review. */
+    payFailure?: PayFailure$1;
 }
 
 interface CenterWalletStorage {
@@ -1532,6 +1585,7 @@ declare function createCenterWalletClient(options: CenterWalletClientOptions): R
         refreshPayment: (options?: {
             waitSeconds?: number;
         }) => Promise<CenterWalletPaymentStatus>;
+        retirePayment: () => Promise<CenterWalletPaymentStatus>;
         pendingPayment: () => CenterWalletPaymentStatus | null;
         clearPayment: () => void;
     }>;
@@ -1550,4 +1604,4 @@ type SponsoredCall = {
 declare function sponsoredCallsCommitment(calls: readonly SponsoredCall[]): Hex;
 
 export { RestClientError, assertReviewedOperation, createCenterWalletClient, ownerOperationSignature, ownerOperationSigning, sponsoredCallsCommitment, userOperationMaximumCost };
-export type { CenterWalletClientOptions, CenterWalletConnection, CenterWalletExpectedPayment, CenterWalletPaymentInput, CenterWalletPaymentState, CenterWalletPaymentStatus, CenterWalletPreparedConnection, CenterWalletStorage, PayFailure, PreparedRequest, PreparedUserOperation, SmartWalletPlan, SponsoredCall };
+export type { CenterWalletClientOptions, CenterWalletConnection, CenterWalletExpectedPayment, CenterWalletPaymentInput, CenterWalletPaymentState, CenterWalletPaymentStatus, CenterWalletPreparedConnection, CenterWalletStorage, PayFailure$1 as PayFailure, PreparedRequest, PreparedUserOperation, SmartWalletPlan, SponsoredCall };

package/index.js

@@ -950,6 +950,10 @@ var SmartAccountClient = class {
     );
   }
   /** With `wait`, the answer is held (up to 20 s) until the operation moves past the revision seen. */
+  /** Retires an operation nothing has sent, so it is never claimed or sent again; one already claimed comes back with its submission. */
+  retireUserOperation(operationId) {
+    return this.post(`/user-operations/${id(operationId)}/retirement`, {});
+  }
   userOperation(operationId, wait) {
     if (wait && (!Number.isInteger(wait.seconds) || wait.seconds < 1 || wait.seconds > 20 || !Number.isInteger(wait.since) || wait.since < 0))
       invalid4("Wait 1\u201320 seconds past a revision already seen.");
@@ -1393,14 +1397,7 @@ function payFailureOf(value) {
   if (Object.keys(rest).length || typeof reason !== "string" || !Object.hasOwn(payFailureReverts, reason) || typeof message2 !== "string" || !amount(received) || !amount(minimum)) return void 0;
   const settled = received === void 0 ? void 0 : BigInt(received);
   const floor = minimum === void 0 ? void 0 : BigInt(minimum);
-  const canonical = sdkPayFailures(reason, settled, floor).some((failure) => failure && failure.reason === reason && failure.message === message2 && failure.received === settled && failure.minimum === floor);
-  if (!canonical) return void 0;
-  return {
-    reason,
-    message: message2,
-    ...received === void 0 ? {} : { received },
-    ...minimum === void 0 ? {} : { minimum }
-  };
+  return sdkPayFailures(reason, settled, floor).find((failure) => failure && failure.reason === reason && failure.message === message2 && failure.received === settled && failure.minimum === floor) ?? void 0;
 }
 
 // src/rest/client/center.ts
@@ -1854,6 +1851,10 @@ function parseBotRegistration(value) {
 // src/rest/client/walletPayments.ts
 import { sha256 as sha2564, stringToHex as stringToHex6 } from "viem";
 
+// src/rest/client/paymentStates.ts
+var settledPaymentStates = ["paid", "reverted", "cancelled", "expired", "refused"];
+var isSettledPayment = (status) => settledPaymentStates.includes(status);
+
 // src/rest/smartAccounts/passkeySignatures.ts
 import {
   concatHex as concatHex5,
@@ -2166,8 +2167,8 @@ var maximumBytes = 1048576;
 var reviewPath = "/api/v1/wallet/payment-reviews";
 var reviewIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 var paymentFields = ["kind", "chainId", "account", "token", "terminal", "projectId", "amount", "beneficiary", "minimumReturnedTokens", "memo", "metadata"];
-var states = ["reviewing", "approved", "submitting", "pending", "confirming", "paid", "reverted", "cancelled", "unknown", "expired"];
-var terminal = (status) => ["paid", "reverted", "cancelled", "expired"].includes(status);
+var states = ["reviewing", "approved", "submitting", "pending", "confirming", "paid", "reverted", "cancelled", "unknown", "expired", "refused"];
+var terminal = isSettledPayment;
 var hex32 = (value) => typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value);
 var uuid2 = (value) => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
 var integer2 = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
@@ -2310,7 +2311,7 @@ function createCenterWalletPaymentClient(options) {
       if (!("ownerProfile" in signing)) mismatch();
       const expectedSigning = { digest: signing.digest, signedData: signing.signedData, validAfter: signing.validAfter, validUntil: signing.validUntil };
       const payment = checkInput(saved, saved.grant, saved.startedAtMs);
-      if (v.version !== "center-wallet-payment-review-v1" || !uuid2(v.id) || saved.review && v.id !== saved.review.id || v.state !== saved.state || v.issuer !== issuer || v.accountId !== saved.grant.accountId || app.origin !== saved.grant.origin || app.callbackUri !== callbackUri || app.grantId !== saved.grant.id || app.grantIncarnation !== saved.grant.incarnation || v.planId !== saved.plan.id || !same3(v.planCommitment, saved.plan.commitment) || v.operationId !== saved.operation.id || !same3(v.operationCommitment, saved.operation.commitment) || !same3(v.operationHash, saved.operation.operationHash) || !equal(v.stepIndexes, saved.operation.stepIndexes) || !equal(normalizeUserOperation(v.operation), normalizeUserOperation(saved.operation.operation)) || v.chainId !== 8453 || !same3(v.entryPoint, saved.operation.entryPoint) || !same3(v.safe7579, signing.typedData.domain.verifyingContract) || !equal(v.signing, expectedSigning) || !equal(comparablePayment(v.payment), comparablePayment(payment)) || !integer2(v.createdAtMs) || v.createdAtMs < saved.startedAtMs - 3e4 || v.createdAtMs > now() + 3e4 || !integer2(v.expiresAtMs) || v.expiresAtMs <= v.createdAtMs || v.expiresAtMs > saved.operation.expiresAt || v.expiresAtMs > saved.grant.expiresAt * 1e3 || v.expiresAtMs > v.createdAtMs + 3e5 || saved.review && (v.createdAtMs !== saved.review.createdAtMs || v.expiresAtMs !== saved.review.expiresAtMs) || !["pending", "approved", "cancelled"].includes(String(v.status)) || !["prepared", "submitting", "submission_unknown", "pending", "unknown", "confirming", "confirmed", "reverted", "expired"].includes(String(v.operationState))) mismatch();
+      if (v.version !== "center-wallet-payment-review-v1" || !uuid2(v.id) || saved.review && v.id !== saved.review.id || v.state !== saved.state || v.issuer !== issuer || v.accountId !== saved.grant.accountId || app.origin !== saved.grant.origin || app.callbackUri !== callbackUri || app.grantId !== saved.grant.id || app.grantIncarnation !== saved.grant.incarnation || v.planId !== saved.plan.id || !same3(v.planCommitment, saved.plan.commitment) || v.operationId !== saved.operation.id || !same3(v.operationCommitment, saved.operation.commitment) || !same3(v.operationHash, saved.operation.operationHash) || !equal(v.stepIndexes, saved.operation.stepIndexes) || !equal(normalizeUserOperation(v.operation), normalizeUserOperation(saved.operation.operation)) || v.chainId !== 8453 || !same3(v.entryPoint, saved.operation.entryPoint) || !same3(v.safe7579, signing.typedData.domain.verifyingContract) || !equal(v.signing, expectedSigning) || !equal(comparablePayment(v.payment), comparablePayment(payment)) || !integer2(v.createdAtMs) || v.createdAtMs < saved.startedAtMs - 3e4 || v.createdAtMs > now() + 3e4 || !integer2(v.expiresAtMs) || v.expiresAtMs <= v.createdAtMs || v.expiresAtMs > saved.operation.expiresAt || v.expiresAtMs > saved.grant.expiresAt * 1e3 || v.expiresAtMs > v.createdAtMs + 3e5 || saved.review && (v.createdAtMs !== saved.review.createdAtMs || v.expiresAtMs !== saved.review.expiresAtMs) || !["pending", "approved", "cancelled"].includes(String(v.status)) || !["prepared", "submitting", "submission_unknown", "pending", "unknown", "confirming", "confirmed", "reverted", "expired", "retired"].includes(String(v.operationState))) mismatch();
       if (v.status === "approved" ? !integer2(v.approvedAtMs) || v.cancelledAtMs !== null : v.approvedAtMs !== null) mismatch();
       if (v.status === "cancelled" ? !integer2(v.cancelledAtMs) : v.cancelledAtMs !== null) mismatch();
       for (const at of [v.approvedAtMs, v.cancelledAtMs])
@@ -2348,10 +2349,11 @@ function createCenterWalletPaymentClient(options) {
     return value;
   }
   function status(value) {
-    const payFailure = value.status === "reverted" && value.observation?.state === "reverted" ? payFailureOf(value.observation.payFailure) : void 0;
+    const served = value.status === "reverted" && value.observation?.state === "reverted" ? value.observation.payFailure : void 0;
+    const payFailure = payFailureOf(served);
     const { payFailure: _served, ...observed } = value.observation ?? {};
-    const observation = value.observation && { ...observed, ...payFailure ? { payFailure } : {} };
-    return snapshot2({
+    const observation = value.observation && { ...observed, ...payFailure ? { payFailure: served } : {} };
+    const copy = snapshot2({
       status: value.status,
       accountId: value.grant.accountId,
       chainId: 8453,
@@ -2364,9 +2366,9 @@ function createCenterWalletPaymentClient(options) {
       ...observation ? {
         observation,
         ...hex32(observation.transactionHash) ? { transactionHash: observation.transactionHash } : {}
-      } : {},
-      ...payFailure ? { payFailure } : {}
+      } : {}
     });
+    return payFailure ? { ...copy, payFailure } : copy;
   }
   function receiveView(input, saved, appView) {
     const reviewed = checkView(input, saved.value, appView);
@@ -2456,6 +2458,7 @@ function createCenterWalletPaymentClient(options) {
       if (operation.state === "confirmed" && observation?.state === "confirmed" && canonical && receipt?.status === "success" && observation.semantic?.status === "verified") result = "paid";
       if (operation.state === "reverted" && observation?.state === "reverted" && canonical && (receipt?.status === "reverted" || observation.semantic?.status === "failed")) result = "reverted";
       if (operation.state === "expired" && observation?.state === "expired" && observation.transactionHash === void 0 && !receipt) result = "expired";
+      if (operation.state === "retired" && !operation.submission && !observation) result = "refused";
       return save({ ...saved.value, status: result, ...observation ? { observation } : {} }, saved.encoded);
     } catch (error) {
       if (error instanceof RestClientError && ["WALLET_PAYMENT_STORAGE_UNAVAILABLE", "WALLET_PAYMENT_CHANGED"].includes(error.code)) throw error;
@@ -2474,10 +2477,19 @@ function createCenterWalletPaymentClient(options) {
       const result = await client.smartAccounts().submitUserOperation(saved.value.operation.id, saved.value.approval.signature, saved.value.submissionKey);
       return status(receiveOperation(result, saved).value);
     } catch (error) {
-      save({ ...saved.value, status: "unknown" }, saved.encoded);
+      saved = save({ ...saved.value, status: "unknown" }, saved.encoded);
+      if (error instanceof RestClientError && error.status !== void 0 && error.status >= 400) await retire(saved).catch(() => void 0);
       throw error;
     }
   }
+  function retire(saved) {
+    return live(saved.value).client.smartAccounts().retireUserOperation(saved.value.operation.id).then((result) => receiveOperation(result, saved));
+  }
+  async function retirePayment() {
+    const saved = pending();
+    if (!saved.value.approval || terminal(saved.value.status)) fail3("WALLET_PAYMENT_NOT_APPROVED", "Only an approved payment that has not settled can be retired.");
+    return status((await retire(saved)).value);
+  }
   const revisions = /* @__PURE__ */ new Map();
   async function refreshPayment(options2 = {}) {
     if (options2.waitSeconds !== void 0 && (!Number.isInteger(options2.waitSeconds) || options2.waitSeconds < 1 || options2.waitSeconds > 20))
@@ -2496,7 +2508,7 @@ function createCenterWalletPaymentClient(options) {
           client.smartAccounts().userOperation(saved.value.operation.id)
         ]);
         const reviewed = receiveView(value2, saved, true);
-        if (!snapshot2(operation).submission) return status(reviewed.value);
+        if (!snapshot2(operation).submission && operation.state !== "retired") return status(reviewed.value);
         return status(receiveOperation(operation, save({ ...reviewed.value, submissionStarted: true, status: "submitting" }, reviewed.encoded)).value);
       }
       const value = await client.request({ requestTarget: reviewPath + "/" + saved.value.review.id });
@@ -2528,8 +2540,9 @@ function createCenterWalletPaymentClient(options) {
     try {
       const history = existing === null ? [] : JSON.parse(existing);
       if (!Array.isArray(history)) throw new Error();
+      const { payFailure: _decoded, ...archived } = status(saved.value);
       const receipt = {
-        ...status(saved.value),
+        ...archived,
         ...!settled ? { status: "unknown", archiveReason: unsignedWindowElapsed ? "no-local-submission-recorded" : "grant-expired" } : {},
         issuer,
         audience,
@@ -2559,7 +2572,7 @@ function createCenterWalletPaymentClient(options) {
       fail3("WALLET_PAYMENT_STORAGE_UNAVAILABLE", "The original payment must be archived before clearing this tab\u2019s pending record.");
     }
   }
-  return Object.freeze({ preparePayment, reviewUrl, completePayment, submitPayment, refreshPayment, pendingPayment, clearPayment });
+  return Object.freeze({ preparePayment, reviewUrl, completePayment, submitPayment, refreshPayment, retirePayment, pendingPayment, clearPayment });
 }
 
 // src/rest/wallet/grantLifetime.ts

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@me.jango/signa",
-  "version": "0.3.8",
-  "description": "Connect a Juicebox Center account to your app and review passkey payments",
+  "version": "0.4.0",
+  "description": "Sign in to an app with a Signa passkey account or an external wallet, and review passkey payments",
   "repository": { "type": "git", "url": "https://github.com/mejango/signa.git", "directory": "wallet-client" },
   "type": "module",
   "sideEffects": false,
   "main": "./index.js",
   "types": "./index.d.ts",
-  "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },
-  "files": ["index.js", "index.d.ts", "README.md"],
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./index.js" },
+    "./core": { "types": "./core/index.d.ts", "import": "./core/index.js" },
+    "./wagmi": { "types": "./wagmi/index.d.ts", "import": "./wagmi/index.js" },
+    "./react": { "types": "./react/index.d.ts", "import": "./react/index.js" }
+  },
+  "files": ["index.js", "index.d.ts", "core/", "wagmi/", "react/", "README.md"],
   "publishConfig": { "access": "public" },
   "engines": { "node": ">=22" },
-  "dependencies": { "viem": "^2.37.5" }
+  "dependencies": { "viem": "^2.37.5" },
+  "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "wagmi": "^2.10.2 || ^3.0.0" },
+  "peerDependenciesMeta": { "react": { "optional": true }, "wagmi": { "optional": true } }
 }

package/react/index.d.ts

@@ -0,0 +1,34 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ConnectController, ConnectOption } from '../core/index.js';
+
+type JBConnectModalProps = {
+    open: boolean;
+    controller: ConnectController;
+    /** Called for Escape, the backdrop and the cancel button, after the controller is cancelled. */
+    onClose(): void;
+    /** Which option is the passkey account; it renders as the primary button. */
+    passkeyId?: string;
+    /** The primary button's text. Defaults to the platform's prompt: Touch ID, Face ID, Windows Hello, or a passkey. */
+    passkeyLabel?: string;
+    title?: ReactNode;
+    /** Renders a pairing URI (a QR code, a deep link) once an option publishes one. */
+    renderHandoff?(uri: string, option: ConnectOption): ReactNode;
+    /** A mark for an option without an icon. Defaults to the option's initial. */
+    renderIcon?(option: ConnectOption): ReactNode;
+    /** Extra footer actions, laid out on the cancel button's baseline. */
+    footer?: ReactNode;
+    /** App content shown under the wallet tiles while idle, such as mobile wallet links. */
+    children?: ReactNode;
+    className?: string;
+};
+declare function JBConnectModal(props: JBConnectModalProps): react.JSX.Element;
+
+/** Themed through custom properties so a Tailwind app and a plain-CSS app both look native. */
+declare const connectModalCss = "\n.jb-connect{--jb-connect-bg:#fff;--jb-connect-fg:#1a1a1a;--jb-connect-muted:#6b6b6b;--jb-connect-line:#dcdcdc;--jb-connect-accent:#1a1a1a;--jb-connect-accent-fg:#fff;--jb-connect-radius:16px;--jb-connect-tile:44px;--jb-connect-font:inherit;--jb-connect-pad:32px;--jb-connect-backdrop:rgba(0,0,0,.45);--jb-connect-width:440px;\n  box-sizing:border-box;width:min(var(--jb-connect-width),calc(100vw - 24px));max-height:calc(100dvh - 32px);padding:var(--jb-connect-pad);margin:auto;border:1px solid var(--jb-connect-line);border-radius:var(--jb-connect-radius);background:var(--jb-connect-bg);color:var(--jb-connect-fg);font:16px/1.4 var(--jb-connect-font);overscroll-behavior:contain}\n.jb-connect::backdrop{background:var(--jb-connect-backdrop)}\n.jb-connect *{box-sizing:border-box}\n.jb-connect h2{margin:0 0 20px;font-size:28px;font-weight:600;line-height:1.1}\n.jb-connect button{font:inherit;color:inherit;cursor:pointer}\n.jb-connect button:disabled{cursor:default;opacity:.55}\n.jb-connect .jb-connect-primary{display:block;width:100%;min-height:50px;padding:14px 20px;border:0;border-radius:calc(var(--jb-connect-radius) / 2);background:var(--jb-connect-accent);color:var(--jb-connect-accent-fg);font-weight:600}\n.jb-connect .jb-connect-powered{margin:8px 0 0;font-size:13px;color:var(--jb-connect-muted);text-align:center}\n.jb-connect .jb-connect-frame{display:block;width:calc(100% + 2 * var(--jb-connect-pad));height:14rem;margin:0 calc(-1 * var(--jb-connect-pad));border:1px solid var(--jb-connect-line);border-width:1px 0;background:var(--jb-connect-bg);transition:height .2s ease}\n@media (prefers-reduced-motion:reduce){.jb-connect .jb-connect-frame{transition:none}}\n.jb-connect .jb-connect-divider{margin:24px 0 10px;font-size:13px;color:var(--jb-connect-muted)}\n.jb-connect .jb-connect-tiles{display:flex;gap:10px;min-height:var(--jb-connect-tile);padding:4px;margin:-4px;overflow-x:auto}\n.jb-connect .jb-connect-tile{display:grid;place-items:center;flex:0 0 var(--jb-connect-tile);width:var(--jb-connect-tile);height:var(--jb-connect-tile);padding:8px;border:1px solid var(--jb-connect-line);border-radius:9px;background:var(--jb-connect-bg)}\n.jb-connect .jb-connect-tile img,.jb-connect .jb-connect-tile svg{width:22px;height:22px;object-fit:contain}\n.jb-connect .jb-connect-tile span{font-size:12px;font-weight:600;line-height:1}\n.jb-connect .jb-connect-status,.jb-connect .jb-connect-error{margin:16px 0 0;font-size:13px}\n.jb-connect .jb-connect-status{color:var(--jb-connect-muted)}\n.jb-connect .jb-connect-error{padding:12px 15px;border-left:3px solid #c8755e;background:#fae9e4;color:#873b2e;overflow-wrap:anywhere}\n.jb-connect .jb-connect-handoff{margin-top:16px}\n.jb-connect .jb-connect-footer{display:flex;align-items:baseline;justify-content:flex-end;gap:16px;margin-top:20px}\n.jb-connect .jb-connect-text{min-height:auto;padding:4px 0;margin:-4px 0;border:0;background:none;font-size:14px;text-decoration:underline;text-underline-offset:3px}\n@media (max-width:540px){.jb-connect{--jb-connect-pad:20px;padding:24px var(--jb-connect-pad)}.jb-connect h2{font-size:24px}}\n";
+
+/** Names the prompt the person is about to see; "passkey" is the fallback when the platform is unknown. */
+declare function passkeyLabel(userAgent: string): string;
+
+export { JBConnectModal, connectModalCss, passkeyLabel };
+export type { JBConnectModalProps };