@bitpal/checkout 0.8.0 → 0.10.0

package/README.md

@@ -180,6 +180,7 @@ app.post(
 | `checkout.session.expired` | Session expired unpaid |
 | `checkout.session.unresolved` | Underpaid / overpaid / wrong token — needs review |
 | `checkout.refund.recorded` | An on-chain auto-refund (over / under / late payment) was recorded |
+| `x402.payment.resolved` | An x402 payment that `/settle` left unresolved was later settled on-chain (see below) |
 
 ### ⚠️ Replay defense + at-least-once delivery
 
@@ -208,7 +209,7 @@ app.get('/report', x402({
   apiKey: process.env.BITPAL_API_KEY,   // bp_test_… or bp_live_…
   payTo: '0xYourPayoutWallet',
   network: 'base',                      // test key → 'base-sepolia'
-  amount: '1000000',                    // atomic (USDC, 6dp) — your gross; the fee comes out of it
+  amount: '1.00',                       // human-readable — no decimals math
 }), (req, res) => {
   res.json({ report: '…' });            // req.x402Payment has the txHash
 });
@@ -227,6 +228,12 @@ handler with `X-PAYMENT-RESPONSE` set. The middleware also does what the API can
   timeout — answers `503` and asks for a retry with the *same* header. Handing back a `402` there
   would make the caller re-sign and pay twice.
 
+When `/settle` answers `503`, nobody knows yet whether the money moved — so BitPal watches the chain
+and tells you how it ended with a **`x402.payment.resolved`** webhook (`status`: `confirmed` |
+`reverted` | `expired`, plus `payment_id` and `tx_hash`). It fires only on that path: the normal case
+already returned the result to you, and you should not have to handle the same outcome twice. Verify
+it exactly like a checkout webhook.
+
 Not on Express? `X402Gate` is the framework-neutral core — give it the header and the resource URL,
 it tells you whether to bill or serve. On a `settled` result, call `commit()` once you have delivered
 the response, or `release()` if you could not.
@@ -267,6 +274,9 @@ if (res.status === 402) {
 | Base | USDC | `base` |
 | Base Sepolia | USDC | `base-sepolia` |
 
+Amounts are human-readable (`'1.00'`), the same model as `line_items[].amount` — the server converts.
+Pass `amountAtomic` instead if you already have raw units.
+
 EOA signers only — smart-contract wallets cannot sign EIP-3009 authorizations. Amounts are exact:
 over- and underpayment are both rejected, and this lane has no refund path. Authorizations are valid
 for 90–3600 seconds (the server's floor is 60s; the extra 30s absorbs clock skew and round trips).

package/dist/index.cjs

@@ -315,12 +315,23 @@ var BitPalCheckoutClient = class {
     );
   }
   /* ─── Fees ─── */
-  /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+  /**
+   * 수수료 미리보기 — `/v1/checkout/fee-preview`.
+   *
+   * `amount` 는 **사람 표기**다("100", "0.5") — line item / Price / x402 와 같은 모델이라
+   * decimals 를 계산할 필요가 없다. raw μUSD 를 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+   * 응답은 계속 atomic 이다(계산 결과라 정밀도가 곧 계약이다).
+   *
+   * @example
+   * const { data } = await bp.checkout.previewFee('100');       // $100
+   * const { data } = await bp.checkout.previewFee({ amountAtomic: '100000000' });
+   */
   async previewFee(amount) {
-    return this.request(
-      "GET",
-      `/v1/checkout/fee-preview?amount=${encodeURIComponent(amount)}`
-    );
+    const qs = typeof amount === "string" ? `amount=${encodeURIComponent(amount)}` : `amount_atomic=${encodeURIComponent(amount.amountAtomic)}`;
+    if (typeof amount === "string" && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(amount)) {
+      throw new Error('[BitPal] previewFee: amount must be a decimal string like "100" or "0.5" (max 6 decimals). For raw \u03BCUSD use { amountAtomic }.');
+    }
+    return this.request("GET", `/v1/checkout/fee-preview?${qs}`);
   }
 };
 var BitPalError = class extends Error {
@@ -340,7 +351,12 @@ var CHECKOUT_WEBHOOK_EVENTS = [
   "checkout.session.settled",
   "checkout.session.expired",
   "checkout.session.unresolved",
-  "checkout.refund.recorded"
+  "checkout.refund.recorded",
+  // x402 결제의 **사후** 확정. 정상 경로(/settle 이 그 자리에서 결과를 반환)는 발행되지 않는다 —
+  //   이미 아는 결과를 중복으로 받지 않게 하기 위함이다. /settle 이 503 을 반환해 결과를 모른 채
+  //   남았을 때, reconciler 가 체인을 보고 종결시키면 이 이벤트가 온다.
+  //   payload: { payment_id, status: 'confirmed'|'reverted'|'expired', tx_hash, resource, amount, … }
+  "x402.payment.resolved"
 ];
 var WEBHOOK_HEADERS = {
   signature: "X-Webhook-Signature-256",
@@ -476,8 +492,16 @@ var X402Gate = class {
     if (!/^0x[a-fA-F0-9]{40}$/.test(opts.payTo)) {
       throw new Error("[BitPal] x402: payTo must be a 0x EVM address (your registered payout wallet).");
     }
-    if (!/^\d+$/.test(opts.amount)) {
-      throw new Error('[BitPal] x402: amount must be an atomic integer string (USDC 6dp, $1 = "1000000").');
+    const hasHuman = opts.amount != null;
+    const hasAtomic = opts.amountAtomic != null;
+    if (hasHuman === hasAtomic) {
+      throw new Error('[BitPal] x402: provide exactly one of `amount` ("0.1") or `amountAtomic` ("100000").');
+    }
+    if (hasHuman && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(opts.amount)) {
+      throw new Error('[BitPal] x402: amount must be a decimal string like "0.1" or "29" (max 6 decimals).');
+    }
+    if (hasAtomic && !/^\d+$/.test(opts.amountAtomic)) {
+      throw new Error('[BitPal] x402: amountAtomic must be an integer string (USDC 6dp, $1 = "1000000").');
     }
     const timeoutSeconds = opts.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
     if (timeoutSeconds < MIN_VALIDITY_SECONDS || timeoutSeconds > MAX_VALIDITY_SECONDS) {
@@ -495,7 +519,8 @@ var X402Gate = class {
   async requirements(resource) {
     return this.request("POST", "/v1/x402/requirements", {
       payTo: this.opts.payTo,
-      amount: this.opts.amount,
+      // 사람 표기 → atomic 변환은 **서버가** 한다. SDK 가 decimals 를 알 필요가 없다.
+      ...this.opts.amount != null ? { amount: this.opts.amount } : { amountAtomic: this.opts.amountAtomic },
       resource,
       ...this.opts.network ? { network: this.opts.network } : {},
       ...this.opts.asset ? { asset: this.opts.asset } : {},

package/dist/index.d.cts

@@ -556,8 +556,20 @@ declare class BitPalCheckoutClient {
      * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
      */
     getStatus(sessionId: string): Promise<ApiResponse<SessionStatus>>;
-    /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
-    previewFee(amount: string): Promise<ApiResponse<FeePreview>>;
+    /**
+     * 수수료 미리보기 — `/v1/checkout/fee-preview`.
+     *
+     * `amount` 는 **사람 표기**다("100", "0.5") — line item / Price / x402 와 같은 모델이라
+     * decimals 를 계산할 필요가 없다. raw μUSD 를 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+     * 응답은 계속 atomic 이다(계산 결과라 정밀도가 곧 계약이다).
+     *
+     * @example
+     * const { data } = await bp.checkout.previewFee('100');       // $100
+     * const { data } = await bp.checkout.previewFee({ amountAtomic: '100000000' });
+     */
+    previewFee(amount: string | {
+        amountAtomic: string;
+    }): Promise<ApiResponse<FeePreview>>;
 }
 declare class BitPalError extends Error {
     readonly statusCode: number;
@@ -572,7 +584,7 @@ declare class BitPalError extends Error {
 /**
  * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
  */
-declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved"];
 type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
 /**
  * Canonical envelope (HTTP body).
@@ -785,8 +797,14 @@ interface X402GateOptions {
     apiKey: string;
     /** 정산 지갑. 콘솔에 등록한 payout 주소와 같은 값이어야 한다. */
     payTo: string;
-    /** 호출 1건당 받을 총액(atomic). USDC 6dp 기준 $1 = `'1000000'`. 수수료는 여기서 차감된다. */
-    amount: string;
+    /**
+     * 호출 1건당 받을 총액. **사람 표기 문자열**이다 — `'0.1'`, `'1'`, `'29.00'`.
+     * 체인·토큰 decimals 를 계산할 필요가 없다(체크아웃 `line_items[].amount` 와 같은 모델).
+     * 수수료는 이 금액에서 차감된다. raw atomic 을 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+     */
+    amount?: string;
+    /** raw atomic 정수 문자열(고급). USDC 6dp 기준 $1 = `'1000000'`. `amount` 와 상호 배타. */
+    amountAtomic?: string;
     /** 생략 시 API 키 모드의 기본 자산(현재 Base / Base Sepolia). */
     network?: string;
     /** 기본 `'USDC'`. */

package/dist/index.d.ts

@@ -556,8 +556,20 @@ declare class BitPalCheckoutClient {
      * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
      */
     getStatus(sessionId: string): Promise<ApiResponse<SessionStatus>>;
-    /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
-    previewFee(amount: string): Promise<ApiResponse<FeePreview>>;
+    /**
+     * 수수료 미리보기 — `/v1/checkout/fee-preview`.
+     *
+     * `amount` 는 **사람 표기**다("100", "0.5") — line item / Price / x402 와 같은 모델이라
+     * decimals 를 계산할 필요가 없다. raw μUSD 를 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+     * 응답은 계속 atomic 이다(계산 결과라 정밀도가 곧 계약이다).
+     *
+     * @example
+     * const { data } = await bp.checkout.previewFee('100');       // $100
+     * const { data } = await bp.checkout.previewFee({ amountAtomic: '100000000' });
+     */
+    previewFee(amount: string | {
+        amountAtomic: string;
+    }): Promise<ApiResponse<FeePreview>>;
 }
 declare class BitPalError extends Error {
     readonly statusCode: number;
@@ -572,7 +584,7 @@ declare class BitPalError extends Error {
 /**
  * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
  */
-declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved"];
 type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
 /**
  * Canonical envelope (HTTP body).
@@ -785,8 +797,14 @@ interface X402GateOptions {
     apiKey: string;
     /** 정산 지갑. 콘솔에 등록한 payout 주소와 같은 값이어야 한다. */
     payTo: string;
-    /** 호출 1건당 받을 총액(atomic). USDC 6dp 기준 $1 = `'1000000'`. 수수료는 여기서 차감된다. */
-    amount: string;
+    /**
+     * 호출 1건당 받을 총액. **사람 표기 문자열**이다 — `'0.1'`, `'1'`, `'29.00'`.
+     * 체인·토큰 decimals 를 계산할 필요가 없다(체크아웃 `line_items[].amount` 와 같은 모델).
+     * 수수료는 이 금액에서 차감된다. raw atomic 을 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+     */
+    amount?: string;
+    /** raw atomic 정수 문자열(고급). USDC 6dp 기준 $1 = `'1000000'`. `amount` 와 상호 배타. */
+    amountAtomic?: string;
     /** 생략 시 API 키 모드의 기본 자산(현재 Base / Base Sepolia). */
     network?: string;
     /** 기본 `'USDC'`. */

package/dist/index.js

@@ -256,12 +256,23 @@ var BitPalCheckoutClient = class {
     );
   }
   /* ─── Fees ─── */
-  /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+  /**
+   * 수수료 미리보기 — `/v1/checkout/fee-preview`.
+   *
+   * `amount` 는 **사람 표기**다("100", "0.5") — line item / Price / x402 와 같은 모델이라
+   * decimals 를 계산할 필요가 없다. raw μUSD 를 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+   * 응답은 계속 atomic 이다(계산 결과라 정밀도가 곧 계약이다).
+   *
+   * @example
+   * const { data } = await bp.checkout.previewFee('100');       // $100
+   * const { data } = await bp.checkout.previewFee({ amountAtomic: '100000000' });
+   */
   async previewFee(amount) {
-    return this.request(
-      "GET",
-      `/v1/checkout/fee-preview?amount=${encodeURIComponent(amount)}`
-    );
+    const qs = typeof amount === "string" ? `amount=${encodeURIComponent(amount)}` : `amount_atomic=${encodeURIComponent(amount.amountAtomic)}`;
+    if (typeof amount === "string" && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(amount)) {
+      throw new Error('[BitPal] previewFee: amount must be a decimal string like "100" or "0.5" (max 6 decimals). For raw \u03BCUSD use { amountAtomic }.');
+    }
+    return this.request("GET", `/v1/checkout/fee-preview?${qs}`);
   }
 };
 var BitPalError = class extends Error {
@@ -281,7 +292,12 @@ var CHECKOUT_WEBHOOK_EVENTS = [
   "checkout.session.settled",
   "checkout.session.expired",
   "checkout.session.unresolved",
-  "checkout.refund.recorded"
+  "checkout.refund.recorded",
+  // x402 결제의 **사후** 확정. 정상 경로(/settle 이 그 자리에서 결과를 반환)는 발행되지 않는다 —
+  //   이미 아는 결과를 중복으로 받지 않게 하기 위함이다. /settle 이 503 을 반환해 결과를 모른 채
+  //   남았을 때, reconciler 가 체인을 보고 종결시키면 이 이벤트가 온다.
+  //   payload: { payment_id, status: 'confirmed'|'reverted'|'expired', tx_hash, resource, amount, … }
+  "x402.payment.resolved"
 ];
 var WEBHOOK_HEADERS = {
   signature: "X-Webhook-Signature-256",
@@ -417,8 +433,16 @@ var X402Gate = class {
     if (!/^0x[a-fA-F0-9]{40}$/.test(opts.payTo)) {
       throw new Error("[BitPal] x402: payTo must be a 0x EVM address (your registered payout wallet).");
     }
-    if (!/^\d+$/.test(opts.amount)) {
-      throw new Error('[BitPal] x402: amount must be an atomic integer string (USDC 6dp, $1 = "1000000").');
+    const hasHuman = opts.amount != null;
+    const hasAtomic = opts.amountAtomic != null;
+    if (hasHuman === hasAtomic) {
+      throw new Error('[BitPal] x402: provide exactly one of `amount` ("0.1") or `amountAtomic` ("100000").');
+    }
+    if (hasHuman && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(opts.amount)) {
+      throw new Error('[BitPal] x402: amount must be a decimal string like "0.1" or "29" (max 6 decimals).');
+    }
+    if (hasAtomic && !/^\d+$/.test(opts.amountAtomic)) {
+      throw new Error('[BitPal] x402: amountAtomic must be an integer string (USDC 6dp, $1 = "1000000").');
     }
     const timeoutSeconds = opts.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
     if (timeoutSeconds < MIN_VALIDITY_SECONDS || timeoutSeconds > MAX_VALIDITY_SECONDS) {
@@ -436,7 +460,8 @@ var X402Gate = class {
   async requirements(resource) {
     return this.request("POST", "/v1/x402/requirements", {
       payTo: this.opts.payTo,
-      amount: this.opts.amount,
+      // 사람 표기 → atomic 변환은 **서버가** 한다. SDK 가 decimals 를 알 필요가 없다.
+      ...this.opts.amount != null ? { amount: this.opts.amount } : { amountAtomic: this.opts.amountAtomic },
       resource,
       ...this.opts.network ? { network: this.opts.network } : {},
       ...this.opts.asset ? { asset: this.opts.asset } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "BitPal Checkout SDK — non-custodial crypto checkout: create sessions, issue per-order deposit addresses, poll status, verify signed webhooks, and charge per API call with x402.",
   "license": "MIT",
   "repository": {