@ldgr/client 0.5.0 → 0.6.0

package/README.md

@@ -67,9 +67,10 @@ Settlement failures return `status: "failed"`; they do not have a transaction
 hash or fee because the ledger rejected them before appending a transaction.
 Transport and unexpected response errors still throw.
 
-## Silent payments
+## Confidential payments
 
-`silentPayments.send()` accepts a reusable LDGR payment code and a
+The product term is **confidential payments**. The compatibility-stable
+`silentPayments.send()` API accepts a reusable LDGR payment code and a
 `LocalLdgrWallet`. It signs and publishes the wallet's immutable sender-DH
 public key, fetches the asset nonce, derives a fresh one-time destination, and
 submits an ordinary transfer. A `NONCE_MISMATCH` causes one fresh derivation;
@@ -112,8 +113,9 @@ ledger-sequence `nextAfter` checkpoint, and `moreAvailable`. Matching requires
 the receiver scan secret and belongs in wallet code such as
 `@ldgr/wallet-core`, never on a server that does not own the recovery key. This
 LDGR-specific construction is not BIP-352-compatible and remains experimental.
-Wallet discovery is available on both ledgers, while reusable-code display,
-first-party sending, and private-output spending remain gated pending testnet-first
+Wallet discovery is available on both ledgers. The extension and Web Wallet
+display reusable codes; the Web Wallet also sends to them. Spending or
+consolidating confidential-payment outputs remains gated pending testnet-first
 operational testing and external cryptographic review.
 
 ```ts
@@ -139,6 +141,59 @@ transaction hash as the idempotency key. AMM quotes are estimates: pass an
 explicit minimum output in the signed swap payload and re-quote immediately
 before signing.
 
+## Widget and Checkout merchant verification
+
+Available in `@ldgr/client` **0.6.0**. These methods work on servers without
+DOM globals or wallet keys. Configure the client's network from your saved
+order and pass only the widget's identifiers as the submitted proof:
+
+```ts
+import { createLdgrClient } from "@ldgr/client";
+
+const order = await orders.load(orderId); // Your persisted server order.
+const client = createLdgrClient({ network: order.network });
+const payment = await client.payments.verifyPayment({
+  transactionHash: submitted.transactionHash,
+  checkoutSessionId: submitted.checkoutSessionId, // Optional for wallet payments.
+}, {
+  to: order.recipient,
+  asset: order.assetCode,
+  amount: order.grossAmount, // Exact decimal string, including Checkout's fee.
+  reference: order.publicReference,
+});
+
+if (payment.status === "confirmed") {
+  // In one database transaction: check order expiry, claim a unique
+  // (network, transactionHash), bind it to this order, and fulfil once.
+  await orders.fulfilOnce(order.id, order.network, payment.transactionHash);
+}
+```
+
+`verifyPayment` explicitly dispatches to Checkout when `checkoutSessionId` is
+provided; otherwise it requires a plain transfer. It never infers Checkout
+from arbitrary batch metadata or falls back after a session mismatch. Expected
+`to`, `asset`, gross decimal `amount`, and `reference` must come from your server,
+not from the browser. Amount comparisons use exact strings, never floating point.
+
+For a known Checkout session, use `payments.verifyCheckout(sessionId, {
+to, asset, amount, reference, transactionHash? })`. It checks the authoritative
+session ID, ledger, recipient, asset, gross amount, reference, paid state, and
+optional submitted hash. A confirmed result includes `sessionId`,
+`transactionHash`, `from`, `to`, `asset`, gross `amount`, `merchantAmount`, and
+`checkoutFee`. With the default fee, a gross `1` USDL receipt reports merchant
+`0.995` USDL and Checkout fee `0.005` USDL. Do not compare the net receipt with
+the gross order amount.
+
+Non-confirmed Checkout results are `pending`, `expired`, `not_found`, or
+`mismatch`. An expired funding instruction does not invalidate a paid receipt.
+Network/server errors and invalid arguments throw; callers must not fulfil on
+an error. `verifyTransfer` remains a strict plain-transfer verifier. It also
+checks that the response hash matches the requested hash.
+
+The SDK reads receipts; your service owns authentication, order persistence,
+order expiry rules, and atomic duplicate-payment protection. Browser SDK
+`getPaymentStatus` / `getCheckoutStatus` results are UX hints only.
+
 ## LDGR402 merchant verification
 
 For a persisted LDGR402 requirement and the browser's

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type LdgrTransferResult, type SendTransferInput } from "./transfer";
 import { type Ldgr402Requirement } from "@ldgr/protocol";
-import { type LdgrAccountTransactionPage, type LdgrClientOptions, type LdgrAsset, type Ldgr402Verification, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission, type SilentPaymentSendInput, type SilentPaymentScanPage, type WalletPublicKeyRecord, type WalletPublicKeyRegistration } from "./types";
+import { type LdgrAccountTransactionPage, type LdgrClientOptions, type LdgrAsset, type Ldgr402Verification, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type CheckoutPaymentExpectation, type CheckoutPaymentVerification, type MerchantPaymentExpectation, type MerchantPaymentVerification, type PaymentSubmission, type SignedSubmission, type SilentPaymentSendInput, type SilentPaymentScanPage, type WalletPublicKeyRecord, type WalletPublicKeyRegistration } from "./types";
 export declare function createLdgrClient(options: LdgrClientOptions): {
     ledger: {
         get: () => Promise<{
@@ -75,6 +75,8 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
     };
     payments: {
         verifyTransfer: (transactionHash: string, expected: PaymentExpectation) => Promise<PaymentVerification>;
+        verifyCheckout: (sessionId: string, expected: CheckoutPaymentExpectation) => Promise<CheckoutPaymentVerification>;
+        verifyPayment: (submission: PaymentSubmission, expected: MerchantPaymentExpectation) => Promise<MerchantPaymentVerification>;
         verifyLdgr402: (proofHeader: string, requirementInput: Ldgr402Requirement, options?: {
             readonly nowMs?: number;
         }) => Promise<Ldgr402Verification>;
@@ -93,7 +95,7 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
 };
 export { LdgrClientError, SilentPaymentSubmissionUnknownError } from "./types";
 export { decodeMerchantLdgr402Payment, parseMerchantLdgr402Requirement } from "./ldgr402";
-export type { LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission, SilentPaymentScanPage, SilentPaymentScanRecord, SilentPaymentSendInput, WalletPublicKeyRecord, WalletPublicKeyRegistration } from "./types";
+export type { CheckoutPaymentExpectation, CheckoutPaymentVerification, MerchantPaymentExpectation, MerchantPaymentVerification, PaymentSubmission, LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission, SilentPaymentScanPage, SilentPaymentScanRecord, SilentPaymentSendInput, WalletPublicKeyRecord, WalletPublicKeyRegistration } from "./types";
 export { createWebCryptoSigner, deriveLocalSilentPaymentIdentity, generateLocalWallet, loadLocalWallet } from "./signer";
 export type { LdgrSigner, LocalLdgrWallet, LocalSilentPaymentIdentity } from "./signer";
 export { buildTransferSubmission } from "./transfer";

package/dist/index.js

@@ -225,7 +225,7 @@ function decodeMerchantLdgr402Payment(headerValue) {
 // src/index.ts
 function normalizedHash(transactionHash) {
   const hash = transactionHash.toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(hash))
+  if (hash.length !== 64 || !/^[0-9a-f]{64}$/.test(hash))
     throw new TypeError("transactionHash must be a 64-character hexadecimal hash");
   return hash;
 }
@@ -247,6 +247,18 @@ function paymentReference(metadata) {
 function transactionFields(transaction) {
   return typeof transaction.from === "string" && typeof transaction.to === "string" && typeof transaction.asset === "string" && typeof transaction.amount === "string" ? { from: transaction.from, to: transaction.to, asset: transaction.asset, amount: transaction.amount } : null;
 }
+function assertMerchantTerms(expected) {
+  if (typeof expected.to !== "string" || !expected.to)
+    throw new TypeError("to is required");
+  if (typeof expected.asset !== "string" || !expected.asset.trim())
+    throw new TypeError("asset is required");
+  if (typeof expected.reference !== "string" || !expected.reference || new TextEncoder().encode(expected.reference).byteLength > 128) {
+    throw new TypeError("reference must be 1 to 128 UTF-8 bytes");
+  }
+  if (typeof expected.amount !== "string" || !sameDecimalAmount(expected.amount, expected.amount) || !/[1-9]/.test(expected.amount)) {
+    throw new TypeError("amount must be a positive exact decimal string");
+  }
+}
 function isNonceMismatch(error) {
   return error instanceof LdgrClientError && error.code === "NONCE_MISMATCH";
 }
@@ -282,18 +294,65 @@ function createLdgrClient(options) {
       throw error;
     }
     const fields = transactionFields(transaction);
-    if (transaction.action !== "transfer" || fields === null || fields.to !== expected.to || fields.asset !== expectedAsset || !sameDecimalAmount(fields.amount, expected.amount) || expected.reference !== undefined && paymentReference(transaction.metadata) !== expected.reference) {
+    if (transaction.transactionHash !== hash || transaction.action !== "transfer" || fields === null || fields.to !== expected.to || fields.asset !== expectedAsset || !sameDecimalAmount(fields.amount, expected.amount) || expected.reference !== undefined && paymentReference(transaction.metadata) !== expected.reference) {
       return { status: "mismatch", transactionHash: hash };
     }
     return { status: "confirmed", transactionHash: hash, ...fields };
   };
-  const verifyLdgr402 = async (proofHeader, requirementInput, options2 = {}) => {
+  const verifyCheckout = async (sessionId, expected) => {
+    if (ledgerId === undefined)
+      throw new TypeError("network is required for Checkout verification");
+    if (sessionId.length !== 36 || !/^chk_[0-9a-f]{32}$/.test(sessionId))
+      throw new TypeError("Invalid Checkout session ID");
+    assertMerchantTerms(expected);
+    const asset = resolveAsset(expected.asset.trim());
+    const expectedHash = expected.transactionHash === undefined ? undefined : normalizedHash(expected.transactionHash);
+    let body;
+    try {
+      body = await transport.get(`/api/v1/checkout/sessions/${sessionId}`);
+    } catch (error) {
+      if (error instanceof LdgrClientError && error.status === 404)
+        return { status: "not_found", sessionId };
+      throw error;
+    }
+    const mismatch = { status: "mismatch", sessionId };
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+      return mismatch;
+    const session = body;
+    if (session.id !== sessionId || session.ledgerId !== ledgerId || session.recipient !== expected.to || session.asset !== asset || typeof session.amount !== "string" || !sameDecimalAmount(session.amount, expected.amount) || session.paymentReference !== expected.reference)
+      return mismatch;
+    if (session.status === "open")
+      return { status: "pending", sessionId };
+    if (session.status === "expired")
+      return { status: "expired", sessionId };
+    if (session.status !== "paid" || typeof session.transactionHash !== "string" || session.transactionHash.length !== 64 || !/^[0-9a-f]{64}$/.test(session.transactionHash) || expectedHash !== undefined && session.transactionHash !== expectedHash || typeof session.guestAddress !== "string" || !session.guestAddress || typeof session.merchantAmount !== "string" || !sameDecimalAmount(session.merchantAmount, session.merchantAmount) || typeof session.checkoutFee !== "string" || !sameDecimalAmount(session.checkoutFee, session.checkoutFee))
+      return mismatch;
+    return {
+      status: "confirmed",
+      sessionId,
+      transactionHash: session.transactionHash,
+      from: session.guestAddress,
+      to: expected.to,
+      asset,
+      amount: session.amount,
+      merchantAmount: session.merchantAmount,
+      checkoutFee: session.checkoutFee
+    };
+  };
+  const verifyPayment = async (submission, expected) => {
+    if (ledgerId === undefined)
+      throw new TypeError("network is required for merchant payment verification");
+    assertMerchantTerms(expected);
+    const hash = normalizedHash(submission.transactionHash);
+    return submission.checkoutSessionId === undefined ? verifyTransfer(hash, expected) : verifyCheckout(submission.checkoutSessionId, { ...expected, transactionHash: hash });
+  };
+  const verifyLdgr402 = async (proofHeader, requirementInput, options = {}) => {
     const proof = decodeLdgr402Payment3(proofHeader);
     const requirement = parseLdgr402Requirement3(requirementInput, {
-      nowMs: options2.nowMs,
+      nowMs: options.nowMs,
       allowExpired: true
     });
-    const nowMs = options2.nowMs ?? Date.now();
+    const nowMs = options.nowMs ?? Date.now();
     if (ledgerId === undefined)
       throw new TypeError("network is required for LDGR402 verification");
     if (proof.ledgerId !== requirement.ledgerId || ledgerId !== requirement.ledgerId || proof.challenge !== requirement.challenge) {
@@ -348,9 +407,9 @@ function createLdgrClient(options) {
         try {
           return await submit();
         } catch (retryError) {
-          const failure2 = transferFailure(retryError);
-          if (failure2 !== undefined)
-            return failure2;
+          const failure = transferFailure(retryError);
+          if (failure !== undefined)
+            return failure;
           throw retryError;
         }
       }
@@ -440,9 +499,9 @@ function createLdgrClient(options) {
         try {
           return await submit();
         } catch (retryError) {
-          const failure2 = transferFailure(retryError);
-          if (failure2 !== undefined)
-            return failure2;
+          const failure = transferFailure(retryError);
+          if (failure !== undefined)
+            return failure;
           throw retryError;
         }
       }
@@ -463,10 +522,10 @@ function createLdgrClient(options) {
       getNextNonce: (address, asset) => transport.get(`/api/v1/nonces/${encodePathSegment(address)}/${encodePathSegment(resolveAsset(asset))}`),
       getWalletPublicKey: (address) => transport.get(`/api/v1/wallets/${encodePathSegment(address)}/public-key`),
       registerWalletPublicKey: (address, registration) => transport.post(`/api/v1/wallets/${encodePathSegment(address)}/public-key`, registration),
-      async listTransactions(address, options2 = {}) {
+      async listTransactions(address, options = {}) {
         const path = queryPath(`/api/v1/explorer/addresses/${encodePathSegment(address)}/transactions`, {
-          before: options2.before,
-          asset: options2.asset === undefined ? undefined : resolveAsset(options2.asset)
+          before: options.before,
+          asset: options.asset === undefined ? undefined : resolveAsset(options.asset)
         });
         try {
           return await transport.get(path);
@@ -518,9 +577,9 @@ function createLdgrClient(options) {
     usernames: {
       get: (name) => transport.get(`/api/v1/usernames/${encodePathSegment(name)}`),
       getPrimary: (address) => transport.get(`/api/v1/usernames/by-address/${encodePathSegment(address)}`),
-      listOwned: (address, options2) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options2 ?? {}))
+      listOwned: (address, options) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options ?? {}))
     },
-    payments: { verifyTransfer, verifyLdgr402 },
+    payments: { verifyTransfer, verifyCheckout, verifyPayment, verifyLdgr402 },
     silentPayments: {
       scan: (after = "0", limit) => transport.get(queryPath("/api/v1/silent-payments/scan", { after, limit })),
       send: sendSilentPayment,

package/dist/types.d.ts

@@ -64,6 +64,34 @@ export type PaymentVerification = {
     readonly status: "not_found" | "mismatch";
     readonly transactionHash: string;
 };
+/** Immutable merchant order terms; amount is the gross exact decimal amount. */
+export type MerchantPaymentExpectation = PaymentExpectation & {
+    readonly asset: string;
+    readonly reference: string;
+};
+export type CheckoutPaymentExpectation = MerchantPaymentExpectation & {
+    readonly transactionHash?: string;
+};
+/** Identifiers forwarded from a widget event, never trusted order terms. */
+export type PaymentSubmission = {
+    readonly transactionHash: string;
+    readonly checkoutSessionId?: string;
+};
+export type CheckoutPaymentVerification = {
+    readonly status: "confirmed";
+    readonly sessionId: string;
+    readonly transactionHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly merchantAmount: string;
+    readonly checkoutFee: string;
+} | {
+    readonly status: "pending" | "expired" | "not_found" | "mismatch";
+    readonly sessionId: string;
+};
+export type MerchantPaymentVerification = PaymentVerification | CheckoutPaymentVerification;
 export type Ldgr402Verification = PaymentVerification | {
     readonly status: "expired";
     readonly transactionHash: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {