@bitpal/checkout 0.8.0 → 0.9.0

package/README.md

@@ -208,7 +208,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
 });
@@ -267,6 +267,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 {
@@ -476,8 +487,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 +514,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;
@@ -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;
@@ -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 {
@@ -417,8 +428,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 +455,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.9.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": {